Files
backup-orchestrator/docs/ARCHITECTURE_AND_RECOVERY_PLAN_v0.4.md

10 KiB
Raw Permalink Blame History

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:

  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 <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 auf shinkan_before_<ts> 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 <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

  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).