PKR-Lab

20010 - NAS-Backup auf externe USB-Platte

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/2-betrieb-hardware/20010-nas-backup.md

NAS-Backup auf externe USB-Platte

Löst den in capulus-core/2-betrieb-hardware/20000-nas-storage.md → Backups auf externer NAS-Platte
angekündigten Punkt ein: eine externe USB-Festplatte, direkt am UGREEN NAS
angeschlossen, sichert regelmäßig beide Storage-Pools (volume1 und
volume2) — also sowohl den generischen Cluster-Storage
(k8s-storage, StorageClass nas) als auch den dedizierten
Immich-Storage (immich-storage, StorageClass immich-nas, siehe
capulus-core/3-apps-workloads/300c0-immich.md).

Wie bei der NFS-Einrichtung in capulus-core/2-betrieb-hardware/20000-nas-storage.md gibt es dafür bewusst kein
Ansible-Playbook — UGOS ist eine eigene Firmware ohne SSH-Ansible-Support
für diese Art Task, die Einrichtung läuft über UGOS Task Scheduler +
Docker (Container Manager), analog zu den bereits dokumentierten
node_exporter/smartctl_exporter-Containern.


Architektur

┌─────────────────────────────── UGREEN NAS (UGOS) ───────────────────────────────┐
│                                                                                   │
│   /volume1  (k8s-storage, RAID1, 2×4TB)  ──┐                                     │
│                                             ├──▶  restic backup  ──▶  externe    │
│   /volume2  (immich-storage)  ─────────────┘      (Docker-Container,             │
│                                                     via UGOS Task Scheduler)      │
│                                                            │                      │
│                                                            ▼                      │
│                                              USB-Platte (z.B. /volumeUSB1/...)   │
│                                              verschlüsseltes restic-Repository    │
└───────────────────────────────────────────────────────────────────────────────┘

Voraussetzungen

  1. Externe USB-Platte am NAS angeschlossen, in UGOS unter
    Speicher-Manager → Externe Geräte formatiert (ext4 oder btrfs,
    keine NTFS-Berechtigungsprobleme unter Linux-Docker) und eingehängt.
    Den Mount-Pfad notieren — UGOS hängt externe Laufwerke typischerweise
    unter /volumeUSB1/usbshare1 o. ä. ein; exakten Pfad in UGOS unter
    Speicher-Manager prüfen
    , das Beispiel unten ist ein Platzhalter.
  2. Kapazität der USB-Platte ≥ tatsächlich genutzter Speicher auf
    volume1 + volume2 (nicht die Rohkapazität) plus Puffer für
    mehrere retinierte Snapshots (siehe Aufbewahrung
    unten — bei täglichen Backups mit restic-Dedup meist 20–40 % Aufschlag,
    nicht ein Vielfaches, da nur geänderte Blöcke zusätzlich Platz kosten).
  3. Docker (Container Manager) auf dem NAS aktiv — bereits Voraussetzung
    für die Exporter in capulus-core/2-betrieb-hardware/20000-nas-storage.md → Monitoring.

Schritt 1 — restic-Repository einmalig anlegen

Passwort generieren und sicher aufbewahren (Passwort-Manager) — ohne
dieses Passwort ist das Backup nicht wiederherstellbar, auch nicht vom
NAS-Admin selbst:

openssl rand -base64 32

Repository auf der externen Platte initialisieren (Pfad an den echten
Mount-Punkt aus den Voraussetzungen anpassen):

docker run --rm \
  -v /volumeUSB1/usbshare1/nas-backup:/repo \
  -e RESTIC_REPOSITORY=/repo \
  -e RESTIC_PASSWORD='<generiertes-Passwort>' \
  restic/restic:latest init

Schritt 2 — Backup-Skript für den UGOS Task Scheduler

Systemsteuerung → Task Scheduler → Erstellen → Geplante Aufgabe →
Benutzerdefiniertes Skript.
Zeitplan siehe Wie oft?
unten (04:00 Uhr, nach allen Cluster-Jobs, siehe Zeitplan der Nacht), Skript-Inhalt:

#!/bin/sh
set -eu

REPO=/volumeUSB1/usbshare1/nas-backup   # ← an echten Mount-Pfad anpassen
PASSWORD='<generiertes-Passwort-aus-Schritt-1>'

docker run --rm \
  -v /volume1:/data/volume1:ro \
  -v /volume2:/data/volume2:ro \
  -v "$REPO":/repo \
  -e RESTIC_REPOSITORY=/repo \
  -e RESTIC_PASSWORD="$PASSWORD" \
  restic/restic:latest \
  backup /data/volume1 /data/volume2 \
  --exclude='/data/volume1/@eaDir' \
  --exclude='/data/volume2/@eaDir'

