From 3b12324d4e189bc11b33e7120d61578b825586bc Mon Sep 17 00:00:00 2001 From: root Date: Sun, 28 Jun 2026 09:57:38 +0200 Subject: [PATCH] =?UTF-8?q?Doku:=20Freigabe-Dokument=20f=C3=BCr=20notify?= =?UTF-8?q?=5Fpush=20(Linuxserver=20Docker=20Mod).?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Empfohlener Weg ohne NPM-Änderung; Sidecar als Alternative dokumentiert. Co-authored-by: Cursor --- migration/README.md | 3 +- migration/nextcloud-notify-push-freigabe.md | 341 ++++++++++++++++++++ pve1/06_ubuntu-vm-nextcloud.md | 5 +- 3 files changed, 346 insertions(+), 3 deletions(-) create mode 100644 migration/nextcloud-notify-push-freigabe.md diff --git a/migration/README.md b/migration/README.md index f64667f..cc80db9 100644 --- a/migration/README.md +++ b/migration/README.md @@ -5,7 +5,8 @@ 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 | +| [nextcloud-tuning-freigabe.md](nextcloud-tuning-freigabe.md) | **Umgesetzt:** PHP-FPM, APCu, Cron (2026-06-28) | +| [nextcloud-notify-push-freigabe.md](nextcloud-notify-push-freigabe.md) | **Zur Absegnung:** notify_push via Linuxserver Docker Mod | **Ist-Doku (Status quo):** [../pve1/06_ubuntu-vm-nextcloud.md](../pve1/06_ubuntu-vm-nextcloud.md) diff --git a/migration/nextcloud-notify-push-freigabe.md b/migration/nextcloud-notify-push-freigabe.md new file mode 100644 index 0000000..27a9847 --- /dev/null +++ b/migration/nextcloud-notify-push-freigabe.md @@ -0,0 +1,341 @@ +# Freigabe: notify_push (Client Push / Rust HPB) + +**Status:** ⏳ **Zur Absegnung — noch nicht umgesetzt** +**Erstellt:** 2026-06-28 +**Betrifft:** VM 101 ubuntu · Container `nextcloud` · NPM · **kein** NC-Version-Upgrade + +Dieses Dokument beschreibt den geplanten Rollout von **notify_push** (High Performance Backend für Files, Rust-Daemon). Ziel: weniger Client-Polling (`index.php/204`, `status.php`) → weniger PHP-FPM-Last. + +**Voraussetzungen (bereits erfüllt):** + +| Voraussetzung | Status | +|---------------|--------| +| Redis in `config.php` | ✅ | +| PHP-FPM Tuning (12 Worker) | ✅ (2026-06-28) | +| VM RAM 12 GB | ✅ | +| Nginx `/push/`-Block im Nextcloud-Container | ✅ bereits in `default.conf` | +| NPM WebSocket-Header für `cloud.jeanavril.com` | ✅ bereits aktiv | + +--- + +## Kurzfassung + +| Was | Empfehlung | +|-----|------------| +| **Deploy-Methode** | **Linuxserver Docker Mod** (nicht separater Sidecar) | +| **Compose-Änderung** | 1 Zeile: `DOCKER_MODS=linuxserver/mods:nextcloud-notify-push` | +| **NPM-Änderung** | **Keine** — `/push/` wird im Nextcloud-Container terminiert | +| **App** | `notify_push` v1.3.3 (NC 34 kompatibel) | +| **Erwarteter Effekt** | Deutlich weniger Polling-Requests in Nginx-Logs | + +--- + +## Warum notify_push? + +**Problem heute:** Desktop- und Mobile-Clients fragen regelmäßig den Server ab, ob sich Dateien geändert haben (`GET /index.php/204`, `GET /status.php`). Das erzeugt dauerhaft PHP-FPM-Last — unabhängig von der Client-Version. + +**Lösung:** Der Rust-Daemon hält WebSocket-Verbindungen offen und **pusht** Änderungen an Clients. Clients pollen seltener (best-effort, Polling bleibt als Fallback). + +**Relevanz für euren Incident (28.06.2026):** v1.3.3 enthält Fixes gegen DB-Query-Spitzen bei Cache-Invalidierung — passt zum beobachteten Lastmuster. + +Quellen: + +- https://github.com/nextcloud/notify_push +- https://apps.nextcloud.com/apps/notify_push (v1.3.3 für NC 34) +- https://nextcloud.com/blog/… (ADA/HPB Files v2 Kontext) + +--- + +## Architektur nach Umsetzung + +``` +Client (Desktop/Android) + │ wss://cloud.jeanavril.com/push/… + ▼ +NPM (10.2.2.254) ← TLS, WebSocket-Upgrade (bereits konfiguriert) + │ http://10.2.2.253:80 + ▼ +Nextcloud-Container (10.2.2.253) + ├── Nginx location ^~ /push/ → 127.0.0.1:7867 + └── notify_push (Rust) ← via Docker Mod, Port 7867 intern + │ + ├── Redis (nextcloud-redis-1) ← Pub/Sub + └── MariaDB (nextcloud-db-1) +``` + +**Kein neuer externer Port.** Der Push-Daemon läuft **im** Nextcloud-Container (Mod), nicht als separater öffentlicher Dienst. + +--- + +## Empfohlene Methode: Linuxserver Docker Mod + +Ihr nutzt `lscr.io/linuxserver/nextcloud:latest`. Linuxserver bietet dafür einen **offiziellen Mod** an — der passt besser als ein separater Sidecar-Container: + +| | Docker Mod (empfohlen) | Separater Sidecar | +|--|------------------------|-------------------| +| Wartung | offiziell von Linuxserver | manuell (Binary-Version, Netzwerk) | +| Nginx `/push/` | bereits in `default.conf` | NPM Custom Location nötig | +| `trusted_proxies`-Probleme | selten (Push lokal im Container) | häufig (GitHub #663) | +| Compose-Änderung | 1 Env-Variable | neuer Service + Netzwerk | + +Mod-Doku: https://github.com/linuxserver/docker-mods/tree/nextcloud-notify-push + +--- + +## Geplante Änderungen (Detail) + +### 1. `/opt/stacks/nextcloud/compose.yml` + +**Nur** beim Service `nextcloud` unter `environment` ergänzen: + +```yaml + nextcloud: + # … bestehende Einträge … + environment: + - PUID=33 + - PGID=33 + - TZ=Etc/UTC + - DOCKER_MODS=linuxserver/mods:nextcloud-notify-push # NEU +``` + +**Nicht ändern:** `db`, `redis`, `collabora`, Volumes, Netzwerke, Image-Tag. + +### 2. Container neu erstellen (nur `nextcloud`) + +```bash +cd /opt/stacks/nextcloud +docker compose pull nextcloud +docker compose up -d --force-recreate nextcloud +``` + +**Hinweis:** Wie beim PHP-FPM-Tuning reicht `docker restart` **nicht** — Mod wird beim Container-**Erstellen** geladen. + +**Erwartete Unterbrechung:** ~10–30 s für Nextcloud (Clients reconnecten automatisch). + +### 3. App installieren & aktivieren + +```bash +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 +``` + +(Falls App-Store nicht erreichbar: manuell v1.3.3 von https://apps.nextcloud.com/apps/notify_push) + +### 4. Setup-Wizard + +```bash +docker exec -u abc nextcloud php /app/www/public/occ notify_push:setup https://cloud.jeanavril.com/push +``` + +Der Wizard prüft automatisch: Erreichbarkeit, WebSocket, Reverse Proxy, Redis. + +### 5. Logs prüfen + +```bash +docker logs nextcloud 2>&1 | grep -i notify +# Erwartet: "**** Starting notify-push ****" +``` + +--- + +## NPM — bewusst keine Änderung + +Aktueller Stand (`/opt/stacks/npm/data/nginx/proxy_host/1.conf`): + +- Forward: `http://10.2.2.253:80` +- WebSocket-Header: **bereits gesetzt** (`Upgrade`, `Connection`, `http/1.1`) +- Kein separater Custom Location `/push` nötig + +Der `/push/`-Pfad wird vom **internen Nginx** im Nextcloud-Container an den Mod-Daemon weitergeleitet (Block existiert bereits): + +```nginx +location ^~ /push/ { + proxy_pass http://127.0.0.1:7867/; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; +} +``` + +--- + +## Bekannte Stolpersteine & Fallbacks + +### „push server is not a trusted proxy“ + +`trusted_proxies` in `config.php` enthält bereits: + +- `10.1.1.1` +- `10.2.2.254` (NPM) + +Falls `notify_push:setup` den Test dennoch fehlschlägt: + +1. IP aus der Fehlermeldung in `trusted_proxies` aufnehmen (oft `127.0.0.1` bei Mod-Setup) +2. Per occ (Beispiel — exakte IP aus Setup-Output nehmen): + +```bash +docker exec -u abc nextcloud php /app/www/public/occ config:system:set trusted_proxies 2 --value=127.0.0.1 +``` + +3. Setup erneut ausführen + +Quelle: https://github.com/nextcloud/notify_push#push-server-is-not-a-trusted-proxy + +### Mod startet nicht + +- Redis erreichbar? (`docker exec nextcloud-redis-1 redis-cli ping`) +- Container-Log auf Fehler prüfen +- ggf. `default.conf` neu generieren (nur wenn `/push/`-Block fehlt): + +```bash +# Nur wenn Block fehlt — bei uns vorhanden, normalerweise NICHT nötig: +mv /opt/stacks/nextcloud/config/nginx/site-confs/default.conf /opt/stacks/nextcloud/config/nginx/site-confs/default.conf.bak +docker compose up -d --force-recreate nextcloud +``` + +### App-Store nicht erreichbar + +Bekanntes Log-Thema (Timeout zu apps.nextcloud.com). App kann manuell installiert werden — kein Blocker für notify_push selbst. + +--- + +## Was bewusst NICHT geändert wird + +| Item | Grund | +|------|-------| +| `config.php` Redis-Einträge | bereits korrekt | +| Separates Redis für `notify_push_redis` | optional, Phase 2 — erst bei Last-Problemen | +| NPM Compose / Custom Locations | nicht nötig mit Mod | +| NC Minor-Update 34.0.1 | separater Schritt | +| Desktop-Client-Updates | optional, nicht Voraussetzung | + +--- + +## Risiken + +| Risiko | Einschätzung | Mitigation | +|--------|--------------|------------| +| Kurze Cloud-Unterbrechung beim Recreate | gering | bei wenig Traffic umsetzen | +| Mod-Inkompatibilität nach Image-Update | mittel | Image-Tag pinnen (separates TODO) | +| Setup schlägt fehl (trusted_proxy) | mittel | Fallbacks oben | +| Mehr RAM im Nextcloud-Container | gering | ~20–50 MB für Rust-Daemon; VM hat 12 GB | +| Rollback nötig | gering | siehe unten | + +--- + +## Rollback + +1. `DOCKER_MODS`-Zeile aus `compose.yml` entfernen +2. `docker compose up -d --force-recreate nextcloud` +3. App deaktivieren: `occ app:disable notify_push` +4. Optional App deinstallieren: `occ app:remove notify_push` + +Kein DB-Rollback nötig. Keine NPM-Änderungen rückgängig zu machen. + +--- + +## Verifikation nach Umsetzung + +```bash +# 1. Daemon läuft +docker logs nextcloud 2>&1 | grep -i "notify-push" + +# 2. Setup OK +docker exec -u abc nextcloud php /app/www/public/occ notify_push:setup https://cloud.jeanavril.com/push + +# 3. Metriken (nach Client-Verbindung) +docker exec -u abc nextcloud php /app/www/public/occ notify_push:metrics + +# 4. Polling zurückgegangen? (24h beobachten) +docker exec nextcloud tail -f /config/log/nginx/access.log | grep -E 'status\.php|index\.php/204' +``` + +**Erfolgskriterien:** + +- [ ] `notify_push:setup` ohne Fehler +- [ ] Log: „Starting notify-push“ +- [ ] `notify_push:metrics` zeigt Verbindungen (sobald Clients online) +- [ ] Weniger `index.php/204` / `status.php` in Access-Log vs. vorher +- [ ] Kein erneuter PHP-FPM-Auslastungs-Incident unter Normal-Last + +--- + +## Empfohlene Reihenfolge + +| Schritt | Aktion | Dauer | +|---------|--------|-------| +| A | Optional: VM-Snapshot `pre-notify-push` | 1 min | +| B | `compose.yml`: `DOCKER_MODS` ergänzen | 1 min | +| C | `docker compose up -d --force-recreate nextcloud` | ~30 s | +| D | Log: Mod gestartet? | 1 min | +| E | App installieren + enable | 2 min | +| F | `notify_push:setup https://cloud.jeanavril.com/push` | 2 min | +| G | Bei Fehler: trusted_proxies anpassen | ggf. | +| H | Metriken + Access-Log 24h beobachten | laufend | + +**Optional vorher:** VM-Snapshot auf pve1 (`qm snapshot 101 pre-notify-push-YYYYMMDD`). + +--- + +## Umsetzungs-Befehle (nach Freigabe) + +```bash +# Auf VM 101 (als jean mit sudo) oder via SSH + +# A) compose.yml editieren — DOCKER_MODS Zeile hinzufügen (siehe oben) + +# B) Deploy +cd /opt/stacks/nextcloud +sudo docker compose pull nextcloud +sudo docker compose up -d --force-recreate nextcloud +sleep 15 +sudo docker logs nextcloud 2>&1 | tail -30 + +# C) App + Setup +sudo docker exec -u abc nextcloud php /app/www/public/occ app:install notify_push +sudo docker exec -u abc nextcloud php /app/www/public/occ app:enable notify_push +sudo docker exec -u abc nextcloud php /app/www/public/occ notify_push:setup https://cloud.jeanavril.com/push + +# D) Metriken +sudo docker exec -u abc nextcloud php /app/www/public/occ notify_push:metrics +``` + +--- + +## Alternative (nicht empfohlen): Separater Sidecar-Container + +Falls der Docker Mod Probleme macht, wäre ein separater Container mit `ghcr.io/nextcloud/notify_push` möglich — erfordert dann: + +- neuen Service in `compose.yml` mit `DATABASE_URL`, `REDIS_URL`, `NEXTCLOUD_URL` +- NPM Custom Location `/push` → Sidecar-IP:7867 +- `trusted_proxies` für Sidecar-Subnetz +- Netzwerk-Anbindung an `nextcloud_default` + ggf. `docbr0` + +**Für euren Stack nicht empfohlen** — Mod ist der offizielle Linuxserver-Weg und vermeidet die meisten Proxy-Probleme. + +--- + +## Freigabe + +| | | +|---|---| +| ☐ | **Freigegeben** — Docker Mod wie beschrieben umsetzen | +| ☐ | **Anpassung** — z. B. Sidecar statt Mod, oder erst Snapshot | +| ☐ | **Abgelehnt / später** | + +**Freigegeben von:** _______________ +**Datum:** _______________ +**Anmerkungen:** _______________ + +--- + +## Referenzen + +| Thema | URL | +|-------|-----| +| notify_push GitHub | https://github.com/nextcloud/notify_push | +| Linuxserver Mod | https://github.com/linuxserver/docker-mods/tree/nextcloud-notify-push | +| App Store v1.3.3 | https://apps.nextcloud.com/apps/notify_push | +| trusted_proxies Troubleshooting | https://github.com/nextcloud/notify_push#push-server-is-not-a-trusted-proxy | +| Bereits umgesetztes Tuning | [nextcloud-tuning-freigabe.md](nextcloud-tuning-freigabe.md) | +| Gesamt-Roadmap | [nextcloud-optimierung-und-updates.md](nextcloud-optimierung-und-updates.md) | diff --git a/pve1/06_ubuntu-vm-nextcloud.md b/pve1/06_ubuntu-vm-nextcloud.md index 4e8f0f8..c0ba47a 100644 --- a/pve1/06_ubuntu-vm-nextcloud.md +++ b/pve1/06_ubuntu-vm-nextcloud.md @@ -240,11 +240,12 @@ 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)** +Freigabe Phase F+G: **[migration/nextcloud-tuning-freigabe.md](../migration/nextcloud-tuning-freigabe.md)** (✅ umgesetzt) +Freigabe notify_push: **[migration/nextcloud-notify-push-freigabe.md](../migration/nextcloud-notify-push-freigabe.md)** (⏳ offen) - [x] PHP-FPM `www2.conf` angepasst + Container recreate - [x] `apc.shm_size` auf 128 MB - [x] System-Cron für `occ background:cron` eingerichtet - [x] VM-RAM 12 GB -- [ ] `notify_push` PoC (App + Sidecar + NPM-Route) +- [ ] `notify_push` — siehe [Freigabe-Dokument](../migration/nextcloud-notify-push-freigabe.md) - [ ] Nach Änderungen: Nginx-Access-Log auf Polling-Frequenz prüfen