Make Nextcloud NAS backups independent, verified and retryable

2026-10-26 11:39:54 +01:00
1 parent ffe3c354be
commit 7e94915442
@@ -1,94 +1,52 @@
 # nextcloud-borg-backup

-Tägliches Borg-Backup des lokalen Nextcloud-Mounts nach Synology:
+Verifizierte, versionierte Sicherung von Nextcloud auf das Synology-NAS. Die Workstation liest `Nextcloud:` direkt mit rclone, prüft einen privaten lokalen Zwischenstand und erstellt daraus verschlüsselte Borg-Archive auf `/net/thor/volume1/NetBackup/Nextcloud/borg-repo`. Der Desktop-Mount `~/Nextcloud` ist unabhängig davon.

- Quelle: `/home/johannes/Nextcloud`
- Ziel: `/net/thor/volume1/NetBackup/Nextcloud/borg-repo`
- Historie: `4w`, also vier Wochen wiederherstellbare Archive
- Betrieb: systemd User Timer, täglich um 03:15 Uhr mit Zufallsverzögerung
- Restore: über CLI, Suche, Borg-Mount oder gezieltes Extrahieren
+Die Übertragung geht ausschließlich **von Nextcloud zum NAS**. Dateien werden in Nextcloud weder geändert noch gelöscht. Das NAS enthält eine Borg-Historie, keinen gewöhnlichen Dateispiegel; gelöschte oder überschriebene Dateien bleiben aus älteren Archiven wiederherstellbar.

-Das Projekt ist bewusst klein gehalten: eine Bash-CLI, Konfiguration, systemd-User-Units und Dokumentation. Es eignet sich direkt für ein Gitea-Repository.
+## Schutz und Zeitplanung

-## Installation
+- Alle 15 Minuten wird geprüft, ob eine Sicherung fällig ist; nach Erfolg frühestens nach 24 Stunden. Fehler werden beim nächsten Timerlauf erneut versucht, auch nach Neustart oder Aufwachen.
+- Eigene direkte Cloud-Verbindung ohne FUSE-Verzeichnis-Cache. Vollständige Inventur vor und nach der Übertragung; Abbruch, wenn sich die Quelle währenddessen ändert.
+- SHA1/MD5-Prüfung des Zwischenstands gegen Nextcloud. Dateien ohne Serverhash werden vollständig neu gelesen und per Downloadvergleich geprüft.
+- Vor und nach der Cloud-Übertragung: Prüfung des tatsächlichen NFS-Mounts, des vorhandenen Repositorys und des freien Speicherplatzes. Keine automatische Repository-Neuanlage im Backup.
+- Schutz vor leerer Quelle, Rückgang von Dateizahl oder Datenmenge um mehr als 20 Prozent und mehr als 1.000 Löschungen im lokalen Zwischenstand.
+- Jeder neue Borg-Stand wird vollständig auf Lesbarkeit und Datenintegrität geprüft; Dateizahl und Bytezahl müssen zur Cloud-Inventur passen. Erst dann gilt der Lauf als bestätigt.
+- Vier Wochen Historie, zusätzlich mindestens sieben Archive; Bereinigung ausschließlich nach erfolgreicher Sicherung. Fehlgeschlagene Wartung wird separat erneut versucht.
+- Unabhängiger stündlicher Alterswächter: Desktop-Warnung bei mehr als 36 Stunden ohne bestätigte Sicherung. Warnungen maximal alle sechs Stunden, Fehler und Details im Journal.
+
+## Installation / Update
+
+Voraussetzungen: Linux, systemd User Manager, Python 3, Borg **1.x**, rclone, util-linux (`findmnt`, `flock`), GNU coreutils und optional `notify-send`. rclone muss `Nextcloud:` bereits authentifiziert kennen; das NAS wird durch das vorhandene autofs eingebunden.

 ```bash
-cd /home/johannes/localdev/nextcloud-borg-backup
+cd ~/localdev/nextcloud-borg-backup
+make check
 ./scripts/install.sh
-```
-
-Der Installer legt an:
-
- `~/.local/bin/nextcloud-borg-backup`
- `~/.config/nextcloud-borg-backup/config`
- `~/.config/nextcloud-borg-backup/passphrase`
- `~/.config/systemd/user/nextcloud-borg-backup.service`
- `~/.config/systemd/user/nextcloud-borg-backup.timer`
-
-Der Installer überschreibt eine vorhandene Konfiguration nicht.
-
-Danach den ersten Lauf manuell starten:
-
-```bash
-systemctl --user start nextcloud-borg-backup.service
+systemctl --user start --no-block nextcloud-borg-backup.service
 journalctl --user -u nextcloud-borg-backup.service -f
 ```