# Alte Snapshots gemäß Aufbewahrungsrichtlinie entfernen + Speicher freigeben
docker run --rm \
  -v "$REPO":/repo \
  -e RESTIC_REPOSITORY=/repo \
  -e RESTIC_PASSWORD="$PASSWORD" \
  restic/restic:latest \
  forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

@eaDir sind UGOS/Synology-typische versteckte Thumbnail-/Metadaten-
Verzeichnisse — Ausschluss spart Platz und vermeidet unnötige Backup-Last.
Falls UGOS einen anderen Namen für diese Verzeichnisse verwendet, per
ls -la /volume1 prüfen und die --exclude-Pfade anpassen.

Read-only Mounts (:ro): Der Backup-Container kann die
Quell-Volumes nicht verändern — ein Bug im Skript kann bestenfalls die
externe Platte, nie die Produktivdaten beschädigen.

Task Scheduler → Einstellungen: "Nur bei Fehler benachrichtigen"
zusätzlich per E-Mail/NAS-eigene Push-Funktion aktivieren, falls
verfügbar, damit ein fehlgeschlagener Backup-Lauf nicht unbemerkt bleibt.


Wie oft? Empfehlungen

restic dedupliziert Blöcke — nach dem ersten vollständigen Backup kostet
ein weiterer Lauf nur die tatsächlich geänderten Daten, nicht die
komplette Datenmenge erneut. Häufigere Backups sind mit restic also
deutlich günstiger als bei klassischem rsync-Vollkopie-Ansatz. Drei
sinnvolle Optionen:

Option Zeitplan Max. Datenverlust (RPO) Wann sinnvoll
Täglich (empfohlen) Jede Nacht, 04:00 Uhr ≤ 24 Stunden Standardfall — Immich-Fotos, Nextcloud-Dateien und Vaultwarden-Tresor ändern sich laufend, dank Dedup kostet der tägliche Lauf kaum mehr als ein wöchentlicher
Zweimal wöchentlich z. B. Mi + So, 02:00 Uhr ≤ 3–4 Tage Kompromiss, falls die USB-Platte über eine langsame Schnittstelle (USB 2.0) angebunden ist und ein täglicher Lauf spürbar Last erzeugt
Wöchentlich z. B. So, 03:00 Uhr ≤ 7 Tage Nur falls Kapazität/Performance der Platte stark eingeschränkt ist — höheres Risiko, eine ganze Woche Fotos/Dokumente bei einem Ausfall zwischen zwei Läufen zu verlieren

Empfehlung: täglich um 04:00 Uhr, mit der Aufbewahrungsrichtlinie aus
Schritt 2 (7 Tage täglich, 4 Wochen wöchentlich, 6 Monate monatlich —
danach werden ältere Snapshots automatisch durch forget --prune
entfernt). Der Lauf liegt hinter allen Cluster-Backups (siehe Zeitplan der Nacht), damit die restic-Repositories der Apps nicht mitten im Schreiben auf die USB-Platte kopiert werden. Nachts, weil dann sowohl Cluster- als auch NAS-Last (SMB/NFS-
Zugriffe, Immich-Uploads) am geringsten sind.

Aufbewahrung (Retention)

Die --keep-*-Flags in forget bestimmen, wie viele Snapshots erhalten
bleiben, unabhängig vom gewählten Backup-Intervall:

Damit lässt sich z. B. eine versehentlich vor 3 Wochen gelöschte Datei
noch wiederherstellen, ohne dass die Platte mit täglichen Snapshots über
Monate hinweg vollläuft.


Zeitplan der Nacht

Alles, was auf local-path liegt (SSD des Nodes homeserver), sieht der NAS-Task nicht. Diese Apps sichern deshalb zuerst per Cluster-Job auf das NAS-Volume (volume1), danach kopiert der NAS-Task volume1 + volume2 verschlüsselt auf die USB-Platte. Auf der USB-Platte liegt damit alles im restic-Repository des NAS-Tasks, die Cluster-Repositories der Apps sind zusätzlich selbst verschlüsselt.

Zeit Job Cluster Art Verschlüsselt im Cluster
01:30 vaultwarden-backup TECH Spiegel (rsync) nein
01:50 immich-postgres-backup PROD pg_dump nein
02:10 vaultwarden TECH restic (Operator) ja
02:20 n8n-restic-backup TECH restic ja
02:30 nextcloud-postgresql-backup PROD pg_dump (7 Stück) nein
02:40 mdm-backup TECH restic ja
02:50 uptime-kuma TECH restic (Operator) ja
03:00 zammad TECH restic (Operator, pg_dump) ja
04:00 NAS-Task NAS restic auf USB ja

