Files
backup-orchestrator/README.md
T

162 lines
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
```bash
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**:
```csv
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:
```json
{
"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):
```json
{
"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:
```text
/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:
```bash
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
```bash
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.