AI-Profile-Router/docs/RECOVERY_REQUIREMENTS.md

Noch benötigte Wiederherstellungsartefakte

Diese Liste definiert, was vor einer Löschung oder grundlegenden Änderung des alten Hosts noch gesichert beziehungsweise präzisiert werden muss.

Statuswerte:

• gesichert: vollständig im Git oder anderweitig reproduzierbar
• offen: muss vor dem Neuaufbau erledigt werden
• lokal geheim: darf nicht unverschlüsselt ins Git

1. Modelle und Prüfsummen – offen, höchste Priorität

Für jedes tatsächlich benötigte Modell werden erfasst:

• exakte Downloadquelle und Repository-ID
• Revision oder Commit
• Dateiname und Splitreihenfolge
• Dateigröße
• SHA256 jeder Datei
• Lizenz
• Zielpfad
• zugehöriger mmproj/MTP-Tensor
• getestete Runtime und Profilzuordnung

Das Ergebnis wird als platform/models/manifest.local.yaml erzeugt. Die Datei enthält keine Geheimnisse, kann aber wegen möglicher privater Quellen zunächst lokal bleiben. Eine bereinigte Fassung gehört anschließend ins Git.

Pflichtrollen:

• Qwen Fast IQ4-MIX
• Qwen Medium/Large/Ultra IQ4_XS Pure
• Qwen Uncensored Abliterated Q4_K_M samt passendem F16-Projektor
• BF16 Vision-Projektor
• Whisper large-v3-turbo
• FLUX.2 klein
• XTTS-v2, per Digest gepinntes CUDA-12.1-Image und CPML-Akzeptanz
• XTTS-Stimme Annmarie Nele, RTX-3060-UUID und persistenter Modellcache
• internes TTS-Gateway mit Queue, Sprachsegmentierung und Piper-Fallback
• Piper piper-tts 1.6.0 und Stimme de_DE-thorsten-high als CPU-Fallback

2. Externe Komponenten und Commits – teilweise gesichert

Im Repository gesichert sind inzwischen:

• getrennte MCP-Container und internes Netz
• Web-MCP-Fassade sowie gepinnte TinySearch-/SearXNG-Images
• ARR-MCP 1.0.1 und der aktuell eingesetzte kompakte Sonarr-Patch
• Home-Assistant-Relay ohne eingebettetes Token
• Startlogik und Health-Checks

Noch extern zu beschaffen und exakt festzuhalten sind:

• Home-Assistant-MCP
• runraid 0.4.2 für den read-only Unraid-MCP
• gegebenenfalls eigener Unraid-Administrations-MCP
• LLama-GUI, falls sie erhalten bleibt

Jede noch externe Komponente bekommt zusätzlich:

• Installationsbefehl
• Systembenutzer
• systemd-/Docker-Datei
• Health-Check
• benötigte Environment-Namen ohne Werte
• Liste read-only und schreibender Werkzeuge

3. Basissystem-Bootstrap – umgesetzt, Praxistest offen

install.sh erstellt inzwischen:

• Paketquellen und benötigte Debian-Pakete
• NVIDIA-Treiber und exakte Version
• CUDA Toolkit und Buildabhängigkeiten
• Docker und Compose
• die benötigten Container-Runtimes und Dienstbenutzer in Images
• Verzeichnisse, Eigentümer und Dateirechte
• Firewallregeln
• Journalgrößenlimit
• automatische Sicherheitsupdates nach bewusstem Freigabemodell

Das Skript darf weder formatieren noch Modelle löschen. Destruktive Speicheroperationen bleiben ein separater, ausdrücklich bestätigter Schritt.

4. Secret-Verfahren – lokal geheim

Benötigt wird ein festes Verfahren für:

• Home-Assistant-Token
• Sonarr-/Radarr-API-Schlüssel
• Unraid-Zugang
• Navidrome-Benutzer und Last.fm API-Key
• optionale GitHub-, Hugging-Face- und Brave-Schlüssel
• SSH-Hostschlüssel und bekannte Hosts

Umgesetzt ist ein age-verschlüsseltes Bundle über platform/recovery/create-recovery-bundle.sh und der zugehörige Bare-Metal-Restore. Noch standortspezifisch festzulegen ist ausschließlich das externe Zielverzeichnis auf Unraid.

Verbindlich bleiben:

