@@ -0,0 +1,415 @@
# 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:
``` bash
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–
| **Direkte S3-Downloads ** (Thumbnails 2– × **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)
``` bash
# 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
``` bash
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
``` bash
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:
``` yaml
# 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)
``` bash
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:
``` bash
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:
``` sql
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): **
``` bash
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):
``` sql
CREATE INDEX fs_path_hash ON oc_filecache ( path_hash ) ;
```
Danach:
``` bash
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:
``` bash
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 ** ).
``` ini
; 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– –
### 5.2 `/opt/stacks/nextcloud/config/php/php-local.ini`
Aktuell nur `date.timezone` . Ergänzen:
``` ini
date.timezone = Etc/UTC
apc.shm_size = 128M
```
(Default im Container: 32 MB — Nextcloud empfiehlt ≥ 128 MB.)
### 5.3 Anwenden
``` bash
# 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
``` bash
docker exec -u abc nextcloud php /app/www/public/occ background:cron
```
Alternativ: Admin → Grundeinstellungen → Hintergrundjobs → **Cron ** .
### 6.2 Crontab auf VM 101 (root)
``` bash
crontab -e
```
``` cron
# 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
``` bash
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
``` 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
```
(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:
``` yaml
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
```
``` bash
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
``` bash
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` :
``` php
'notify_push_redis' => [
'host' => 'redis' ,
'port' => 6379 ,
],
```
### 7.5 Erfolgskontrolle
``` bash
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 ](../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
root