Doku: Freigabe-Dokument für Nextcloud PHP-FPM, APCu und Cron.

Konkrete geplante Änderungen mit Begründung aus offizieller Doku und
Messwerten der VM — zur Absegnung vor Umsetzung.

Co-authored-by: Cursor <cursoragent@cursor.com>

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)
 

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/ |

pve1/06_ubuntu-vm-nextcloud.md

@@ -239,6 +239,7 @@ 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)**  
+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