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, 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.

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.

S
Description
No description provided
Readme
323 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 87.1%
Shell 12.9%