jean/docu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doku: Nextcloud-Migrationsplan und korrigierte Versionslogik.

Browse Source 
Neuer Ordner migration/ mit Schritt-für-Schritt-Anleitung (Backup, Minor-Update,
PHP-FPM, notify_push, DB-Indizes). Hub-Name vs. NC-Version in der Ist-Doku
korrigiert: NC 34 = Hub 26 Spring, ADA bereits aktiv.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
root
2026-06-28 09:37:54 +02:00
parent 28983bb815
commit 509fcd96b6
5 changed files with 450 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
migration/nextcloud-optimierung-und-updates.md
+415
View File
@@ -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–90 %) | hoch |
| **Direkte S3-Downloads** (Thumbnails 2–10× schneller) | **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–100 MB/Worker → 15 Worker ≈ 1,2–1,5 GB — passt in VM mit 8 GB neben MariaDB/Redis.
### 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