Add encrypted bare-metal recovery workflow

2026-08-23 15:48:41 +02:00
parent e5dffbc2ba
commit 3d528f2716
9 changed files with 416 additions and 7 deletions
@@ -0,0 +1,121 @@
+# Vollständige Bare-Metal-Wiederherstellung
+
+Dieses Dokument ist die verbindliche Anleitung für den Verlust der Athena-
+System-SSD. Wissen aus früheren Chats ist weder Voraussetzung noch gültige
+Dokumentation.
+
+## Was woher wiederkommt
+
+| Bestandteil | Quelle beim Recovery |
+|---|---|
+| Plattform, Router, Profile, MCP-Builds und Patches | dieses Git-Repository, exakter Commit |
+| Qwen-, Projektor- und Bildmodelle | dokumentierte URLs und SHA256 in `config/install.env.example` beziehungsweise der gesicherten Installationskonfiguration |
+| Navidrome-MCP 2.2.0 samt llama.cpp-Schemafix | `platform/mcp/Dockerfile.navidrome` |
+| OpenWebUI-Benutzer, Chats, Arbeitsbereichsmodelle, Filter und Verbindungen | verschlüsseltes Recovery-Bundle |
+| Router-, WireGuard-, HA-, ARR-, Unraid- und Navidrome-Zugangsdaten | verschlüsseltes Recovery-Bundle |
+| Last.fm API-Key | `/etc/mike-ai/navidrome-mcp.env` im verschlüsselten Bundle |
+| Navidrome-Bibliothek und Benutzer | bleiben auf dem separaten Unraid-Server |
+
+Das Last.fm Shared Secret wird nicht verwendet und daher nicht gesichert.
+Modelldateien müssen nicht im Bundle liegen: Der Installer lädt sie erneut und
+verifiziert jede Datei kryptografisch. Ein vorhandenes intaktes `/data` kann
+den Download lediglich beschleunigen.
+
+## Einmalige Vorbereitung
+
+Die geheime age-Identität muss **außerhalb Athenas** liegen, beispielsweise
+auf dem Mac und zusätzlich in einem Passwortmanager oder Offline-Datenträger:
+
+```bash
+age-keygen -o athena-recovery.agekey
+age-keygen -y athena-recovery.agekey > athena-recovery.recipient
+```
+
+Nur die öffentliche Zeile aus `athena-recovery.recipient` wird auf Athena als
+`/etc/mike-ai/recovery.age-recipient` mit Modus `0600` abgelegt. Die Datei
+`athena-recovery.agekey` darf niemals auf Athena oder im Git liegen.
+
+## Sicherung erzeugen
+
+Das Ziel muss nach einem SSD-Verlust noch existieren. Bevorzugt wird ein
+gemountetes, ausschließlich für Backups beschreibbares Verzeichnis auf Unraid;
+`/data` allein schützt nur vor dem Verlust der System-SSD, nicht vor Verlust
+des gesamten Rechners.
+
+```bash
+sudo /opt/mike-ai/stack/platform/recovery/create-recovery-bundle.sh \
+  /PFAD/AUF/UNRAID/athena-recovery-$(date +%F).tar.age
+```
+
+Das Skript nimmt ausschließlich auf:
+
+- `/etc/mike-ai` einschließlich aller Fach-MCP-Secrets,
+- `/root/mike-ai-install.env`,
+- das lokale `runraid`-Binary, falls vorhanden,
+- das vollständige OpenWebUI-Datenvolume,
+- Prüfsummen und den eingesetzten Git-Commit.
+
+Der Klartext liegt nur in einem kurzlebigen root-only Verzeichnis unter
+`/tmp` und wird beim Ende entfernt. Das Ergebnis ist vollständig mit age
+verschlüsselt. Ohne erfolgreiche Ausgabe `RECOVERY_BUNDLE_OK` gilt die
+Sicherung als fehlgeschlagen. Für ein konsistentes SQLite-Abbild stoppt das
+Skript OpenWebUI kurz und startet es anschließend auch bei einem Fehler über
+eine Aufräumroutine wieder. Laufende LLM-Profile und MCP-Dienste bleiben dabei
+unangetastet.
+
+## Wiederherstellung nach SSD-Verlust
+
+1. Debian 12 oder 13 installieren, Netzwerk herstellen und den administrativen
+   Benutzer aus der Installationskonfiguration anlegen.
+2. Root-SSH-Zugriff mit dem vorhandenen Schlüssel herstellen.
+3. Dieses Repository klonen und exakt den in `METADATA` des Bundles genannten
+   Commit auschecken. Normalerweise ist das der Commit, mit dem die Sicherung
+   erzeugt wurde.
+4. Recovery-Bundle und `athena-recovery.agekey` temporär auf den Host kopieren.
+5. Einen Befehl ausführen:
+
+```bash
+sudo ./platform/recovery/restore-recovery-bundle.sh \
+  /root/athena-recovery-YYYY-MM-DD.tar.age \
+  /root/athena-recovery.agekey
+```
+
+Der Wiederhersteller:
+
+1. installiert nur die zum Entschlüsseln benötigten Basispakete,
+2. prüft Verschlüsselung, Archivstruktur, SHA256 und Git-Commit,
+3. stellt Installationskonfiguration und Secrets ohne Ausgabe ihrer Werte her,
+4. führt den idempotenten Hostinstaller aus,
+5. signalisiert einen notwendigen NVIDIA-/Netzwerk-Reboot mit Status 20/21;
+   danach wird derselbe Befehl erneut ausgeführt,
+6. sichert den vorhandenen OpenWebUI-Stand als Rückfallarchiv und stellt dann
+   das geprüfte OpenWebUI-Datenvolume wieder her,
+7. installiert die versionierten Modelleinstellungen, Filter und MCP-
+   Verbindungen erneut,
+8. startet alle durch vorhandene Secret-Dateien freigegebenen Toolprofile,
+9. prüft Navidrome, sämtliche Werkzeug-Schemas, Last.fm und den OpenWebUI-
+   Verbindungseintrag ohne Musik- oder Zugangsdaten auszugeben.
+
+Erst die Ausgabe `BARE_METAL_RECOVERY_OK` bedeutet Erfolg.
+
+## Navidrome-Abnahmekriterium
+
+Bei vorhandenem `LASTFM_API_KEY` müssen 45 Werkzeuge erscheinen, andernfalls
+38. Playback-Werkzeuge dürfen auf Athena nicht auftauchen. Sämtliche Regex-
+Patterns müssen für llama.cpp vollständig mit `^…$` verankert sein. Eine
+öffentliche Last.fm-Trendabfrage muss funktionieren; Bibliothek, Playlists und
+Hörverlauf werden während der Abnahme nicht gelesen.
+
+Die Prüfung kann jederzeit wiederholt werden:
+
+```bash
+sudo /opt/mike-ai/stack/platform/mcp/verify-navidrome.sh
+```
+
+## Regelmäßige Kontrolle
+
+Mindestens nach jeder Änderung an OpenWebUI, WireGuard oder einem MCP-Secret
+wird ein neues Bundle erzeugt und **außerhalb Athenas** aufbewahrt. Quartalsweise
+wird ein Restore in einer isolierten Testinstallation durchgeführt. Eine
+Sicherung ohne getestete Entschlüsselung und Abnahmemarker ist nur eine
+Hoffnung, kein Backup.