docu/migration/nextcloud-optimierung-und-updates.md

Nextcloud — Optimierung & Updates (Schritt für Schritt)

Ziel: Server-seitige Stabilität nach CPU-Incident 2026-06-28, ohne unnötiges Major-Upgrade.
Instanz: VM 101 ubuntu · cloud.jeanavril.com · Stack /opt/stacks/nextcloud/
Verifiziert am: 2026-06-28

---

0. Ausgangslage (verifiziert)

Vor jeder Änderung wurde der Stand per occ geprüft:

qm guest exec 101 -- docker exec -u abc nextcloud php /app/www/public/occ status
qm guest exec 101 -- docker exec -u abc nextcloud php /app/www/public/occ config:system:get version

Feld	Wert
versionstring	34.0.0 (intern 34.0.0.12)
needsDbUpgrade	false
maintenance	false
Docker-Image	lscr.io/linuxserver/nextcloud:latest
Hub-Marketing	Hub 26 Spring (Juni 2026)
ADA Engine	bereits enthalten (seit NC 33 / Hub 26 Winter)

Versions-Mapping (wichtig)

Hub-Name und Server-Versionsnummer sind entkoppelt:

Server-Version	Hub-Name	ADA Engine
NC 32	Hub 25 Autumn	nein
NC 33	Hub 26 Winter	ja (Debüt)
NC 34	Hub 26 Spring	ja (weiterentwickelt)

Konsequenz: Es gibt kein anstehendes Major-Upgrade „für ADA“. Ihr seid auf der aktuellen Major-Version. Offen ist:

• Minor-Patch 34.0.0 → 34.0.1 (Security/Bugfixes)
• Betriebs-Tuning (PHP-FPM, notify_push, Cron)
• Image-Tag pinnen statt :latest

Der frühere Roadmap-Punkt „Upgrade auf Hub 26 für ADA“ war falsch (Verwechslung Hub-Name ↔ NC-Nummer).

Was ADA bei euch bringt — und was nicht

ADA-Vorteil	Relevanz bei euch
Previews aus File-Cache getrennt (~56 % kleinere oc_filecache)	mittel (188k Zeilen in DB, aber 93 TB NFS-Daten)
Authoritative Mount Points (~30 % schneller bei Freigaben)	hoch bei vielen Shares
Schlankerer Dateizugriff (~60 % bei freigegebenen Ordnern)	hoch
Weniger Preview-Ressourcen (40–90 %)	hoch
Direkte S3-Downloads (Thumbnails 2–10× schneller)	nein — Daten liegen auf NFS/mergerfs, nicht S3

---

1. Backup (Pflicht vor jedem Image-Update)

Nextcloud unterstützt kein Downgrade. Vor Image-Wechsel oder Major-Sprung:

1.1 VM-Snapshot (pve1)

# Auf pve1 — Snapshot der ganzen VM (schnellster Rollback)
qm snapshot 101 pre-nextcloud-update-$(date +%Y%m%d) --description "Vor NC Update/Tuning"

1.2 MariaDB-Dump

qm guest exec 101 -- bash -c 'docker exec nextcloud-db-1 mariadb-dump -u root -p"$MYSQL_ROOT_PASSWORD" --single-transaction nextcloud' > /root/backups/nextcloud-db-$(date +%Y%m%d).sql

(Passwort aus /opt/stacks/nextcloud/compose.yml bzw. db.env — nicht in Git committen.)

1.3 Config sichern

qm guest exec 101 -- tar czf /root/backups/nextcloud-config-$(date +%Y%m%d).tar.gz -C /opt/stacks/nextcloud config

1.4 Maintenance-Fenster einplanen

• Image-Update → Container startet ggf. automatische DB-Migration (Maintenance-Mode, User gesperrt)
• Große Instanzen: Stunden möglich
• Nach Major-Upgrade: Background-Migrationen laufen weiter → occ background:cron mehrfach ausführen bevor der nächste Major-Sprung

---

2. Image-Tag pinnen (Schutz vor ungeplantem Upgrade)

Problem: :latest + automatischer Pull (Dockge, Watchtower, …) kann unbeabsichtigt migrieren — irreversibel.

Empfehlung: In /opt/stacks/nextcloud/compose.yml festen Tag setzen:

# Vorher:
# image: lscr.io/linuxserver/nextcloud:latest

# Nachher (Stand Juni 2026 — vor Pull aktuellen Tag prüfen):
image: lscr.io/linuxserver/nextcloud:34.0.1
# alternativ: lscr.io/linuxserver/nextcloud:version-34.0.1

Verfügbare Tags prüfen: https://hub.docker.com/r/linuxserver/nextcloud/tags

Linuxserver-Regeln:

• Nur ein Major-Sprung pro Image-Update (z. B. 33 → 34, nicht 32 → 34)
• Update = neues Image pullen + Container recreate (nicht Web-Updater / updater.phar)
• Tag previous = vorherige Major-Version (für schrittweises Upgrade)