• verschlüsseltes Backupformat, beispielsweise age oder ein Passwortmanager
• Besitzer und Rechte je Environment-Datei
• Rotation und Widerruf
• Restore ohne Ausgabe der Werte in Terminal- oder Modellkontext
• Funktionstest mit ausschließlich Statuscode, niemals Tokenanzeige

5. Netzwerk und DNS – Vorlage umgesetzt, Standortwerte offen

Dokumentiert werden müssen:

• endgültiger Hostname
• statische Adresse oder DHCP-Reservierung
• DNS-Name
• erlaubte Client-Netze
• Firewallmatrix pro Port
• TLS/Reverse Proxy, sofern verwendet
• Verhalten bei Neustart und fehlendem Netzwerk

Zielmatrix:

Port	Zugriff
22	nur Administration
8080	ausschließlich WireGuard-Gateway (Open WebUI)
8081	ausschließlich WireGuard-Gateway (Router)
8084	localhost
8085	localhost
8000	localhost
5240	optional nur Administration

Open WebUI und Router selbst besitzen keine Host-Portfreigaben. Zusätzlich zum Repository muss die verschlüsselt gesicherte Fritzbox-Clientdatei als /etc/mike-ai/wireguard/fritz-athena.conf (0600) wiederhergestellt werden.

6. Speicherlayout – offen

Vor dem Neuaufbau festlegen:

• System, Modelle, Caches und Ergebnisse auf getrennten Mounts
• Dateisystem des Modelllaufwerks
• Mindestreserve und Warnschwellen
• Docker-Datenpfad
• Hugging-Face- und Python-Cachepfade
• Backupziel
• Aufbewahrungsregeln für Bilder, Audio und Logs

Empfehlung: System unter 85 Prozent, Modelllaufwerk unter 90 Prozent halten.

7. Runtime-Locks – teilweise gesichert

Bereits gesichert:

• llama.cpp-Commit
• zentrale Python-Versionen für FLUX und Piper
• TinySearch-/SearXNG-Image-Digests

Noch offen:

• vollständiges pip freeze je produktivem Venv
• CUDA-kompatible Wheel-Quelle
• FLUX-Revision
• Piper-Paketversion und exakter Stimmenname
• Whisper-Commit und Buildoptionen
• Docker-Engine-/Compose-Version

8. Betriebsdaten und Aufbewahrung – offen

Festlegen, welche Daten persistent sein sollen:

• generierte Bilder: standardmäßig zeitlich begrenzt
• Audiodateien: standardmäßig nicht dauerhaft
• Vision-Cache: flüchtig
• Chatverläufe: nicht Bestandteil dieser Plattform
• Benchmarkresultate: eigenes Repository
• Logs: ohne Prompt- und Tool-Antwortinhalte

9. Ende-zu-Ende-Installer – weitgehend implementiert, Praxistest offen

Der Ablauf ist jetzt in install.sh zusammengeführt:

bootstrap-host
install-runtime
verify-model-manifest
install-platform
restore-secrets
enable-selected-mcp-profiles
run-acceptance-tests

platform/mcp/install-tools.sh installiert den Webbereich automatisch und aktiviert HA, ARR, Navidrome und Unraid nur bei vorhandenen Secret-/Programmdateien. platform/migration/restore-reference-backup.sh importiert eine bestehende OpenWebUI-Datenbank und ausschließlich die freigegebenen Tool-Secrets, ohne experimentelle Altcontainer zurückzubringen. Der Leerhost-Probelauf wird auf Athena praktisch protokolliert und seine Korrekturen fließen direkt in den Installer zurück.

Ein Container-Backup gilt nur dann als vollständig, wenn nach docker save nicht bloß das Archiv und seine Prüfsumme existieren: Ein isolierter Probeimport muss außerdem jede erwartete Image-ID beziehungsweise den unveränderlichen Registry-Digest und die OCI-Build-Revision bestätigen. Die OpenWebUI-Datenbank wird immer zusammen mit genau diesem geprüften Image gesichert und wiederhergestellt.

Jeder Schritt muss wiederholbar, einzeln prüfbar und bei Fehlern abbrechbar sein. Ein fehlgeschlagener Schritt darf keinen halb aktivierten Dienst hinterlassen.

10. Dokumentations-Abnahmekriterium

Der alte Host darf erst verworfen werden, wenn eine fachkundige Person mit:

1. diesem Repository,
2. den dokumentierten Modellquellen,
3. dem verschlüsselten Secret-Backup

einen leeren Host ohne Wissen aus früheren Chats vollständig in Betrieb nehmen kann.