Wiederherstellung

Vaultwarden-Redeploy: Für den häufigsten Fall — die
vaultwarden-data-PVC ist weg, die NAS-seitige vaultwarden-backup-PVC
(gefüllt vom nächtlichen backup-cronjob.yaml) aber noch da — gibt es
einen automatisierten Ansible-Weg, der nicht über restic/USB geht:
capulus-core/3-apps-workloads/300a0-vaultwarden.md → Restore nach Redeploy / Disaster
Recovery

(make vaultwarden-restore FORCE_RESTORE=true). Der restic-Restore hier
unten bleibt der Fallback, falls auch der NAS-Stand selbst verloren ist.

Einzelne Datei/Ordner (z. B. ein aus Nextcloud gelöschtes Dokument):

docker run --rm \
  -v /volumeUSB1/usbshare1/nas-backup:/repo \
  -v /volume1:/restore-target \
  -e RESTIC_REPOSITORY=/repo \
  -e RESTIC_PASSWORD='<Passwort>' \
  restic/restic:latest \
  restore latest --target /restore-target/RESTORE \
  --include /data/volume1/k8s-storage/<pfad-zur-datei>

Snapshots auflisten (um einen bestimmten Zeitpunkt statt latest zu wählen):

docker run --rm \
  -v /volumeUSB1/usbshare1/nas-backup:/repo \
  -e RESTIC_REPOSITORY=/repo \
  -e RESTIC_PASSWORD='<Passwort>' \
  restic/restic:latest snapshots

Vollständiger Restore (z. B. nach Verlust von volume1): analog mit
--target auf den wiederhergestellten Mount-Punkt, ohne --include-Filter.


Integritätsprüfung

Monatlich empfehlenswert (separater Task-Scheduler-Eintrag oder manuell),
prüft Metadaten + optional Datenintegrität des Repositories:

docker run --rm \
  -v /volumeUSB1/usbshare1/nas-backup:/repo \
  -e RESTIC_REPOSITORY=/repo \
  -e RESTIC_PASSWORD='<Passwort>' \
  restic/restic:latest check

Hinweis: Konsistenz laufender Datenbanken

Der Backup-Task sichert volume1/volume2 auf Dateisystem-Ebene, auch
während PostgreSQL-Container (Wiki.js, Zammad, Nextcloud, Immich, …)
aktiv darauf schreiben. Das entspricht dem Zustand nach einem
Stromausfall — PostgreSQL erholt sich davon dank WAL-basiertem
Crash-Recovery beim nächsten Start, es ist aber kein
transaktions-konsistenter Snapshot wie bei einem pg_dump. Für die
meisten Home-Lab-Fälle ist das ausreichend; falls später ein stärkeres
Konsistenz-Garantie gewünscht ist, lässt sich das Skript in Schritt 2 um
pg_dump-Aufrufe (z. B. via kubectl exec) vor dem restic backup
erweitern — bewusst nicht Teil dieser ersten Iteration.


restic für Vaultwarden (im Cluster)

Zusätzlich zur NAS-seitigen Sicherung läuft im Cluster ein eigener, verschlüsselter und versionierter Vaultwarden-Backup (Backup vaultwarden des capulus-operator, täglich 02:10, nach dem bestehenden Spiegel-Job um 01:30). Der Operator erzeugt daraus den CronJob vaultwarden. Der alte Job vaultwarden-backup bleibt vorerst bestehen, weil die Rolle vaultwarden_restore aus ihm wiederherstellt; er überschreibt seine Kopie bei jedem Lauf, ist unverschlüsselt und kennt keine Versionen.

kubectl -n vaultwarden apply -f - <<'YAML'
apiVersion: v1
kind: Pod
metadata:
  name: restic-restore-test
spec:
  restartPolicy: Never
  containers:
    - name: restic
      image: alpine:3.24
      command: ["sh", "-c", "apk add --no-cache restic sqlite >/dev/null && restic snapshots && restic restore latest --target /restore && ls -R /restore | head -20 && sqlite3 /restore/stage/db.sqlite3 'select count(*) from users' ; sleep 3600"]
      env:
        - name: RESTIC_REPOSITORY
          value: /repo
        - name: RESTIC_CACHE_DIR
          value: /tmp/cache
        - name: RESTIC_PASSWORD
          valueFrom:
            secretKeyRef: {name: vaultwarden-restic, key: password}
      volumeMounts:
        - {name: repo, mountPath: /repo, readOnly: true}
        - {name: restore, mountPath: /restore}
  volumes:
    - name: repo
      persistentVolumeClaim: {claimName: vaultwarden-restic}
    - name: restore
      emptyDir: {}
