refactor(hosts): organize repository by server profiles (hosts/raspberrypi5, hosts/llm-node) and add host-aware installer

This commit is contained in:
Lars committed 2026-10-29 14:27:49 +01:00
1 parent c53fc0a939
commit c2740c9542
44 files changed
+528 -40

No files matched your search

+69 -28
View File
@@ -1,38 +1,79 @@
# Backup-Orchestrator v0.4 – Backup & Recovery Management
# Backup-Orchestrator v0.4 – Multi-Server 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`).
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 & Enthaltene Dateien
## 1. Repository-Struktur (nach Servern & gemeinsamen Modulen getrennt)
- `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`.
```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. CLI-Befehle (v0.4.0)
## 2. Server-spezifische Installation (`install.sh`)
### A. Backup-Steuerung (unverändert kompatibel zu v0.3)
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
@@ -73,7 +114,7 @@ backup-orchestrator --restore \
---
## 3. Exit-Codes im Recovery-Modus
## 4. Exit-Codes im Recovery-Modus
| Exit-Code | Bedeutung |
|---|---|
@@ -85,9 +126,9 @@ backup-orchestrator --restore \
---
## 4. Tests ausführen
## 5. 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.
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/*`.