docu/migration/nextcloud-tuning-freigabe.md

# Freigabe: Nextcloud Tuning (Phase F + G)

**Status:** ✅ **Umgesetzt am 2026-06-28** (freigegeben durch Betreiber)  
**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:**

- [x] `pm.max_children = 12` aktiv (`php-fpm84 -tt`)
- [x] `apc.shm_size = 128M` aktiv
- [x] Cron-Job in root-crontab
- [x] VM-RAM 12 GB (11 GiB sichtbar im Gast)
- [ ] Langzeit: kein erneutes „server reached pm.max_children (5)“ im Log

---

## 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:** Betreiber (Chat 2026-06-28)  
**Datum:** 2026-06-28  
**Anmerkungen:** Zusätzlich VM-RAM 8 → 12 GB (`qm set 101 -memory 12288`, Neustart). Container-Recreate nötig damit PHP-FPM www2.conf greift (restart allein reichte nicht).

---

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