10 KiB
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/<name>.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:
- 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 inschema_migrationsgemäßbackend/run_migrations.py, Pflicht-Tabellen & Readiness gemäßhealth_ready()inbackend/main.py, Sessions-Bereinigung, Medien-Struktur unter/app/mediamitmedia_assetsundexercise_media).
- Definierte Shinkan-Kommandos & Exit-Code-Kontrakt:
shinkan-backup-manifest --target pi-prod|llm-prod --dump <datei> --out-dir <verzeichnis> --result <json>shinkan-restore --target llm-prod|llm-restoretest --dump <datei> --result <json> [--confirm <db>@<host>] [--allow-overwrite] [--sessions clear|keep]shinkan-restore-test --dump <datei> --result <json> [--playwright] [--keep]shinkan-media-diff --target llm-prod|llm-restoretest --result <json> [--manifest <dump>.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 aufshinkan_before_<ts>durchgeführt).
- Wichtige Erkenntnis zum Medienbestand von Shinkan:
- Auf
raspberrypi5liegtSHINKAN_MEDIA_HOST=/shinkan-media/prodauf dem NFSv4-Share192.168.2.63:/volume1/shinkan-media/prod. Aufllm-nodeist derselbe NFSv4-Share unter/srv/shinkan/prod/mediaeingebunden (docker-compose.llm-node.yml). - Kritische Feststellung:
/shinkan-media/prodliegt bereits direkt auf dem Synology NAS, wird aber nicht durchbackup-nas-data.sh(welches nur/media/lars/paperlesssichert) in/backup/data_archiv/01..31versioniert! Während des Parallelbetriebs zwischenraspberrypi5undllm-nodeteilen sich beide Umgebungen denselben physischen Medienbestand, weshalbretention-cronaufllm-nodeüber das Compose-Profilmedia-retentiondeaktiviert bleibt.
- Auf
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 <app>.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
- Meilenstein 1: Bestandsaufnahme & Architekturkonzept (abgeschlossen).
- Meilenstein 2: Recovery-Metadaten, Host-Abstraktion (
host.json), zustandsbewussteraspiBackup-Koordination, Manifest-Schema v1, Backup-Satz-Rotation undshinkan-backup-manifest. - Meilenstein 3: Application Restore MVP (
--list-recovery-points,--recovery-plan,--restore,--restore-test),shinkan-restore,shinkan-restore-test,shinkan-media-diffsowie Durchführung der Shinkan-Erstbefüllung aufllm-node. - Meilenstein 4: Generische PostgreSQL-/MariaDB-Restore-Adapter für die weiteren 16 DBs sowie Storage-/Borg-Adapter.
- Meilenstein 5: System-Recovery-Prozess (
raspiBackup+ Application Recovery).