-Timer prüfen:
+Bestehende Konfiguration, Passphrase und Historie bleiben erhalten. Neue Einstellungen haben kompatible Standardwerte; siehe [etc/config.example](etc/config.example). Für neue Installationen: Konfiguration und NAS prüfen, das Repository einmal ausdrücklich mit `nextcloud-borg-backup init` anlegen. Das Backup selbst legt niemals ein Ersatzrepository an.
+
+Der lokale Zwischenstand benötigt ungefähr die Datenmenge der Cloud. Zusätzlich fordert der konservative Speichercheck vor jedem Lauf noch einmal diese Datenmenge plus 5 GiB freien Speicher. Ein Zwischenstand gehört auf einen privaten lokalen Datenträger, niemals auf den Desktop-Mount.
+
+## Betrieb und Wiederherstellung

 ```bash
-systemctl --user status nextcloud-borg-backup.timer
-systemctl --user list-timers nextcloud-borg-backup.timer
-```
-
-Damit der User-Timer auch ohne aktive Anmeldung läuft:
-
-```bash
-sudo loginctl enable-linger johannes
-```
-
-## Bedienung
-
-```bash
-nextcloud-borg-backup backup
+nextcloud-borg-backup health             # JSON, Exit 0: aktuell, Exit 2: überfällig
+nextcloud-borg-backup backup             # sofortiger manueller Lauf
+nextcloud-borg-backup backup --if-due    # wie der Timer
 nextcloud-borg-backup list
-nextcloud-borg-backup status
-nextcloud-borg-backup search Rechnung
+nextcloud-borg-backup info
+systemctl --user list-timers 'nextcloud-borg-*'
+nextcloud-borg-backup restore "" "Dokumente/Beispiel.pdf" ~/Restore-Test
 nextcloud-borg-backup mount
-nextcloud-borg-backup restore
-nextcloud-borg-backup check --verify-data
-```
-
-## Restore-Beispiele
-
-Neuestes Archiv komplett nach `~/Nextcloud-Restore/<Archivname>` wiederherstellen:
-
-```bash
-nextcloud-borg-backup restore
-```
-
-Bestimmte Datei im neuesten Archiv wiederherstellen:
-
-```bash
-nextcloud-borg-backup restore "" "Dokumente/Beispiel.pdf"
-```
-
-Bestimmtes Archiv und bestimmten Pfad wiederherstellen:
-
-```bash
-nextcloud-borg-backup restore nextcloud-2026-07-10_03-15-00 "Dokumente"
-```
-
-Archive bequem lesbar mounten:
-
-```bash
-nextcloud-borg-backup mount
-xdg-open "${XDG_RUNTIME_DIR}/nextcloud-borg-backup-mount"
 nextcloud-borg-backup umount
 ```

-## Wichtige Hinweise
+Eine manuelle Sofortsicherung kann lange dauern. Das Archiv wird erst nach erfolgreicher Datenprüfung als bestätigt markiert. `health` zeigt auch die letzte fehlgeschlagene Phase; `status` zeigt die herkömmlichen Borg-Informationen.

-Die Borg-Passphrase liegt lokal in `~/.config/nextcloud-borg-backup/passphrase`. Ohne diese Datei kann ein verschlüsseltes Borg-Repository im Notfall nicht wiederhergestellt werden. Eine Kopie gehört daher separat und sicher abgelegt.
+Die Passphrase in `~/.config/nextcloud-borg-backup/passphrase` und ein Borg-Schlüsselexport gehören zusätzlich an einen sicheren unabhängigen Ort. Niemals ins Repository einchecken. Der lokale Zwischenstand ist unverschlüsselt; seine Dateirechte sind privat, eine Datenträgerverschlüsselung richtet dieses Projekt nicht ein.

-Weitere Details stehen in [Dokumentation.md](Dokumentation.md).
+Details, Fehlerbehandlung, Grenzen und Abnahme: [Dokumentation.md](Dokumentation.md).