162 lines
8.6 KiB
Markdown
162 lines
8.6 KiB
Markdown
# 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.
|