YAML
kubectl -n vaultwarden logs -f pod/restic-restore-test
kubectl -n vaultwarden delete pod restic-restore-test

Ein echtes Zurückspielen in das Datenverzeichnis läuft weiter über die Rolle vaultwarden_restore (aus dem Spiegel); eine Umstellung der Rolle auf restic restore und das Abschalten des Spiegel-Jobs ist der nächste Schritt, sobald ein Restore-Test aus dem Repository bestanden ist.


restic für n8n (im Cluster)

n8n hat einen eigenen, verschlüsselten und versionierten Backup-Job (n8n-restic-backup, täglich 02:20, TECH-Cluster, Namespace n8n). Er entstand, weil die n8n-Daten nach dem Umzug von NFS auf local-path (SQLite blockierte auf NFS, siehe 30070) nur noch auf der SSD des Nodes homeserver liegen. Aufbau wie bei Vaultwarden, Chart-Dateien restic-cronjob.yaml, restic-pvc.yaml und restic-sealedsecret.yaml unter argocd/apps/tech/n8n/templates/, alles hinter resticBackup.enabled (Standard false).

kubectl -n n8n apply -f - <<'YAML'
apiVersion: v1
kind: Pod
metadata:
  name: restic-restore-test
spec:
  restartPolicy: Never
  containers:
    - name: restic
      image: alpine:3.24
      command: ["sh", "-c", "apk add --no-cache restic sqlite >/dev/null && restic snapshots && restic restore latest --target /restore && ls -R /restore | head -20 && sqlite3 /restore/stage/database.sqlite 'select count(*) from workflow_entity; select count(*) from credentials_entity' ; sleep 3600"]
      env:
        - name: RESTIC_REPOSITORY
          value: /repo
        - name: RESTIC_CACHE_DIR
          value: /tmp/cache
        - name: RESTIC_PASSWORD
          valueFrom:
            secretKeyRef: {name: n8n-restic, key: password}
      volumeMounts:
        - {name: repo, mountPath: /repo, readOnly: true}
        - {name: restore, mountPath: /restore}
  volumes:
    - name: repo
      persistentVolumeClaim: {claimName: n8n-restic}
    - name: restore
      emptyDir: {}
YAML
kubectl -n n8n logs -f pod/restic-restore-test
kubectl -n n8n delete pod restic-restore-test

restic für Uptime Kuma (im Cluster)

Uptime Kuma (SQLite kuma.db auf local-path) sichert täglich um 02:50 über das Backup uptime-kuma des capulus-operators in ein restic-Repository auf dem NAS-Volume (PVC uptime-kuma-restic, StorageClass nas, 2 Gi). Der Operator macht erst einen konsistenten sqlite3 .backup samt integrity_check, dann sichert restic das Datenverzeichnis ohne die Live-Datenbank. Aufbewahrung 7 tägliche, 4 wöchentliche, 6 monatliche Snapshots. Chart-Dateien restic-backup.yaml, restic-pvc.yaml, restic-sealedsecret.yaml unter argocd/apps/tech/uptime-kuma/templates/, alles hinter resticBackup.enabled (Standard false).


restic für Zammad (im Cluster)

Zammad (PostgreSQL auf local-path, Anhänge liegen in der Datenbank, storageVolume ist aus) sichert täglich um 03:00 über das Backup zammad in ein restic-Repository (PVC zammad-restic, StorageClass nas, 10 Gi). Der Operator zieht per pg_dump -Fc einen konsistenten Dump von zammad_production (Host zammad-postgres, Passwort aus zammad-secrets), restic sichert ihn. Redis und Memcached sind Cache und werden nicht gesichert. Chart-Dateien unter argocd/apps/tech/zammad/templates/restic-*.yaml, hinter resticBackup.enabled (Standard false).


Fehlerbehebung

Task Scheduler zeigt Fehler / Backup läuft nicht:

# UGOS-Task-Log prüfen (Systemsteuerung → Task Scheduler → Aufgabe → Ergebnis anzeigen)
# Manueller Testlauf per SSH, um die konkrete Fehlermeldung zu sehen:
ssh [email protected]
sh /pfad/zum/backup-skript.sh

restic: repository not found / falsches Passwort:

Pfad in RESTIC_REPOSITORY und das in Schritt 1 vergebene Passwort
gegenprüfen — beides muss exakt zum ursprünglichen init-Aufruf passen.

USB-Platte nicht eingehängt nach NAS-Neustart:

UGOS-Einstellung für automatisches Einhängen externer Geräte prüfen
(Speicher-Manager → Externe Geräte → Automatisch einhängen), sonst
schlägt der nächste geplante Task fehl, weil der Mount-Pfad fehlt.