6.1 KiB
6.1 KiB
Backup-Orchestrator v0.4 – Backup & Recovery Management
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. Repository-Struktur & Enthaltene Dateien
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, Targetspi-prod,llm-prod,llm-restoretest).jobs.csv: Produktive Backup-Job-Tabelle (17 Datenbank-Exporte in Phase 10,nas-datain Phase 20,system-imagein 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 fragilessystemctl disable/enable raspiBackup.timer).backup-orchestrator-daily.service&backup-orchestrator-daily.timer: Systemd-Units für den täglichen Lauf um05:30Uhr.
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-Enginesdb-postgres-docker.shunddb-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).
- Alle 17 Datenbank-Dump-Wrapper (
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 (Exit5).shinkan-media-diff: Abgleich zwischen PostgreSQL (media_assets,exercise_media), Dateisystem undmedia.jsonl(missing,mismatch,added_after_backup,orphan).shinkan-restore-test&docker-compose.restoretest.yml: Isolierter End-to-End-Restore-Test im Projektshinkan-restoretest(Ports127.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-prodSperre,--confirm), Dry-Run-Pläne undshinkan-backup-manifest.
2. CLI-Befehle (v0.4.0)
A. Backup-Steuerung (unverändert kompatibel zu v0.3)
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)
# 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
python3 -m unittest discover -s tests -v
Alle Tests arbeiten ausschließlich in temporären Verzeichnissen mit synthetischen Dumps und berühren niemals produktive Datenbanken oder NAS-Mounts.