Files
backup-orchestrator/README.md
T

94 lines
6.1 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 – 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.