Files
backup-orchestrator/README.md
T

139 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)
```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- & 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/`:
```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/<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:
```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_<ts>` 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/*`.