Raspberry Pi 5 – Backup-Orchestrator v0.3

Status: Test- und Integrationsversion. Keine produktiven Backups, Timer, Crontabs oder Datenbanken werden durch Installation, --check, --plan oder --status verändert. Die vorhandenen Backup-Skripte sind noch nicht vollständig standardisiert, zusätzliche Datenbank-Jobs fehlen und eine vollständige Systemwiederherstellung ist noch nicht getestet. --run bleibt bewusst mehrfach gesperrt.

1. Enthaltene Dateien

  • orchestrator.py: phasenbasierter Python-Controller (Python 3.11 / Debian 12, nur Standardbibliothek).
  • jobs.csv: bestehende acht Jobs. Alle enabled=false und verweisen derzeit auf die alten, vorhandenen Skriptpfade.
  • notifications.json.example: eine zentrale Konfigurationsdatei für ausgehende HTTP-POST-Webhooks und Uptime-Kuma-Push-Monitore; keine echten Secrets.
  • tests/test_orchestrator.py: Tests mit künstlichen Shellskripten und simulierten HTTP-Antworten; niemals produktive Datenbanken oder das NAS.

2. Sichere Installation auf raspberrypi5

ZIP auf den Raspberry Pi übertragen und dort entpacken. Im entpackten Verzeichnis:

python3 -m unittest discover -s tests -v
sudo cp -a /usr/local/sbin/backup-orchestrator /usr/local/sbin/backup-orchestrator.before-v03
sudo install -m 755 orchestrator.py /usr/local/sbin/backup-orchestrator

# Die vorhandene /etc/backup-orchestrator/jobs.csv NICHT überschreiben.
# Die Benachrichtigungskonfiguration nur bei erstmaliger Einrichtung kopieren.
sudo install -d -m 750 /etc/backup-orchestrator
if ! sudo test -e /etc/backup-orchestrator/notifications.json; then
  sudo install -m 600 notifications.json.example /etc/backup-orchestrator/notifications.json
fi
sudo backup-orchestrator --check

Ohne bereits installierte ältere Version entfällt die Zeile sudo cp -a ...before-v03.

Keine --run-Befehle ausführen, solange die alten Cronjobs und der raspiBackup-Timer aktiv sind und die alten Dump-Skripte noch nicht gehärtet wurden. Den Produktiv-Cutover führen wir später kontrolliert durch.

3. Konfiguration der Phasen

Die vorhandene Tabelle unter /etc/backup-orchestrator/jobs.csv hat keine Uhrzeiten:

phase,id,script,critical,timeout_seconds,enabled
10,paperless-db,/home/lars/db-backup.sh,true,600,false
10,tandoor-db,/home/lars/db-Tandoor.sh,true,600,false
20,nas-data,/home/lars/backupPaperlessData.sh,true,10800,false
30,system-image,/usr/local/bin/raspiBackup.sh,true,14400,false

Die Beispiele sind ein Ausschnitt; die mitgelieferte Datei enthält acht Jobs.

  • Innerhalb derselben Phase laufen bis zu drei Jobs gleichzeitig (per --max-parallel N einstellbar).
  • Zwischen Phasen gilt eine Barriere: Die nächste Phase beginnt erst, wenn die aktuelle vollständig abgeschlossen ist.
  • Ein kritischer Fehler blockiert nachfolgende Phasen; laufende Jobs derselben Phase werden beendet bzw. bis zum Abschluss abgewartet.
  • Ein unkritischer Fehler wird protokolliert und führt zu einem fehlgeschlagenen Gesamtergebnis, blockiert aber die nächste Phase nicht.
  • Zeitüberschreitung beendet die Skript-Prozessgruppe; Service-Neustart und Datenbankkonsistenz müssen in den jeweiligen Jobs abgesichert sein.

Zentrale Zeitsteuerung per einem systemd-Timer ist eine spätere Cutover-Aufgabe, nicht Bestandteil der Installation.

4. Externe Schnittstellen

A. Ausgehende Webhooks, HTTP POST

/etc/backup-orchestrator/notifications.json bearbeiten:

{
  "timeout_seconds": 3,
  "webhooks": ["http://192.168.2.100:5678/webhook/backup-events"],
  "kuma": {
    "overall_push_url": "http://192.168.2.63:3010/api/push/GESAMT_MONITOR_TOKEN",
    "job_push_urls": {
      "nas-data": "http://192.168.2.63:3010/api/push/NAS_MONITOR_TOKEN",
      "paperless-db": "http://192.168.2.63:3010/api/push/PAPERLESS_MONITOR_TOKEN"
    }
  }
}

Alle URLs sind Beispiele – vorhandene echte Push-Tokens nur auf dem Pi eintragen. Einträge mit "" sind deaktiviert. Es gibt keinen HTTP-Listener und keinen permanent laufenden Webserver; Webhooks sind ausgehend.

Die echten URLs können auch komplett aus der Uptime-Kuma-Oberfläche kopiert werden (...?status=up&msg=OK&ping=). Diese Beispiel-Query wird beim Laden entfernt und beim Push durch den tatsächlichen Status ersetzt.

Diese Datei enthält Zugriffstokens: sudo chmod 600 /etc/backup-orchestrator/notifications.json. Sie gehört in eine vertrauliche Konfigurationssicherung, nicht in ein öffentliches Repository.

