Files
backup-orchestrator/README.md
T

6.4 KiB
Raw Blame History

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-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 <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.csv mit hosts/<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/*.