# Backup-Orchestrator v0.4 – Multi-Server Backup & Recovery Management **Status: Version 0.4.0 (Multi-Host Backup & Application Recovery Management).** Erweitert den Backup-Orchestrator v0.3 um eine **server-spezifische Repository-Struktur (`hosts//`)**, ein integriertes Recovery Management mit kryptografisch geprüften Recovery Points (`schemaVersion: 1`), ein 4-stufiges Verifikationsmodell (`captured` → `verified` → `consistent` → `restore_tested`), einen zustandsbewussten `raspiBackup.service`-Check sowie vollständige Application-Restore- und Restore-Test-Adapter für **Shinkan** auf `llm-node` (`192.168.2.144`). --- ## 1. Repository-Struktur (nach Servern & gemeinsamen Modulen getrennt) ```text backup-orchestrator/ ├── orchestrator.py # Universeller Backup- & Recovery-Controller (v0.4.0) ├── install.sh # Server-spezifischer Installer (--host raspberrypi5 | llm-node) ├── targets.json # Globale Target-Registry ├── scripts/ │ ├── common/ # Gemeinsame, serverunabhängige Backup-Engines │ │ ├── db-postgres-docker.sh │ │ ├── db-mariadb-docker.sh │ │ └── publish-backup-set.sh │ └── shinkan/ # Anwendungs-Adapter für Shinkan (Recovery Contract) │ ├── shinkan-backup-manifest │ ├── shinkan-restore │ ├── shinkan-restore-test │ ├── shinkan-media-diff │ └── docker-compose.restoretest.yml ├── hosts/ # Server-spezifische Profile, Jobs, Wrapper & Systemd-Units │ ├── raspberrypi5/ # Produktiver Backup-Host (Debian 12 ARM64, 192.168.2.49) │ │ ├── host.json # Mounts (/backup), Pfade (/media/lars/paperless/db-backup) │ │ ├── jobs.csv # 17 DB-Jobs (Phase 10), nas-data (Phase 20), system-image (Phase 30) │ │ ├── targets.json # Host-Targets (pi-prod = source_only) │ │ ├── notifications.json.example │ │ ├── scripts/ # Alle 17 DB-Wrapper + NAS-Skripte für raspberrypi5 │ │ └── systemd/ # backup-orchestrator-daily + .service/.timer (05:30 Uhr) │ └── llm-node/ # Neuer Anwendungs- & Recovery-Host (Ubuntu 24.04 x86_64, 192.168.2.144) │ ├── host.json # Mounts (/mnt/nas_backup, /srv/shinkan/prod/media) │ ├── jobs.csv # Backup-Jobs auf llm-node (shinkan-prod-db für Post-Cutover vorbereitet) │ ├── targets.json # Targets (llm-prod, llm-restoretest, pi-prod = source_only) │ ├── notifications.json.example │ ├── scripts/ # Host-spezifische Wrapper für llm-node │ └── systemd/ # backup-orchestrator-daily + .service/.timer (05:00 Uhr) ├── docs/ │ └── ARCHITECTURE_AND_RECOVERY_PLAN_v0.4.md └── tests/ ├── test_orchestrator.py └── test_recovery.py ``` --- ## 2. Server-spezifische Installation (`install.sh`) Auf jedem Server (`raspberrypi5` oder `llm-node`) erkennt `install.sh` automatisch den Hostnamen (`hostname -s`) oder akzeptiert `--host ` und installiert genau die gemeinsame Engine + die zum jeweiligen Server gehörende Konfiguration nach `/etc/backup-orchestrator/`: ```bash # Auf raspberrypi5: sudo ./install.sh --host raspberrypi5 # Auf llm-node: sudo ./install.sh --host llm-node ``` Optional: - `--force-jobs`: Überschreibt eine bereits vorhandene `/etc/backup-orchestrator/jobs.csv` mit `hosts//jobs.csv`. - `--install-systemd`: Installiert und lädt die zum Server gehörenden Systemd-Units (`backup-orchestrator-daily.service` & `.timer`). Auch direkt aus dem Git-Arbeitsverzeichnis können Konfigurationen jedes Servers über `--host` geprüft werden: ```bash python3 orchestrator.py --plan --host raspberrypi5 python3 orchestrator.py --plan --host llm-node ``` --- ## 3. CLI-Befehle (v0.4.0) ### A. Backup-Steuerung (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 ``` --- ## 4. 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_` durchgeführt** | --- ## 5. Tests ausführen ```bash python3 -m unittest discover -s tests -v ``` Alle 23 Tests arbeiten ausschließlich in temporären Verzeichnissen mit synthetischen Dumps und prüfen zusätzlich die Vollständigkeit aller Server-Profile unter `hosts/*`.