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/<server>/), 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)
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- & Restore-Engines
│ │ ├── db-postgres-docker.sh # Universeller PostgreSQL-Dump
│ │ ├── db-mariadb-docker.sh # Universeller MariaDB-Dump
│ │ ├── publish-backup-set.sh # Erzeugt Manifest, Checksumme & relativen latest-Link
│ │ └── universal-db-restore # Universeller Staging-Restore für Postgres & MariaDB
│ └── shinkan/ # Spezifische Adapter für Shinkan (Pilot-Applikation)
│ ├── 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, kairo-pi-prod, tandoor-pi-prod, ...)
│ │ ├── 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 (shinkan, kairo, tandoor, bookstack...)
│ ├── 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
│ ├── APP_MIGRATION_CONTRACT.md # Entwickler-Leitfaden & Agenten-Prompt für App-Migrationen
│ └── UPTIME_KUMA_INTEGRATION.md # Push-Monitoring & Alerting-Konfiguration
└── tests/
├── test_orchestrator.py
├── test_recovery.py
└── test_universal_restore.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 <servername> und installiert genau die gemeinsame Engine + die zum jeweiligen Server gehörende Konfiguration nach /etc/backup-orchestrator/:
# 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.csvmithosts/<host>/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:
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)
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
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_<ts> durchgeführt |
5. Tests ausführen
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/*.