135 lines
6.4 KiB
Markdown
135 lines
6.4 KiB
Markdown
# 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-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/`:
|
||
|
||
```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/*`.
|