Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
master
homelab-infra/docs/RESTORE_MATRIX.md
T

14 KiB
Raw Permalink Blame History

Restore Matrix - KalliLab CORE

Diese Matrix beschreibt fuer die wichtigsten Dienste:

  • was die fuehrende Restore-Quelle ist
  • welche Pfade oder Dumps relevant sind
  • welche Secrets gebraucht werden
  • wovon der Dienst abhaengt
  • wie ein sinnvoller Smoke-Test aussieht

Sie ist die fachliche Ergaenzung zu docs/DISASTER_RECOVERY.md.

Legende

  • Fuehrende Quelle = die primaere Restore-Wahrheit fuer diesen Dienst
  • Datei-Restore = relevante Verzeichnisse / Volume-Pfade
  • Dump / DB = relevante Dump-Artefakte oder Datenbankabhaengigkeiten
  • Secrets / ENV = Dinge, die vor dem Start wieder da sein muessen
  • Smoke-Test = minimaler Nachweis, dass der Restore wirklich greift

Tier 1 - Kritisch fuer Wiederanlauf

Dienst Fuehrende Quelle Datei-Restore Dump / DB Secrets / ENV Abhaengigkeiten Smoke-Test
Unraid OS Flash Borg-Artefakt + optional Unraid Connect /boot/config aus unraid-flash-config.tar.gz unraid-flash-config.tar.gz, .sha256, Manifest enthaelt sensible Host-Konfiguration, wie Secret-Material behandeln Unraid USB Flash Creator / neuer Boot-Stick Unraid bootet, Array-Zuordnung und Shares sind sichtbar
Traefik Share / Borg /mnt/user/appdata/traefik, besonders dynamic/, letsencrypt, secrets keine eigene DB cloudflare_dns_api_token frontend_net, backend_net https://traefik.kaleschke.info erreichbar, Dashboard ueber Authelia
AdGuard Home Share / Borg /mnt/user/appdata/adguard/conf keine keine zusaetzlichen Repo-Secrets dokumentiert dns_net, frontend_net DNS-Aufloesung funktioniert
Tailscale Share / Borg /mnt/user/appdata/tailscale keine Tailscale-State im Pfad Host-Netz Tailscale verbunden
PostgreSQL 18 Share + Dumps /mnt/user/appdata/postgresql18 (Rollback-Altstand: /mnt/user/appdata/postgresql17) postgresql17-globals.sql, postgresql17-mailarchiver.dump, postgresql17-paperless.dump, optional postgresql17-authelia.dump postgres_password.txt, App-Rollen-Passwoerter aus den jeweiligen Stack-ENV/Secret-Dateien backend_net DB startet, Ziel-Datenbanken vorhanden; SHOW data_checksums ist on
Redis 8 Share / Host /mnt/user/appdata/redis; Rollback-Backup unter /mnt/user/backups/borg/dumps/latest/shared-redis-pre-redis8-<ts> RDB/AOF-Dateien im Datenpfad redis_password.txt backend_net Redis startet, redis_version ist 8.x, Apps verbinden sich
Authelia Borg /mnt/user/appdata/authelia/config, /mnt/user/appdata/secrets/*authelia* Shared PostgreSQL 18, optional Dump postgresql17-authelia.dump JWT/Session/Storage/Postgres-/SMTP-Secret-Dateien PostgreSQL 18, Traefik, GMX SMTP Login-Seite und ForwardAuth funktionieren; SMTP-Notifier startet; aktive Sessions werden nach Restart neu aufgebaut
Gitea GitHub-Mirror + Gitea-Bundles fuer Repo-Bootstrap, Borg + Dump fuer Gitea-Appstate /mnt/user/services/gitea/data, /mnt/user/backups/git-bundles/gitea gitea.sqlite.dump, Bundle-Report latest-report.md borg_repo_passphrase.txt fuer Restore-Tests; GitHub-Push-Mirror-PAT liegt nur in Gitea-Mirror-Settings Traefik Web-UI erreichbar, Repo sichtbar, SSH-Port reagiert; Bundle laesst sich klonen und git fsck ist sauber; GitHub-Push-Mirror synchronisiert ohne last_error; Mini-Restore nach /mnt/user/backups/restore-lab/gitea am 2026-05-07 erfolgreich validiert
Komodo Borg / Share /mnt/user/appdata/komodo/core, /mnt/user/appdata/komodo/periphery, /mnt/user/services/stacks komodo-mongo.archive.gz falls verifiziert komodo_mongo_password.txt, KOMODO_* Stack ENV Traefik, Mongo, Gitea UI erreichbar, Periphery verbunden
GitOps Host Automation Borg / Git /mnt/user/services/homelab-infra, /mnt/user/services/posture-check keine eigene DB keine Gitea, Komodo, Unraid User Scripts posture-check laeuft vom Host-Pfad und liefert warning_count: 0 im bekannten Uebergangszustand
Vaultwarden Borg + Dump /mnt/user/appdata/vaultwarden vaultwarden.sqlite.dump vaultwarden_admin_token.txt, borg_repo_passphrase.txt fuer Restore-Tests Traefik Login-Seite erreichbar, Tresor-Daten sichtbar; Mini-Restore nach /mnt/user/backups/restore-lab/vaultwarden am 2026-05-07 erfolgreich validiert

Tier 2 - Wichtige Anwendungen

Dienst Fuehrende Quelle Datei-Restore Dump / DB Secrets / ENV Abhaengigkeiten Smoke-Test
Paperless-ngx Borg + Dumps /mnt/user/appdata/paperless-ngx/data, /mnt/user/documents/paperless, /mnt/user/documents/paperless/export, /mnt/user/documents/scans_inbox postgresql17-paperless.dump PAPERLESS_DBPASS, PAPERLESS_REDIS, borg_repo_passphrase.txt fuer Restore-Tests PostgreSQL 18, Redis, Traefik Web-UI startet, Dokumente vorhanden; Restore-Test am 2026-05-31 erfolgreich: Borg-Archiv Tägliche-Sicherung-2026-05-31T04:30:13.181, isolierter PostgreSQL-18-/Redis-8-Testpfad, HTTP 200, 32 Dokumente im Test-DB-Check, Report /mnt/user/backups/restore-reports/paperless-2026-05-31.md
Mealie Borg + Dump /mnt/user/appdata/mealie/data, /mnt/user/appdata/mealie/postgres18 (Rollback-Altstand: /mnt/user/appdata/mealie/postgres) mealie.dump mealie_postgres_password.txt mealie-postgres, Traefik UI startet, Rezepte vorhanden
Immich Borg + Dump /mnt/user/photos/immich, /mnt/user/photos/family_archive, /mnt/user/appdata/immich_postgres_vectorchord; Rollback-Altstand: /mnt/user/appdata/immich_postgres immich.dump; nach VectorChord braucht ein Restore ein Postgres-Image mit VectorChord IMMICH_DB_PASSWORD, immich_postgres_password.txt, borg_repo_passphrase.txt fuer Restore-Tests immich_postgres, immich_redis, Traefik DB- und UI-Smoke gegen produktives Borg-Archiv am 2026-05-27 erfolgreich validiert; VectorChord-Migration am 2026-05-31: 11977 Assets, 11107 Smart-Search-Zeilen, 7092 Face-Search-Zeilen, vchord 0.4.3, vector 0.8.1, HTTP/API-Smoke 200. Voll-Restore der Foto-Dateien bleibt separater DR-Drill
Mail-Archiver Borg + Shared Dump /mnt/user/appdata/mailarchiver/data-protection-keys postgresql17-mailarchiver.dump MAILARCHIVER_DB_CONNECTION, MAILARCHIVER_AUTH_PASSWORD PostgreSQL 18, Traefik, Authelia Authelia-Weiterleitung greift; nach Login startet die Web-UI und das Archiv laesst sich oeffnen
Nextcloud Borg + Dump /mnt/user/appdata/nextcloud/html, /mnt/user/documents/nextcloud-data, /mnt/user/appdata/nextcloud/postgres18 (Rollback-Altstand: /mnt/user/appdata/nextcloud/postgres), /mnt/user/appdata/nextcloud/redis nextcloud.dump; Redis-Backup vor Redis-8-Cutover unter /mnt/user/backups/borg/dumps/latest/nextcloud-redis-pre-redis8-<ts> nextcloud_admin_user.txt, nextcloud_admin_password.txt, nextcloud_postgres_password.txt; produktive DB-Rolle laut config.php ist oc_admin nextcloud-postgres, nextcloud-redis, Traefik Web-UI startet, Login funktioniert, Dateien sichtbar; occ status zeigt maintenance: false
Glance Git / Borg-Repo Repo-Konfiguration unter ops/glance/config/glance.yml; keine kritische Datenpersistenz keine GLANCE_IMMICH_API_KEY, GLANCE_ADGUARD_USERNAME, GLANCE_ADGUARD_PASSWORD, GLANCE_SPEEDTEST_API_KEY Traefik, Authelia, optional interne API-Ziele Dashboard startet, Widgets laden, Docker-Status laeuft nur ueber glance-docker-socket-proxy
ntfy Borg / Share /mnt/user/appdata/ntfy keine keine besonderen Secret-Dateien dokumentiert Traefik UI und Push-Endpunkt erreichbar
Paperless-GPT Borg / Share /mnt/user/appdata/paperless-gpt keine eigene DB PAPERLESS_API_TOKEN, OPENAI_API_KEY Traefik, Paperless, OpenAI API UI startet, Konfiguration vorhanden; LLM-Provider zeigt openai / gpt-5.4-mini

Tier 3 - Rebuildbar / Sekundaer

Dienst Fuehrende Quelle Datei-Restore Dump / DB Secrets / ENV Abhaengigkeiten Smoke-Test
Borg UI Borg + Dump /mnt/user/appdata/borg-ui/data borg-ui.sqlite Borg-Repo-Creds in /data Traefik UI startet, Repo-Verbindung bekannt
Filebrowser Share / Fresh + Dump /mnt/user/appdata/filebrowser filebrowser.bolt.dump filebrowser_admin_password.txt bei Fresh-Rebuild Traefik, Authelia UI startet, Admin-User vorhanden
Glances Rebuildbar kein kritischer Zustand keine keine Traefik, Authelia UI startet
Scrutiny Teilweise rebuildbar /mnt/user/appdata/scrutiny falls gewuenscht InfluxDB bewusst nicht Teil des Critical-Scope keine Traefik, Authelia UI startet, Laufwerke sichtbar
Speedtest Tracker Share + Dump /mnt/user/appdata/speedtest-tracker/config speedtest-tracker.sqlite.dump APP_KEY, ADMIN_PASSWORD Traefik, Authelia UI startet
BentoPDF Rebuildbar keine kritische Persistenz; alte Stirling-PDF-Daten unter /mnt/user/appdata/stirling-pdf bis zur Abnahme behalten keine keine separaten Secret-Dateien dokumentiert Traefik, Authelia UI startet, PDF-Tools verfuegbar, Office-Konvertierung ueber HTTPS funktioniert
Grafana historischer Altstand /mnt/user/appdata/grafana grafana.sqlite grafana_admin_password.txt, grafana_influxdb_token.txt nicht aktiv Compose-Pfad aus aktivem Repo entfernt; nur ueber Git-Historie wiederherstellen, falls ein Rollback wirklich noetig ist
InfluxDB 3 Core historischer Altstand / Datenuebernahme /mnt/user/appdata/influxdb3/data, /mnt/user/appdata/influxdb3/plugins dateibasierter Object Store influxdb3_admin_token.json monitoring-influxdb3-core Datenpfad wird vom Monitoring-Zielstack weitergenutzt und darf nicht blind geloescht werden
Loki / Alloy historischer Altstand /mnt/user/appdata/loki/config, /mnt/user/appdata/loki/data, /mnt/user/appdata/alloy/config keine primaere DB; Loki-Dateispeicher war transient keine zusaetzlichen Secrets nicht aktiv Compose-Pfad aus aktivem Repo entfernt; aktuelle Logsammlung laeuft ueber monitoring-loki/monitoring-promtail
Monitoring Stack Rebuild + named volumes + InfluxDB-Appdata prometheus_data, loki_data, promtail_positions, grafana_data; InfluxDB unter /mnt/user/appdata/influxdb3/data und /mnt/user/appdata/influxdb3/plugins; Provisioning aus monitoring/grafana/provisioning Prometheus-TSDB, Loki-Dateispeicher und InfluxDB-Dateistore; Diagnose-/Langzeitdaten, keine Tier-1-Restore-Quelle monitoring_grafana_admin_password.txt, monitoring_grafana_influxdb_token.txt, influxdb3_admin_token.json monitoring_net, monitoring_influx_lan, frontend_net, Traefik, Authelia, Docker socket read-only fuer Promtail, Host-Mounts fuer node-exporter/cAdvisor https://monitoring.kaleschke.info leitet zu Authelia; Prometheus Targets sind up; Grafana-Datasources Prometheus, Loki und InfluxDB 3 Core funktionieren
Hermes Agent VM-seitig offen /mnt/user/appdata/hermes-agent/data, /mnt/user/appdata/hermes-agent/ssh keine eigene DB Host-.env fuer Provider-/API-/Home-Assistant-Tokens, hermes_runner_id_ed25519, HERMES_DASHBOARD_HOST separate Hermes-VM/Runner, Traefik, Authelia, hermes_net NAS-Stack nicht starten, solange Runner-VM und echte .env fehlen
ddns-updater Rebuildbar geringe Persistenzrelevanz keine Provider-Zugang ueber Stack ENV Internetzugang Update-Job laeuft

Dumps und Restore-Artefakte

Aktuell relevante Dump-Artefakte unter /mnt/user/backups/borg/dumps/latest:

  • postgresql17-globals.sql
  • postgresql17-mailarchiver.dump
  • postgresql17-paperless.dump
  • postgresql17-authelia.dump (optional / wenn vorhanden)
  • mealie.dump
  • immich.dump
  • nextcloud.dump
  • gitea.sqlite.dump
  • vaultwarden.sqlite.dump
  • speedtest-tracker.sqlite.dump
  • filebrowser.bolt.dump
  • borg-ui.sqlite
  • grafana.sqlite
  • unraid-flash-config.tar.gz plus unraid-flash-config.tar.gz.sha256 und Manifest
  • Monitoring-Stack: keine verpflichtenden Dump-Artefakte; Prometheus/Loki/Grafana named volumes sind Diagnose-/Dashboard-Zustand, keine primaere Restore-Quelle.
  • komodo-mongo.archive.gz (noch gesondert verifizieren)

Die Dump-Erzeugung ist host-seitig ueber ops/borg-ui/scripts/pre-backup-dumps.sh vorgesehen.

PostgreSQL 18 Restore- und Rollback-Regeln

  • PostgreSQL-18-Container verwenden das Docker-Image-Layout mit Mount auf /var/lib/postgresql und PGDATA=/var/lib/postgresql/18/docker.
  • Die alten PostgreSQL-17-Datenpfade bleiben nach dem Major-Upgrade als Rollback-Altstand erhalten und duerfen erst nach separater Freigabe geloescht werden.
  • Shared-Cluster-Restore: zuerst pg_dumpall --globals-only einspielen, dann die einzelnen Custom-Format-Dumps per pg_restore. Der Bootstrap-Rollenkonflikt fuer mailarchiver ist benign, solange CREATE ROLE mailarchiver; gezielt ausgelassen und das folgende ALTER ROLE mailarchiver ... eingespielt wird.
  • Nextcloud-Restore: vor dem Dump occ maintenance:mode --on, nach erfolgreichem Restore und occ status wieder occ maintenance:mode --off. Die Rolle oc_admin muss mit dem in config.php hinterlegten DB-Passwort existieren.
  • Rollback: betroffene App(s) und DB stoppen, Compose auf das vorherige PostgreSQL-17-Image und den alten Datenpfad zuruecksetzen, dann DB und App wieder starten.

Praktische Restore-Regeln

  • Nicht mehrere kritische Dienste gleichzeitig restaurieren.
  • Erst die Abhaengigkeiten wiederherstellen, dann die App.
  • Bei Unsicherheit zuerst in Testpfade oder Testinstanzen pruefen.
  • Der minimale Erfolg ist nicht "Container startet", sondern "fachlicher Smoke-Test gelingt".

Validiertes Restore-Lab-Muster

  • Restore-Quelle bleibt das produktive Borg-Repo
  • Testziel liegt unter /mnt/user/backups/restore-lab/<dienst>
  • Reports liegen unter /mnt/user/backups/restore-reports
  • Borg-Zugriff kann ueber den vorhandenen borg-ui-Container laufen
  • Borg-Passphrasen fuer Restore-Tests sollten aus Host-Secret-Dateien kommen, nicht aus UI-Interna
  • Testinstanzen bekommen keine produktive Domain und keine Traefik-Route

Erste sinnvolle Referenz-Restores

Wenn weitere Restore-Uebungen dokumentiert werden sollen, sind diese Dienste besonders geeignet:

  1. mail-archiver
  2. paperless-ngx
  3. gitea
  4. vaultwarden

Sie liefern hohen Erkenntnisgewinn ohne den kompletten Homelab-Neuaufbau zu brauchen.

Reference in New Issue View Git Blame Copy Permalink