chore: import v0.3.0 baseline and add v0.4 recovery architecture plan

This commit is contained in:
Lars committed 2026-10-29 13:58:35 +01:00
commit 40188c0e10
12 files changed
+1506

No files matched your search

+161
View File
@@ -0,0 +1,161 @@
# 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.