94 lines
6.1 KiB
Markdown
94 lines
6.1 KiB
Markdown
# Backup-Orchestrator v0.4 – Backup & Recovery Management
|
||
|
||
**Status: Version 0.4.0 (Multi-Host Backup & Application Recovery Management).**
|
||
Erweitert den auf `raspberrypi5` produktiv laufenden Backup-Orchestrator v0.3 um ein integriertes Recovery Management, kryptografisch geprüfte Recovery Points (`schemaVersion: 1`), ein 4-stufiges Verifikationsmodell (`captured` → `verified` → `consistent` → `restore_tested`), einen zustandsbewussten `raspiBackup.service`-Konflikt-Check sowie vollständige Application-Restore- und Restore-Test-Adapter für die Referenzanwendung **Shinkan** auf `llm-node` (`192.168.2.144`).
|
||
|
||
---
|
||
|
||
## 1. Repository-Struktur & Enthaltene Dateien
|
||
|
||
- `orchestrator.py`: Phasenbasierter Backup- & Recovery-Controller (`v0.4.0`, Python 3.11+, nur Standardbibliothek).
|
||
- `targets.json`: Multi-Host- und Recovery-Target-Definitionen (`raspberrypi5`, `llm-node`, Targets `pi-prod`, `llm-prod`, `llm-restoretest`).
|
||
- `jobs.csv`: Produktive Backup-Job-Tabelle (17 Datenbank-Exporte in Phase 10, `nas-data` in Phase 20, `system-image` in Phase 30).
|
||
- `notifications.json.example`: Beispielkonfiguration für ausgehende HTTP-POST-Webhooks und Uptime-Kuma-Push-Monitore (enthält keine echten Secrets).
|
||
- `systemd/`:
|
||
- `backup-orchestrator-daily`: Täglicher Runner-Wrapper (ab v0.4 ohne fragiles `systemctl disable/enable raspiBackup.timer`).
|
||
- `backup-orchestrator-daily.service` & `backup-orchestrator-daily.timer`: Systemd-Units für den täglichen Lauf um `05:30` Uhr.
|
||
- `scripts/`:
|
||
- Alle 17 Datenbank-Dump-Wrapper (`db-bookstack.sh`, `db-buyingagent-dev.sh`, `db-buyingagent-prod.sh`, `db-kairo-dev.sh`, `db-kairo-prod.sh`, `db-kansho-dev.sh`, `db-kansho-prod.sh`, `db-karatewiki-dev.sh`, `db-mitai-dev.sh`, `db-mitai-prod.sh`, `db-netbox.sh`, `db-paperless.sh`, `db-shinkan-dev.sh`, `db-shinkan-prod.sh`, `db-tandoor.sh`, `db-tandoor.sh`, `db-tsumugu-dev.sh`, `db-tsumugu-prod.sh`) sowie die generischen Dump-Engines `db-postgres-docker.sh` und `db-mariadb-docker.sh`.
|
||
- `backup-nas-data.sh` & `nas-data-job.sh`: Versionierte rsync-Hardlink-Sicherung (`/media/lars/paperless` → `/backup/data_archiv/01..31` + `last`).
|
||
- `publish-backup-set.sh` & `shinkan-prod-manifest.sh`: Atomare Erzeugung und Publikation vollständiger Backup-Sets (`<dump>.sql`, `<dump>.sql.sha256`, `<dump>.sql.manifest.json`, `<dump>.sql.media.jsonl`).
|
||
- `scripts/shinkan/` (Shinkan Recovery Contract Adapter):
|
||
- `shinkan-backup-manifest`: Erzeugt SHA256, Manifest (`schemaVersion: 1` + Shinkan Contract) und inkrementelles Media-Inventar (`media.jsonl`).
|
||
- `shinkan-restore`: 9-stufiger atomarer Application-Restore über Staging-DB (`shinkan_restore_<ts>`), Single-Transaction-Import, Schema-Migrations-Gate, Plausibilitätsprüfung, `TRUNCATE sessions`, DB-Swap (`shinkan_before_<ts>`), `/api/health/ready`-Prüfung und automatischem Rollback bei Fehlern (Exit `5`).
|
||
- `shinkan-media-diff`: Abgleich zwischen PostgreSQL (`media_assets`, `exercise_media`), Dateisystem und `media.jsonl` (`missing`, `mismatch`, `added_after_backup`, `orphan`).
|
||
- `shinkan-restore-test` & `docker-compose.restoretest.yml`: Isolierter End-to-End-Restore-Test im Projekt `shinkan-restoretest` (Ports `127.0.0.1:18003` / `127.0.0.1:13003`, Read-Only-Media `:ro`, deaktivierte externe Integrationen & Cronjobs).
|
||
- `docs/ARCHITECTURE_AND_RECOVERY_PLAN_v0.4.md`: Vollständige Ist-Inventur, Gap-Analyse und Architektur-Spezifikation für v0.4.
|
||
- `tests/`:
|
||
- `test_orchestrator.py`: Unit-Tests für Backup-Phasen, Parallelität, Timeouts, Mount-Prüfung und Notifications.
|
||
- `test_recovery.py`: Unit- und Integrationstests für Manifest-Validierung, 4-Stufen-Modell, Schema-Kompatibilitätsprüfung (`EXACT_MATCH`, `FORWARD_MIGRATE`, `INCOMPATIBLE_ROLLBACK`), Sicherheits-Gates (`pi-prod` Sperre, `--confirm`), Dry-Run-Pläne und `shinkan-backup-manifest`.
|
||
|
||
---
|
||
|
||
## 2. CLI-Befehle (v0.4.0)
|
||
|
||
### A. Backup-Steuerung (unverändert 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
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 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** |
|
||
|
||
---
|
||
|
||
## 4. Tests ausführen
|
||
|
||
```bash
|
||
python3 -m unittest discover -s tests -v
|
||
```
|
||
Alle Tests arbeiten ausschließlich in temporären Verzeichnissen mit synthetischen Dumps und berühren niemals produktive Datenbanken oder NAS-Mounts.
|