refactor(hosts): organize repository by server profiles (hosts/raspberrypi5, hosts/llm-node) and add host-aware installer
This commit is contained in:
1 parent
c53fc0a939
commit
c2740c9542
44 files changed
+528
-40
No files matched your search
@@ -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/*`.
|
||||
Reference in new issue
Block a user