B. Ereignisse und Beispiele

Alle Ereignisse werden als JSON je Zeile in /var/log/backup-orchestrator/<run_id>/events.jsonl geschrieben; jede Zeile wird auch an die konfigurierten POST-Webhooks gesendet.

  • RUN_STARTED, PHASE_STARTED, JOB_STARTED
  • JOB_SUCCESS, JOB_FAILED, JOB_TIMEOUT, JOB_ERROR, JOB_CANCELLED, JOB_BLOCKED
  • PHASE_COMPLETED, PHASE_BLOCKED, RUN_FINISHED

Beispiel einer Webhook-Nachricht (ohne Geheimnisse):

{
  "event": "JOB_FAILED",
  "timestamp": "2026-10-29T01:02:00+01:00",
  "run_id": "20261029-010000-1234",
  "host": "raspberrypi5",
  "phase": 10,
  "job": "shinkan-prod-db",
  "critical": true,
  "state": "failed",
  "exit_code": 1,
  "duration_seconds": 12.3,
  "log": "/var/log/backup-orchestrator/20261029-010000-1234/shinkan-prod-db.log"
}

Webhooks versenden Ereignismetadaten, nicht den Inhalt der Backup-Skripte oder SQL-Dumps.

C. Uptime Kuma

  • JOB_SUCCESS → status=up für den konfigurierten Job-Monitor.
  • JOB_FAILED, JOB_TIMEOUT, JOB_ERROR, JOB_CANCELLED und JOB_BLOCKED → status=down.
  • RUN_FINISHED → status=up nur beim Gesamtergebnis ok, sonst down.
  • Ausbleibende Backups meldet Kuma über den konfigurierten Push-Heartbeat, z.B. bei einem täglichen Lauf ein zum Zeitplan passender Wert.
  • Schlägt die Zustellung fehl, schreibt der Controller eine Warnung in notifications.log. Der Backup-Exit-Code bleibt unverändert.

Keine doppelten Push-Meldungen erzeugen: Wenn nas-data künftig durch den Orchestrator gemeldet wird, die Push-Funktion im Skript backupPaperlessData.sh deaktivieren oder nur einen der beiden Sender verwenden.

D. Lokaler Status, JSON-Abfrage

Während des Laufs wird der aktuelle Stand atomar aktualisiert:

/var/log/backup-orchestrator/latest.json
/var/log/backup-orchestrator/<run_id>/status.json
/var/log/backup-orchestrator/<run_id>/summary.json
/var/log/backup-orchestrator/<run_id>/events.jsonl

CLI für andere Skripte, Home Assistant oder eine spätere GUI:

sudo backup-orchestrator --status
sudo backup-orchestrator --status --json
sudo cat /var/log/backup-orchestrator/latest.json

Die Statusdateien enthalten keine Push-Tokens oder Zugangsdaten, aber interne Pfade und Jobnamen. Daher nur für vertrauenswürdige lokale Nutzer freigeben. Es gibt derzeit keine eingehende REST-API; dies kann später als separater schreibgeschützter Dienst ergänzt werden.

5. Sichere Bedienung

sudo backup-orchestrator --check                   # nur Prüfungen, keine Backups
sudo backup-orchestrator --plan                    # nur aktivierte Jobs anzeigen
sudo backup-orchestrator --status --json           # letzter Status bzw. no_runs

--run, --run --phase 10 und --run --job paperless-db sind für einen späteren, explizit kontrollierten Produktiv-Cutover vorgesehen. Der Controller verweigert Ausführung, solange keine Jobs aktiviert sind, der NAS-Mount fehlt, aktive alte Zeitpläne gefunden werden oder BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES fehlt. Das stellt keine vollständige Sicherheitsfreigabe dar: Skripte und Restore müssen zusätzlich getestet werden.

6. Offene Arbeiten für den Produktivbetrieb

  1. Vorhandene Datenbank-Dump-Skripte unter scripts/ konsolidieren und auf atomare Dumps unter festen Dateinamen umstellen; Zugänge sicher verwahren.
  2. Weitere Datenbanken (Kairo, Tsumugu, Kanshō, Buying Agent, BookStack, NetBox usw.) und zu sichernde Docker-Volumes/Bind-Mounts aufnehmen.
  3. rsync-Skript prüfen: nas-data sendet bei der Umstellung nicht gleichzeitig selbst und über Orchestrator Pushs.
  4. raspiBackup: zuverlässiger vollständiger Restore, korrekt gestoppte Docker-Dienste, Restart-/Timeout-Verhalten nach Fehler.
  5. Alte Cronjobs/Timer erst beim kontrollierten Cutover ersetzen und einen einzigen orchestrator-Timer installieren.
  6. Vollständigen Testlauf, Restore-Test und erwartete Kuma-Ereignisse prüfen.
  7. Zweiten unabhängigen/offsite Backup-Standort erwägen; NAS-Ausfall bleibt sonst Single Point of Failure.

Hinweis zur bisherigen Zeitplanung: Die Root-Crontab-Einträge sind nach der letzten Nutzerprüfung auskommentiert; die aktive User-Crontab sowie raspiBackup.timer werden weiterhin als aktive Konflikte erkannt.

S
Description
No description provided
Readme
323 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 87.1%
Shell 12.9%