8.6 KiB
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. Alleenabled=falseund 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 Neinstellbar). - 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_STARTEDJOB_SUCCESS,JOB_FAILED,JOB_TIMEOUT,JOB_ERROR,JOB_CANCELLED,JOB_BLOCKEDPHASE_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=upfür den konfigurierten Job-Monitor.JOB_FAILED,JOB_TIMEOUT,JOB_ERROR,JOB_CANCELLEDundJOB_BLOCKED→status=down.RUN_FINISHED→status=upnur beim Gesamtergebnisok, sonstdown.- 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
- Vorhandene Datenbank-Dump-Skripte unter
scripts/konsolidieren und auf atomare Dumps unter festen Dateinamen umstellen; Zugänge sicher verwahren. - Weitere Datenbanken (Kairo, Tsumugu, Kanshō, Buying Agent, BookStack, NetBox usw.) und zu sichernde Docker-Volumes/Bind-Mounts aufnehmen.
- rsync-Skript prüfen: nas-data sendet bei der Umstellung nicht gleichzeitig selbst und über Orchestrator Pushs.
- raspiBackup: zuverlässiger vollständiger Restore, korrekt gestoppte Docker-Dienste, Restart-/Timeout-Verhalten nach Fehler.
- Alte Cronjobs/Timer erst beim kontrollierten Cutover ersetzen und einen einzigen orchestrator-Timer installieren.
- Vollständigen Testlauf, Restore-Test und erwartete Kuma-Ereignisse prüfen.
- 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.