docu/migration/nextcloud-optimierung-und-updates.md

# 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