# Backup-Orchestrator 0.4 – Recovery Management: Bestandsaufnahme, Zielarchitektur & Umsetzungsplan Dieses Dokument bildet das Ergebnis von **Meilenstein 1 (Bestandsaufnahme und Architektur)** gemäß Abschnitt 16 & 18 des Entwicklungsauftrags. Alle Angaben zu Hosts, Pfaden, Skripten und Laufzuständen wurden am **2026-10-29** lesend auf `raspberrypi5` (`192.168.2.49`), `llm-node` (`192.168.2.144`) und im lokalen Shinkan-Repository (`C:/Dev/shinkan-jinkendo`) verifiziert. Der produktive Codebestand von Version `0.3.0` wurde zudem in das lokale Projektverzeichnis `C:/Dev/backup-orchestrator` übernommen. --- ## 1. Ist-Architektur und vorhandene Funktionen (Backup-Orchestrator 0.3.0) ### 1.1 Bestätigte Fakten (Inventar vom 2026-10-29) | Bereich | Bestätigter Ist-Zustand | Quelle / Nachweis | |---|---|---| | **Orchestrator-Code** | `orchestrator.py` (`VERSION = '0.3.0'`, SHA256 `0d07845b…`), identisch unter `/usr/local/sbin/backup-orchestrator`, `/home/lars/pi-backup-orchestrator/orchestrator.py` und `/home/lars/pi-backup-orchestrator-v0.3/orchestrator.py` auf `raspberrypi5`. | `sha256sum` auf `raspberrypi5` | | **Vorhandene Tests** | `tests/test_orchestrator.py` (`OrchestratorTests` + `NotificationTests`, 10 Unit-Tests mit temporären Dummy-Skripten und gemocktem HTTP). | `/home/lars/pi-backup-orchestrator/tests/test_orchestrator.py` | | **Konfiguration (`raspberrypi5`)** | `jobs.csv` (`/etc/backup-orchestrator/jobs.csv`, 19 Jobs: 17 DB-Jobs in Phase 10 `enabled=true`, `nas-data` in Phase 20 `enabled=true`, `system-image` in Phase 30 `enabled=false`). | `/etc/backup-orchestrator/jobs.csv` | | **Zeitsteuerung & Wrapper** | `backup-orchestrator-daily.timer` startet täglich um `05:30:00` den Oneshot-Service `/usr/local/sbin/backup-orchestrator-daily`. Dieser prüft `raspiBackup.service`, deaktiviert temporär `raspiBackup.timer` (Workaround für `legacy_schedules()`), setzt `BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES` und ruft `/usr/local/sbin/backup-orchestrator --run` auf. | `/usr/local/sbin/backup-orchestrator-daily` | | **Letzter Produktivlauf** | Am **2026-10-29 um 05:30:12** (`run_id`: `20261029-053012-4129246`) liefen alle 17 DB-Jobs (Phase 10, Dauer 0,32s–3,51s) sowie `nas-data` (Phase 20, Dauer 21,51s) fehlerfrei (`overall: "ok"`). | `/var/log/backup-orchestrator/latest.json` | | **Datenbank-Dumps (Phase 10)** | `db-postgres-docker.sh` (13 Docker-Postgres-DBs), `db-mariadb-docker.sh` (2 Docker-MariaDB/MySQL-DBs: `bookstack_db`, `karatewiki-dev-db-1`), sowie `db-paperless.sh` (mysqldump gegen `192.168.2.40:3308`) und `db-tandoor.sh` (`pg_dump` gegen `192.168.2.40:5432`). Alle schreiben atomar via `mktemp` + `mv -f` nach `/media/lars/paperless/db-backup/.sql` (`0640 root:lars`). | `/etc/backup-orchestrator/scripts/` | | **NAS-Datensicherung (Phase 20)** | `backup-nas-data.sh` sichert `/media/lars/paperless` (lokale NVMe `/dev/nvme0n1p2`) per `rsync -a -v -R --delete --stats --link-dest=/backup/data_archiv/last` in Tagesordner `/backup/data_archiv/01..31` (aktuell `last -> /backup/data_archiv/29`). Enthält außerdem historische zeitgestempelte Dumps (`*_20261002..20261028*.sql`). | `/backup/data_archiv/` | | **Vollständige Systemsicherung** | `raspiBackup.service` läuft täglich um `02:00` nach `/backup/backup/raspberrypi5/` (jüngster Stand: `raspberrypi5@debian12-rsync-backup-20261029-020053`). Stoppt vorab `apache2`, `mariadb`, `gitea-runner`, `docker`, `cron`, `containerd`. | `/usr/local/etc/raspiBackup.conf` | | **Borg-Repositories** | Auf `raspberrypi5`: `/backup/borg` ist initialisiert (`Oct 28 17:48`), enthält aber **noch keine Archive** (`data/0` hat nur 547 Bytes Init-Metadaten). Auf `llm-node`: `/mnt/nas_backup` (`192.168.2.63:/volume1/Backup_LLM`) enthält aktive Borg-Repos (`borg_repo`, `backup-repo`) sowie Disk-Images. | `/backup/borg`, `/mnt/nas_backup` | | **Zielhost `llm-node`** | `llm-node` (`192.168.2.144`, `x86_64`) hat `/etc/shinkan/prod.env` (`0600 llmadmin:llmadmin`), `/home/llmadmin/docker/shinkan-prod` (noch leer, da `Deploy Production llm-node` auf `main` noch nicht ausgelöst wurde) und den NFSv4-Mount `/srv/shinkan/prod/media` (`192.168.2.63:/volume1/shinkan-media/prod`). `backup-orchestrator` ist auf `llm-node` noch nicht installiert. | SSH-Inspektion `llmadmin@192.168.2.144` | --- ## 2. Ergebnisse aus der Shinkan-Recovery-Analyse Die Vorarbeiten im Shinkan-Repository (`.claude/docs/technical/PROD_DEPLOYMENTS.md` und `.claude/docs/technical/RECOVERY_CONTRACT.md`) definieren bereits einen präzisen Schnittstellenvertrag zwischen dem Backup-Orchestrator und Shinkan: 1. **Verantwortungstrennung (Orchestrator ↔ Anwendungs-Adapter):** - **Orchestrator:** Zeitsteuerung, Ausführung von Phasen/Jobs, Erzeugung der Dumps, Aufbewahrung/Generationen, NAS-Synchronisation, Ausführungshistorie, Benachrichtigungen (Kuma/Webhooks) sowie CLI-Steuerung für Recovery-Planung und -Auslösung. - **Anwendung (`scripts/ops/shinkan-*`):** Kennt die internen Details (Schema-Migrationen in `schema_migrations` gemäß `backend/run_migrations.py`, Pflicht-Tabellen & Readiness gemäß `health_ready()` in `backend/main.py`, Sessions-Bereinigung, Medien-Struktur unter `/app/media` mit `media_assets` und `exercise_media`). 2. **Definierte Shinkan-Kommandos & Exit-Code-Kontrakt:** - `shinkan-backup-manifest --target pi-prod|llm-prod --dump --out-dir --result ` - `shinkan-restore --target llm-prod|llm-restoretest --dump --result [--confirm @] [--allow-overwrite] [--sessions clear|keep]` - `shinkan-restore-test --dump --result [--playwright] [--keep]` - `shinkan-media-diff --target llm-prod|llm-restoretest --result [--manifest .media.jsonl]` - **Standardisierte Exit-Codes:** `0` = OK, `1` = Ausführungsfehler, `2` = Vorbedingung/Host/Bestätigung fehlt, `3` = Schema-/Versionsinkompatibilität (Dump enthält Migrationen, die der Code nicht kennt), `4` = Checksummenfehler, `5` = Post-Restore-Check fehlgeschlagen (automatischer Rollback auf `shinkan_before_` durchgeführt). 3. **Wichtige Erkenntnis zum Medienbestand von Shinkan:** - Auf `raspberrypi5` liegt `SHINKAN_MEDIA_HOST=/shinkan-media/prod` auf dem NFSv4-Share `192.168.2.63:/volume1/shinkan-media/prod`. Auf `llm-node` ist derselbe NFSv4-Share unter `/srv/shinkan/prod/media` eingebunden (`docker-compose.llm-node.yml`). - **Kritische Feststellung:** `/shinkan-media/prod` liegt bereits direkt auf dem Synology NAS, wird aber **nicht** durch `backup-nas-data.sh` (welches nur `/media/lars/paperless` sichert) in `/backup/data_archiv/01..31` versioniert! Während des Parallelbetriebs zwischen `raspberrypi5` und `llm-node` teilen sich beide Umgebungen denselben physischen Medienbestand, weshalb `retention-cron` auf `llm-node` über das Compose-Profil `media-retention` deaktiviert bleibt. --- ## 3. Gap-Analyse: Backup-Orchestrator 0.3 vs. Recovery Management 0.4 | Anforderung (Auftrag 0.4) | Stand in Backup-Orchestrator 0.3.0 | Identifizierte Lücke (Gap) & Risiko | |---|---|---| | **Multi-Host-Fähigkeit (`raspberrypi5` & `llm-node`)** | `orchestrator.py` hat `NAS_MOUNT = '/backup'` und `NAS_SOURCE = '192.168.2.63:/volume1/Backup_Paperless'` hartcodiert; `legacy_schedules()` prüft hart den User `lars` und Pi-spezifische Timer. | Läuft auf `llm-node` (`/mnt/nas_backup`, User `llmadmin`) nicht ohne Konfigurationsabstraktion (`host.json` / Host-Profile). | | **Timer-Koordination (`raspiBackup`)** | `legacy_schedules()` blockiert jeden Lauf, sobald `raspiBackup.timer` `enabled` ist – selbst wenn `raspiBackup.service` gar nicht läuft. Deshalb deaktiviert `/usr/local/sbin/backup-orchestrator-daily` den Timer vor jedem Lauf per Workaround. | Muss durch eine zustandsbewusste Prüfung ersetzt werden: `raspiBackup.service` darf nicht `active`/`activating` sein; ein ruhender Timer um 05:30 Uhr ist kein Konflikt. | | **Recovery Points & Manifeste** | Erzeugt nur isolierte `.sql`-Dateien unter festem Namen (`shinkan-prod.sql`). Keine `.sha256`, kein Release-/Commit-/Schema-Manifest, kein Medien-Manifest. | Nach einem Ausfall ist im Dump nicht ohne Weiteres erkennbar, welcher `git_commit`, welche `app_version`, welche `last_migration` und welcher Medienstand dazugehören. | | **Generationen für DB-Sätze** | Lokal wird `.sql` täglich überschrieben; in `/backup/data_archiv/01..31` liegt nur 1 Stand pro Kalendertag ohne atomares Backup-Satz-Bündel (Dump + `.sha256` + Manifest + Media-Index). | Wenn ein verkürzter/fehlerhafter Lauf oder ein 2-stündlicher Takt eingeführt wird, fehlt eine generationssichere Rotation vollständiger Backup-Sätze (`pi-prod` vs. `llm-prod` getrennt). | | **Versions- & Schemakompatibilität** | Keine Prüfung zwischen Datenbank-Migrationsstand (`schema_migrations`) und Ziel-Code (`backend/migrations/*.sql`). | Risiko von Rollback-Brüchen (DB hat neuere Migrationen als der Code) oder unbemerkten Schema-Drifts. | | **Recovery-Planung (`--recovery-plan`) & Ausführung (`--restore`)** | CLI unterstützt nur `--check`, `--plan`, `--status`, `--run`. Keine Recovery-Befehle, kein Dry-Run-Plan, kein Staging-DB-Swap, kein Audit-Log für Restores. | Vollständige Erweiterung um Recovery-Subkommandos bzw. Modi erforderlich. | | **Shinkan-Skripte (`scripts/ops/shinkan-*`)** | In `RECOVERY_CONTRACT.md` spezifiziert (`Status: Entwurf zur Abstimmung, nichts umgesetzt`), unter `C:/Dev/shinkan-jinkendo/scripts/ops/` noch nicht angelegt. | Müssen (nach expliziter Freigabe für das Shinkan-Repo) exakt nach Vertrag implementiert werden. | --- ## 4. Zielarchitektur und Recovery-Point-Datenmodell Siehe `recovery_management_plan_v0_4.md` für das vollständige JSON-Schema (`schemaVersion: 1`) sowie die 4 Validierungsstufen (`captured`, `verified`, `consistent`, `restore_tested`). --- ## 5. Priorisierter Implementierungsplan 1. **Meilenstein 1:** Bestandsaufnahme & Architekturkonzept (abgeschlossen). 2. **Meilenstein 2:** Recovery-Metadaten, Host-Abstraktion (`host.json`), zustandsbewusste `raspiBackup`-Koordination, Manifest-Schema v1, Backup-Satz-Rotation und `shinkan-backup-manifest`. 3. **Meilenstein 3:** Application Restore MVP (`--list-recovery-points`, `--recovery-plan`, `--restore`, `--restore-test`), `shinkan-restore`, `shinkan-restore-test`, `shinkan-media-diff` sowie Durchführung der Shinkan-Erstbefüllung auf `llm-node`. 4. **Meilenstein 4:** Generische PostgreSQL-/MariaDB-Restore-Adapter für die weiteren 16 DBs sowie Storage-/Borg-Adapter. 5. **Meilenstein 5:** System-Recovery-Prozess (`raspiBackup` + Application Recovery).