cd /opt/stacks/nextcloud
docker compose pull
docker compose up -d
docker logs -f nextcloud   # Migration/Startup beobachten

---

3. Minor-Update 34.0.0 → 34.0.1

Risiko: niedrig (Bugfixes/Security). Sollte zeitnah erfolgen — CVEs erscheinen oft ~3 Wochen nach Minor-Release.

Schritte

1. Schritt 1 (Backup) ausführen
2. Tag in compose.yml auf 34.0.1 setzen (siehe oben)
3. Pull & Recreate (siehe oben)
4. Verifizieren:

qm guest exec 101 -- docker exec -u abc nextcloud php /app/www/public/occ status
qm guest exec 101 -- docker exec -u abc nextcloud php /app/www/public/occ check

5. Admin-UI: Warnungen, App-Kompatibilität, Logs

Kein separater Major-Migrationspfad nötig — ihr bleibt auf NC 34.

---

4. Datenbank-Indizes

4.1 Bekanntes ADA-Migrationsproblem (32 → 33)

Symptom nach Upgrade: hohe DB-CPU, langsame Instanz, Query:

DELETE FROM oc_filecache WHERE path_hash = ?

Ursache: Index fs_storage_path_hash ist zusammengesetzt (storage, path_hash). Reine path_hash-Lookups/DELETEs können Full Table Scan auslösen → Locks, Deadlocks.

Prüfen (aktueller Stand 2026-06-28):

qm guest exec 101 -- docker exec nextcloud-db-1 mariadb -u nextcloud -p nextcloud \
  -e "SHOW INDEX FROM oc_filecache WHERE Key_name LIKE '%path%';"

Bei uns vorhanden: fs_storage_path_hash (storage, path_hash) — kein separater path_hash-Only-Index.

Workaround (nur wenn Symptome auftreten):

CREATE INDEX fs_path_hash ON oc_filecache (path_hash);

Danach:

docker exec -u abc nextcloud php /app/www/public/occ db:add-missing-indices

4.2 Fehlende Indizes (bereits angewendet)

Am 2026-06-28 wurden per occ db:add-missing-indices u. a. folgende Indizes ergänzt:

• oc_properties — properties_name_path_user
• oc_systemtag_object_mapping — systag_objecttype
• oc_vcategory — unique_category_per_user
• oc_share — share_with_file_target_index
• oc_share_external — user_mountpoint_index
• oc_calendarobjects — calobjects_by_uid_index
• oc_cards_properties — cards_prop_abid_name_value
• oc_activity — activity_object_user

Status: erledigt. Bei künftigen Upgrades erneut:

docker exec -u abc nextcloud php /app/www/public/occ db:add-missing-indices
docker exec -u abc nextcloud php /app/www/public/occ db:convert-filecache-bigint   # falls empfohlen

---

5. PHP-FPM & APCu (Priorität 1)

Konfiguration liegt persistent unter /opt/stacks/nextcloud/config/php/ und wird in den Container gemountet.

5.1 /opt/stacks/nextcloud/config/php/www2.conf

Aktuell fast leer (Defaults: pm.max_children = 5 — Ursache des Incidents).

; Override default PHP-FPM limits
[www]
pm.max_children = 15
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6
request_terminate_timeout = 300
pm.max_requests = 500

RAM-Rechnung: ~80–100 MB/Worker → 15 Worker ≈ 1,2–1,5 GB — passt in VM mit 8 GB neben MariaDB/Redis.

5.2 /opt/stacks/nextcloud/config/php/php-local.ini

Aktuell nur date.timezone. Ergänzen:

date.timezone = Etc/UTC
apc.shm_size=128M

(Default im Container: 32 MB — Nextcloud empfiehlt ≥ 128 MB.)

5.3 Anwenden

# Auf VM 101
docker restart nextcloud

# Prüfen
docker exec nextcloud php -i | grep apc.shm_size
docker exec nextcloud cat /etc/php84/php-fpm.d/www.conf | grep pm.max

---

6. Background-Jobs auf System-Cron (Priorität 2)

6.1 Modus in Nextcloud setzen

docker exec -u abc nextcloud php /app/www/public/occ background:cron

Alternativ: Admin → Grundeinstellungen → Hintergrundjobs → Cron.

6.2 Crontab auf VM 101 (root)

crontab -e

# Nextcloud Background-Jobs alle 5 Minuten
*/5 * * * * docker exec -u abc nextcloud php /app/www/public/occ background:cron >> /var/log/nextcloud-cron.log 2>&1

6.3 Verifizieren

docker exec -u abc nextcloud php /app/www/public/occ config:system:get backgroundjobs_mode
docker exec -u abc nextcloud php /app/www/public/occ background:queue:status

---

7. notify_push — Rust High Performance Backend (Priorität 1)

Version Stand Recherche: v1.3.3 (Mai 2026) — Fix gegen DB-Query-Spitzen bei Cache-Invalidierung (relevant für euren Incident).

Effekt: Clients müssen seltener index.php/204 / status.php pollen → entlastet PHP-FPM unabhängig von Client-Version.

