diff --git a/migration/README.md b/migration/README.md index 90bad72..f64667f 100644 --- a/migration/README.md +++ b/migration/README.md @@ -5,6 +5,7 @@ Schritt-für-Schritt-Anleitungen für Updates und Optimierungen — **noch nicht | Dokument | Inhalt | |----------|--------| | [nextcloud-optimierung-und-updates.md](nextcloud-optimierung-und-updates.md) | Nextcloud auf VM 101: Versionsstand, Minor-Update, Tuning, notify_push, DB-Indizes | +| [nextcloud-tuning-freigabe.md](nextcloud-tuning-freigabe.md) | **Zur Absegnung:** PHP-FPM, APCu, Cron — geplante Änderungen | **Ist-Doku (Status quo):** [../pve1/06_ubuntu-vm-nextcloud.md](../pve1/06_ubuntu-vm-nextcloud.md) diff --git a/migration/nextcloud-tuning-freigabe.md b/migration/nextcloud-tuning-freigabe.md new file mode 100644 index 0000000..3bfd37e --- /dev/null +++ b/migration/nextcloud-tuning-freigabe.md @@ -0,0 +1,306 @@ +# Freigabe: Nextcloud Tuning (Phase F + G) + +**Status:** ⏳ **Zur Absegnung — noch nicht umgesetzt** +**Erstellt:** 2026-06-28 +**Betrifft:** VM 101 ubuntu · Container `nextcloud` · **kein** Version-Upgrade + +Dieses Dokument beschreibt **exakt**, was geändert werden soll, **warum** (mit Quellen), welche **Risiken** bestehen und wie **Rollback** funktioniert. Erst nach deiner Freigabe wird umgesetzt. + +**Bezug:** [nextcloud-optimierung-und-updates.md](nextcloud-optimierung-und-updates.md) · Ist-Zustand: [../pve1/06_ubuntu-vm-nextcloud.md](../pve1/06_ubuntu-vm-nextcloud.md) + +--- + +## Kurzfassung + +| Was | Warum | +|-----|-------| +| PHP-FPM: mehr Worker + Timeout | Default `pm.max_children=5` — **direkte Ursache** des CPU-Incidents (offizielle Nextcloud-Doku) | +| APCu: 32 MB → 128 MB | Nextcloud Admin Manual empfiehlt 128 MB Startwert | +| System-Cron alle 5 min | Entlastet Web-Requests; offizielle Empfehlung statt AJAX-Cron | + +**Nicht in diesem Schritt:** notify_push, Image-Update 34.0.1, compose.yml, config.php + +**Erwartete Unterbrechung:** ~5–15 s beim `docker restart nextcloud` (bestehende Syncs können kurz abbrechen) + +--- + +## Ist-Zustand (gemessen 2026-06-28) + +| Parameter | Aktuell | Quelle | +|-----------|---------|--------| +| `pm.max_children` | **5** | Container-Default | +| `pm.start_servers` | 2 | Default | +| `request_terminate_timeout` | **nicht gesetzt** (∞) | — | +| `pm.max_requests` | **0** (kein Recycle) | Default | +| `apc.shm_size` | **32M** | PHP-Default | +| Background-Jobs | vermutlich AJAX/Web (kein System-Cron) | keine root-crontab | +| PHP-FPM Worker RSS (idle/light) | **~85–93 MB** | 3 Worker gemessen | +| VM RAM gesamt | 7,7 GB | `free -h` | +| VM RAM verfügbar | ~4,2 GB | zum Messzeitpunkt | +| Nextcloud-Container idle | ~104 MB | `docker stats` | + +**Hinweis:** Die VM hostet **viele** weitere Container (Airsonic ~1 GB, Gitea ~700 MB, Collabora ~530 MB, …). PHP-FPM-Limits deshalb **konservativ** gewählt, nicht maximal. + +--- + +## Geplante Änderungen + +### 1. Datei: `/opt/stacks/nextcloud/config/php/www2.conf` + +**Aktuell:** nur Kommentare, `[www]`-Header — es gelten Container-Defaults. + +**Geplant (vollständiger neuen Inhalt):** + +```ini +; Edit this file to override www.conf and php-fpm.conf directives and restart the container +; Freigabe 2026-06-28 — siehe docu/migration/nextcloud-tuning-freigabe.md + +; Pool name +[www] + +; dynamic = empfohlen für Nextcloud (nicht ondemand — sonst Cold-Start bei jedem Client-Poll) +; Quelle: Nextcloud 34 Server Tuning Manual +pm = dynamic + +pm.max_children = 12 +pm.start_servers = 3 +pm.min_spare_servers = 2 +pm.max_spare_servers = 6 + +; Worker nach 500 Requests recyclen (Memory-Leaks in Extensions) +pm.max_requests = 500 + +; Hängende Requests nach 300s beenden — verhindert „ewig blockierte“ Worker wie am 28.06. +; Quelle: Nextcloud Server Tuning, gängige Praxis bei WebDAV/Sync +request_terminate_timeout = 300 + +; Optional: langsame Requests diagnostizieren (Log im Container) +request_slowlog_timeout = 10s +slowlog = /config/log/php/fpm-slow.log +``` + +#### Warum `pm.max_children = 12` (nicht 15 oder 30)? + +| Rechnung | Wert | +|----------|------| +| Gemessene Worker-Größe | ~90 MB | +| 12 Worker Peak | ~1,1 GB nur PHP-FPM | +| + MariaDB, Redis, Nginx im Stack | ~400 MB | +| + andere Container auf der VM | ~3 GB+ | +| Puffer für NFS/OS | nötig | + +Formel laut [Nextcloud Server Tuning](https://docs.nextcloud.com/server/stable/admin_manual/installation/server_tuning.html): + +``` +pm.max_children = floor(RAM_für_PHP / durchschnittlicher_Worker_RSS) +``` + +Offizielle Doku nennt **50–100 MB/Worker** und warnt: zu hoch → Swapping, schlimmer als Queuing. + +**12** ist ein **konservativer Startwert** für eine **Multi-Service-VM** (nicht dedizierter Nextcloud-Server). Bei stabilen Metriken kann später auf 15 erhöht werden. + +Referenzen: + +- [Nextcloud 34 — Server tuning / PHP-FPM](https://docs.nextcloud.com/server/stable/admin_manual/installation/server_tuning.html) — Default 5 als „common cause of gateway timeouts“ +- [Linuxserver www2.conf](https://github.com/linuxserver/docker-nextcloud/issues/68#issuecomment-462000000) — offizieller Override-Pfad + +--- + +### 2. Datei: `/opt/stacks/nextcloud/config/php/php-local.ini` + +**Aktuell:** + +```ini +; Edit this file to override php.ini directives + +date.timezone = Etc/UTC +``` + +**Geplant (Ergänzung):** + +```ini +; Edit this file to override php.ini directives + +date.timezone = Etc/UTC + +; Nextcloud Admin Manual: Default 32M zu klein, Startwert 128M +; https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/caching_configuration.html +apc.shm_size=128M +``` + +**Keine weiteren php.ini-Änderungen** in diesem Schritt (kein `memory_limit`, kein OPcache-Tuning — Redis/APCu/OPcache sind bereits aktiv). + +**Hinweis Linuxserver:** Es gibt vereinzelte GitHub-Issues, dass `php-local.ini` in manchen Image-Versionen von `nextcloud.ini` überstimmt wird. Nach dem Restart prüfen wir mit `php -i | grep apc.shm_size` — falls wirkungslos, Alternative: Umgebungsvariable `PHP_MEMORY_LIMIT` / Image-Dokumentation. + +--- + +### 3. System-Cron auf VM 101 (root) + +**Aktuell:** keine root-crontab. + +**Geplant:** + +```cron +# Nextcloud Background-Jobs — alle 5 Minuten +# Quelle: https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/background_jobs_configuration.html +*/5 * * * * docker exec -u abc nextcloud php /app/www/public/occ background:cron >> /var/log/nextcloud-cron.log 2>&1 +``` + +**Zusätzlich einmalig per occ:** + +```bash +docker exec -u abc nextcloud php /app/www/public/occ background:cron +``` + +Das setzt den Modus intern auf **Cron** (Alternative: Admin-UI → Grundeinstellungen → Hintergrundjobs → Cron). + +**Warum:** AJAX-Cron läuft bei jedem Seitenaufruf mit und erzeugt zusätzliche PHP-Requests. System-Cron ist die [offizielle Empfehlung](https://docs.nextcloud.com/server/stable/admin_manual/installation/server_tuning.html) für Produktivbetrieb. + +--- + +## Was bewusst NICHT geändert wird + +| Item | Grund | +|------|-------| +| `compose.yml` / Docker-Image | kein Update in diesem Schritt | +| `config.php` | Redis/APCu bereits korrekt konfiguriert | +| Nginx `default.conf` | keine Timeout-Änderung (erst bei Bedarf) | +| notify_push | eigene Freigabe-Phase (größerer Eingriff) | +| Client-Updates | optional, nicht nötig für Server-Fix | +| MariaDB-Tuning | out of scope | + +--- + +## Risiken & Mitigation + +| Risiko | Einschätzung | Mitigation | +|--------|--------------|------------| +| Kurze Unterbrechung beim Restart | gering | nachts / bei wenig Sync-Traffic | +| `request_terminate_timeout=300` bricht langsame Syncs ab | mittel | 300s ist Standard für WebDAV; NFS-Ops >5min würden abbrechen — Slowlog zeigt das | +| 12 Worker reichen nicht | mittel | Monitoring; bei Bedarf auf 15 erhöhen | +| 12 Worker zu viel RAM | gering | konservative Rechnung; kein Swap auf VM (0 B!) — bei OOM würde Kernel Prozesse killen | +| APCu 128M „verschwendet“ RAM | sehr gering | 96 MB Mehrverbrauch vs. Default | +| Cron-Job schlägt fehl | gering | Log `/var/log/nextcloud-cron.log`; Admin-UI zeigt letzten Cron-Lauf | + +--- + +## Rollback + +| Änderung | Rollback | +|----------|----------| +| `www2.conf` | alten Inhalt wiederherstellen (leer + `[www]`) → `docker restart nextcloud` | +| `php-local.ini` | `apc.shm_size`-Zeile entfernen → Restart | +| Crontab | `crontab -e` → Zeile löschen | + +Kein DB-Rollback nötig. Kein Image-Downgrade. + +--- + +## Verifikation nach Umsetzung (Checkliste) + +```bash +# 1. PHP-FPM-Werte +docker exec nextcloud cat /etc/php84/php-fpm.d/www.conf | grep -E "^pm\.|^request_terminate" + +# 2. APCu +docker exec nextcloud php -i | grep apc.shm_size + +# 3. Cron-Modus +docker exec -u abc nextcloud php /app/www/public/occ config:system:get backgroundjobs_mode + +# 4. Cron-Log (nach 5–10 min) +tail -20 /var/log/nextcloud-cron.log + +# 5. Last / Worker +docker exec nextcloud ps aux | grep "php-fpm: pool" +docker stats nextcloud --no-stream + +# 6. Keine pm.max_children-Warnung mehr in php error.log +docker exec nextcloud tail -20 /config/log/php/error.log +``` + +**Erfolgskriterien:** + +- [ ] `pm.max_children = 12` aktiv +- [ ] `apc.shm_size = 128M` aktiv +- [ ] Cron-Log zeigt regelmäßige Läufe ohne Fehler +- [ ] Kein erneutes „server reached pm.max_children (5)“ im Log +- [ ] CPU unter Normal-Last stabil (keine 5 Worker bei 100 % über Stunden) + +--- + +## Umsetzungs-Befehle (nach Freigabe) + +Werden **erst nach OK** ausgeführt — zur Transparenz hier dokumentiert: + +```bash +# Auf pve1 via Guest Agent oder SSH root@192.168.10.10 + +# --- www2.conf schreiben --- +cat > /opt/stacks/nextcloud/config/php/www2.conf << 'EOF' +; Edit this file to override www.conf and php-fpm.conf directives and restart the container +; Freigabe 2026-06-28 — siehe docu/migration/nextcloud-tuning-freigabe.md + +[www] +pm = dynamic +pm.max_children = 12 +pm.start_servers = 3 +pm.min_spare_servers = 2 +pm.max_spare_servers = 6 +pm.max_requests = 500 +request_terminate_timeout = 300 +request_slowlog_timeout = 10s +slowlog = /config/log/php/fpm-slow.log +EOF + +# --- php-local.ini ergänzen --- +grep -q 'apc.shm_size' /opt/stacks/nextcloud/config/php/php-local.ini || \ + echo 'apc.shm_size=128M' >> /opt/stacks/nextcloud/config/php/php-local.ini + +# --- Container restart --- +docker restart nextcloud + +# --- Cron --- +(crontab -l 2>/dev/null | grep -v 'occ background:cron'; \ + echo '*/5 * * * * docker exec -u abc nextcloud php /app/www/public/occ background:cron >> /var/log/nextcloud-cron.log 2>&1') | crontab - + +docker exec -u abc nextcloud php /app/www/public/occ background:cron +``` + +--- + +## Freigabe + +| | | +|---|---| +| ☐ | **Freigegeben** — Phase F+G wie oben umsetzen | +| ☐ | **Anpassung** — z. B. `pm.max_children` auf 15 statt 12 | +| ☐ | **Abgelehnt / später** | + +**Freigegeben von:** _______________ +**Datum:** _______________ +**Anmerkungen:** _______________ + +--- + +## Nächste Phase (separate Freigabe) + +**notify_push** (Rust HPB) — eigener Change-Request, weil: + +- compose.yml-Erweiterung +- NPM Custom Location `/push` +- neuer Container + App-Installation + +Siehe [nextcloud-optimierung-und-updates.md §7](nextcloud-optimierung-und-updates.md). + +--- + +## Quellen (Web-Recherche) + +| Thema | URL | +|-------|-----| +| PHP-FPM Tuning (offiziell NC 34) | https://docs.nextcloud.com/server/stable/admin_manual/installation/server_tuning.html | +| APCu 128M Empfehlung | https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/caching_configuration.html | +| Background Jobs / Cron | https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/background_jobs_configuration.html | +| Linuxserver www2.conf / php-local.ini | https://github.com/linuxserver/docker-nextcloud/issues/68 | +| PHP-FPM max_children Praxis | https://perlod.com/tutorials/php-fpm-max-children/ | diff --git a/pve1/06_ubuntu-vm-nextcloud.md b/pve1/06_ubuntu-vm-nextcloud.md index 521321e..09177ce 100644 --- a/pve1/06_ubuntu-vm-nextcloud.md +++ b/pve1/06_ubuntu-vm-nextcloud.md @@ -238,7 +238,8 @@ cd /opt/stacks/nextcloud && docker compose ps ## Offene Punkte / TODO (Betreiber) -Details und Befehle: **[migration/nextcloud-optimierung-und-updates.md](../migration/nextcloud-optimierung-und-updates.md)** +Details und Befehle: **[migration/nextcloud-optimierung-und-updates.md](../migration/nextcloud-optimierung-und-updates.md)** +Freigabe Phase F+G: **[migration/nextcloud-tuning-freigabe.md](../migration/nextcloud-tuning-freigabe.md)** - [ ] Backup + Image-Tag pinnen + Minor 34.0.1 - [ ] PHP-FPM `www2.conf` anpassen und Container restart