feat(v0.4): import all Raspberry Pi scripts and implement Recovery Management engine + Shinkan adapters
This commit is contained in:
1 parent
40188c0e10
commit
c53fc0a939
35 files changed
+2877
-191
No files matched your search
@@ -1,161 +1,93 @@
|
||||
# Raspberry Pi 5 – Backup-Orchestrator v0.3
|
||||
# Backup-Orchestrator v0.4 – Backup & Recovery Management
|
||||
|
||||
**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.
|
||||
**Status: Version 0.4.0 (Multi-Host Backup & Application Recovery Management).**
|
||||
Erweitert den auf `raspberrypi5` produktiv laufenden Backup-Orchestrator v0.3 um ein integriertes Recovery Management, kryptografisch geprüfte Recovery Points (`schemaVersion: 1`), ein 4-stufiges Verifikationsmodell (`captured` → `verified` → `consistent` → `restore_tested`), einen zustandsbewussten `raspiBackup.service`-Konflikt-Check sowie vollständige Application-Restore- und Restore-Test-Adapter für die Referenzanwendung **Shinkan** auf `llm-node` (`192.168.2.144`).
|
||||
|
||||
## 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.
|
||||
## 1. Repository-Struktur & Enthaltene Dateien
|
||||
|
||||
## 2. Sichere Installation auf raspberrypi5
|
||||
- `orchestrator.py`: Phasenbasierter Backup- & Recovery-Controller (`v0.4.0`, Python 3.11+, nur Standardbibliothek).
|
||||
- `targets.json`: Multi-Host- und Recovery-Target-Definitionen (`raspberrypi5`, `llm-node`, Targets `pi-prod`, `llm-prod`, `llm-restoretest`).
|
||||
- `jobs.csv`: Produktive Backup-Job-Tabelle (17 Datenbank-Exporte in Phase 10, `nas-data` in Phase 20, `system-image` in Phase 30).
|
||||
- `notifications.json.example`: Beispielkonfiguration für ausgehende HTTP-POST-Webhooks und Uptime-Kuma-Push-Monitore (enthält keine echten Secrets).
|
||||
- `systemd/`:
|
||||
- `backup-orchestrator-daily`: Täglicher Runner-Wrapper (ab v0.4 ohne fragiles `systemctl disable/enable raspiBackup.timer`).
|
||||
- `backup-orchestrator-daily.service` & `backup-orchestrator-daily.timer`: Systemd-Units für den täglichen Lauf um `05:30` Uhr.
|
||||
- `scripts/`:
|
||||
- Alle 17 Datenbank-Dump-Wrapper (`db-bookstack.sh`, `db-buyingagent-dev.sh`, `db-buyingagent-prod.sh`, `db-kairo-dev.sh`, `db-kairo-prod.sh`, `db-kansho-dev.sh`, `db-kansho-prod.sh`, `db-karatewiki-dev.sh`, `db-mitai-dev.sh`, `db-mitai-prod.sh`, `db-netbox.sh`, `db-paperless.sh`, `db-shinkan-dev.sh`, `db-shinkan-prod.sh`, `db-tandoor.sh`, `db-tandoor.sh`, `db-tsumugu-dev.sh`, `db-tsumugu-prod.sh`) sowie die generischen Dump-Engines `db-postgres-docker.sh` und `db-mariadb-docker.sh`.
|
||||
- `backup-nas-data.sh` & `nas-data-job.sh`: Versionierte rsync-Hardlink-Sicherung (`/media/lars/paperless` → `/backup/data_archiv/01..31` + `last`).
|
||||
- `publish-backup-set.sh` & `shinkan-prod-manifest.sh`: Atomare Erzeugung und Publikation vollständiger Backup-Sets (`<dump>.sql`, `<dump>.sql.sha256`, `<dump>.sql.manifest.json`, `<dump>.sql.media.jsonl`).
|
||||
- `scripts/shinkan/` (Shinkan Recovery Contract Adapter):
|
||||
- `shinkan-backup-manifest`: Erzeugt SHA256, Manifest (`schemaVersion: 1` + Shinkan Contract) und inkrementelles Media-Inventar (`media.jsonl`).
|
||||
- `shinkan-restore`: 9-stufiger atomarer Application-Restore über Staging-DB (`shinkan_restore_<ts>`), Single-Transaction-Import, Schema-Migrations-Gate, Plausibilitätsprüfung, `TRUNCATE sessions`, DB-Swap (`shinkan_before_<ts>`), `/api/health/ready`-Prüfung und automatischem Rollback bei Fehlern (Exit `5`).
|
||||
- `shinkan-media-diff`: Abgleich zwischen PostgreSQL (`media_assets`, `exercise_media`), Dateisystem und `media.jsonl` (`missing`, `mismatch`, `added_after_backup`, `orphan`).
|
||||
- `shinkan-restore-test` & `docker-compose.restoretest.yml`: Isolierter End-to-End-Restore-Test im Projekt `shinkan-restoretest` (Ports `127.0.0.1:18003` / `127.0.0.1:13003`, Read-Only-Media `:ro`, deaktivierte externe Integrationen & Cronjobs).
|
||||
- `docs/ARCHITECTURE_AND_RECOVERY_PLAN_v0.4.md`: Vollständige Ist-Inventur, Gap-Analyse und Architektur-Spezifikation für v0.4.
|
||||
- `tests/`:
|
||||
- `test_orchestrator.py`: Unit-Tests für Backup-Phasen, Parallelität, Timeouts, Mount-Prüfung und Notifications.
|
||||
- `test_recovery.py`: Unit- und Integrationstests für Manifest-Validierung, 4-Stufen-Modell, Schema-Kompatibilitätsprüfung (`EXACT_MATCH`, `FORWARD_MIGRATE`, `INCOMPATIBLE_ROLLBACK`), Sicherheits-Gates (`pi-prod` Sperre, `--confirm`), Dry-Run-Pläne und `shinkan-backup-manifest`.
|
||||
|
||||
ZIP auf den Raspberry Pi übertragen und dort entpacken. Im entpackten Verzeichnis:
|
||||
---
|
||||
|
||||
## 2. CLI-Befehle (v0.4.0)
|
||||
|
||||
### A. Backup-Steuerung (unverändert kompatibel zu v0.3)
|
||||
|
||||
```bash
|
||||
backup-orchestrator --check
|
||||
backup-orchestrator --plan
|
||||
backup-orchestrator --status --json
|
||||
BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES backup-orchestrator --run
|
||||
BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES backup-orchestrator --run --phase 10
|
||||
BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES backup-orchestrator --run --job shinkan-prod-db
|
||||
```
|
||||
|
||||
### B. Recovery Management (neu in v0.4)
|
||||
|
||||
```bash
|
||||
# 1. Verfügbare Recovery Points auflisten (inkl. 4-Stufen-Status)
|
||||
backup-orchestrator --list-recovery-points
|
||||
backup-orchestrator --list-recovery-points --app shinkan --json
|
||||
|
||||
# 2. Einzelnen Recovery Point kryptografisch & strukturell prüfen
|
||||
backup-orchestrator --verify-recovery-point \
|
||||
--point /mnt/nas_backup/shinkan/prod/db/latest/shinkan-prod.sql
|
||||
|
||||
# 3. Dry-Run Recovery-Plan erstellen (inkl. Schema-Kompatibilitätsprüfung)
|
||||
backup-orchestrator --recovery-plan \
|
||||
--point /mnt/nas_backup/shinkan/prod/db/latest/shinkan-prod.sql \
|
||||
--target llm-prod
|
||||
|
||||
# 4. Isolierten Restore-Test ausführen (schreibgeschütztes Media-Mount, Ports 18003/13003)
|
||||
backup-orchestrator --restore-test \
|
||||
--point /mnt/nas_backup/shinkan/prod/db/latest/shinkan-prod.sql \
|
||||
--target llm-restoretest
|
||||
|
||||
# 5. Produktiver Application-Restore / Erstbefüllung auf llm-node
|
||||
backup-orchestrator --restore \
|
||||
--point /mnt/nas_backup/shinkan/prod/db/latest/shinkan-prod.sql \
|
||||
--target llm-prod \
|
||||
--confirm shinkan@llm-node
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Exit-Codes im Recovery-Modus
|
||||
|
||||
| Exit-Code | Bedeutung |
|
||||
|---|---|
|
||||
| `0` | Erfolgreich (`verified`/`consistent`/`restore_tested` bzw. Restore + `/api/health/ready` grün) |
|
||||
| `2` | Ungültige Argumente, fehlendes `--confirm`, gesperrtes Ziel (`pi-prod` ist `source_only`) oder Mount/Pfad fehlt |
|
||||
| `3` | Schema-/Versions-Inkompatibilität (`INCOMPATIBLE_ROLLBACK`: Dump enthält Migrationen, die im Ziel-Code fehlen) |
|
||||
| `4` | Integritätsfehler (SHA256-Prüfsumme weicht ab, Dump leer/korrupt oder Pflicht-Tabellen nach Staging-Import leer) |
|
||||
| `5` | Health-Check (`/api/health/ready`) nach DB-Umschaltung fehlgeschlagen – **automatisches Rollback auf `shinkan_before_<ts>` durchgeführt** |
|
||||
|
||||
---
|
||||
|
||||
## 4. Tests ausführen
|
||||
|
||||
```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.
|
||||
Alle Tests arbeiten ausschließlich in temporären Verzeichnissen mit synthetischen Dumps und berühren niemals produktive Datenbanken oder NAS-Mounts.
|
||||
Reference in new issue
Block a user