Voraussetzungen: Redis ✅ · Reverse Proxy (NPM) ✅ · App + Daemon

7.1 App installieren

docker exec -u abc nextcloud php /app/www/public/occ app:install notify_push
docker exec -u abc nextcloud php /app/www/public/occ app:enable notify_push

(App ggf. vorher im App-Store / manuell bereitstellen — NC 34 kompatibel.)

7.2 Sidecar-Container (empfohlen für Linuxserver-Setup)

In /opt/stacks/nextcloud/compose.yml ergänzen — Zugangsdaten aus db.env / compose.yml eintragen, nicht committen:

  notify_push:
    image: ghcr.io/nextcloud/notify_push:latest   # Tag zur NC-Version pinnen, z. B. v1.3.3
    container_name: nextcloud-notify-push
    restart: unless-stopped
    environment:
      - PORT=7867
      - NEXTCLOUD_URL=https://cloud.jeanavril.com
      # Compose-Service-Name ist "db", nicht der Container-Name
      - DATABASE_URL=mysql://nextcloud:<PASSWORT>@db:3306/nextcloud
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis
    networks:
      - default
      - docbr0    # falls NPM über docbr0 routen soll

cd /opt/stacks/nextcloud
docker compose up -d notify_push
docker logs nextcloud-notify-push

Hinweis: Offizielles Image/Binary-Release mit App-Version abstimmen — siehe https://github.com/nextcloud/notify_push/releases

Alternative ohne Docker-Image: statisches Binary notify_push-x86_64-unknown-linux-musl als Systemd-/Sidecar-Service.

7.3 NPM — Custom Location

Host cloud.jeanavril.com in Nginx Proxy Manager (10.2.2.254):

Feld	Wert
Location	/push
Scheme	http
Forward Host	IP/Name des notify_push-Containers (z. B. 10.2.2.x auf docbr0 oder Container-Name wenn NPM im gleichen Docker-Netz)
Forward Port	7867
Websockets	an

7.4 Setup & Test

docker exec -u abc nextcloud php /app/www/public/occ notify_push:setup
docker exec -u abc nextcloud php /app/www/public/occ notify_push:self-test

Optional separates Redis für Pub/Sub in config.php:

'notify_push_redis' => [
    'host' => 'redis',
    'port' => 6379,
],

7.5 Erfolgskontrolle

docker exec nextcloud tail -f /config/log/nginx/access.log | grep -E 'status\.php|index\.php/204'

Erwartung: deutlich weniger Treffer nach Aktivierung (Clients pollen seltener).

---

8. Empfohlene Reihenfolge (Gesamtplan)

Phase	Schritt	Risiko	Status
A	Version verifizieren (occ status)	—	✅ erledigt
B	Backup (Snapshot + DB + config)	—	☐ offen
C	Image-Tag pinnen (34.0.1)	niedrig	☐ offen
D	Minor-Update 34.0.0 → 34.0.1	niedrig	☐ offen
E	db:add-missing-indices	niedrig	✅ erledigt (2026-06-28)
F	PHP-FPM + APCu (Schritt 5)	niedrig	☐ offen
G	System-Cron (Schritt 6)	niedrig	☐ offen
H	notify_push (Schritt 7)	mittel	☐ offen
I	fs_path_hash-Index nur bei DB-Symptomen	mittel	☐ beobachten
J	Client-Updates	optional	☐ optional

Begründung Reihenfolge: Erst Backup + kontrolliertes Minor-Update, dann Tuning das den CPU-Incident verhindert (FPM, notify_push). Major-Upgrade aktuell nicht nötig.

---

9. Rollback

Änderung	Rollback
PHP-FPM / APCu	Dateien zurücksetzen, docker restart nextcloud
notify_push	Container stoppen, App deaktivieren, NPM-Location entfernen
Minor-Update 34.0.1	Nicht supported — VM-Snapshot oder DB+Config-Restore
DB-Indizes	Normalerweise nicht zurückrollen

---

10. Referenzen

Thema	URL
Linuxserver Update-Regeln	https://docs.linuxserver.io/images/docker-nextcloud/
Linuxserver Image-Änderung 2023	https://info.linuxserver.io/issues/2023-06-25-nextcloud/
notify_push	https://github.com/nextcloud/notify_push
ADA Engine Blog	https://nextcloud.com/blog/a-new-data-access-architecture-for-nextcloud-introducing-the-ada-engine/
Memory caching	https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/caching_configuration.html
Ist-Doku / Incident	../pve1/06_ubuntu-vm-nextcloud.md

---

Checkliste (zum Abhaken)

• Snapshot VM 101
• DB-Dump + Config-Archiv
• compose.yml: Image 34.0.1 statt latest
• Minor-Update durchgeführt, occ check OK
• www2.conf + php-local.ini angepasst
• Crontab für background:cron
• notify_push deployed + NPM /push + notify_push:setup OK
• Nginx-Log: Polling zurückgegangen
• Optional: Client-Updates