AI-Profile-Router/docs/MIGRATION.md

Migration vom bestehenden Host

Behalten

• Qwen3.8-27B IQ4-MIX und das getestete MTP2-Profil
• IQ4_XS Pure für Medium
• Abliterated Q4_K_M und passender F16-mmproj für Uncensored
• BF16-mmproj für die integrierte Vision aller Qwen-Profile
• festgeschriebener llama.cpp-Commit
• Router, Piper-TTS, Whisper und Websuche
• spezialisierte MCPs nach Sicherheitsprofil
• relevante Benchmarkresultate

Nicht übernehmen

• RX-470-Dienste
• doppelte Whisper-Server
• automatisch aktivierte Modellrennen und Benchmarks
• unvollständige Modelldownloads
• alte llama.cpp-/BeeLlama-Testbuilds
• alte systemd-Backups
• Caches und generierte Medien
• doppelte oder klar unterlegene Modelle

Reihenfolge

1. Repositories und verschlüsselte Konfiguration sichern.
2. Modellmanifest mit Dateigrößen und SHA256 erstellen.
3. Neuen Host installieren und Speicherlayout festlegen.
4. NVIDIA-Treiber und CUDA verifizieren.
5. Festgeschriebenen llama.cpp-Commit bauen.
6. nur die benötigten Modelle übertragen und Hashes prüfen.
7. Fast-Profil ohne MCP starten und testen.
8. Medium, Large, Ultra und Uncensored einzeln testen.
9. Router installieren und Profilwechsel testen.
10. Web, HA, ARR und Unraid nacheinander hinzufügen.
11. Piper-TTS prüfen; optional STT ergänzen und den Projektor für integrierte Vision prüfen.
12. Standardbenchmark und Sicherheitsprüfung ausführen.
13. Erst danach Clients umstellen.

Referenz-Backup automatisiert einspielen

Nach einem erfolgreichen Lauf von install.sh kann eine Sicherung des alten Referenzhosts gezielt importiert werden:

sudo ./platform/migration/restore-reference-backup.sh \
  /data/ki-migration-backup-YYYYMMDD

Das Skript prüft zuerst die Archiv-Hashes und übernimmt ausschließlich:

• die persistente OpenWebUI-Datenbank samt Einstellungen und Uploads,
• das zur Datenbank passende, gesicherte OpenWebUI-Container-Image,
• den dazugehörigen WebUI- und Router-Schlüssel,
• die freigegebenen HA-, ARR- und Unraid-Secrets,
• runraid, dessen privaten Schlüssel, Zertifikat und Known-Hosts-Datei.

Es übernimmt bewusst keine alten Compose-Dateien, Routerprofile, Experimentdienste oder .before-*-Altstände. Vor dem Ersetzen des frischen OpenWebUI-Volumes wird unter /data/open-webui-before-restore-*.tar.gz eine Rückfallsicherung erstellt. Secret-Werte werden nicht ausgegeben.

OpenWebUI-Datenbanken sind nicht beliebig vor- oder rückwärtskompatibel. Das Restore-Skript lädt deshalb bewusst das im Backup inventarisierte Original- Image, versieht es lokal mit dem Tag mike-ai/openwebui:reference und trägt diesen Tag sowohl in stack.env als auch – falls vorhanden – in /root/mike-ai-install.env ein. Dadurch bleibt auch ein späterer, idempotenter Installerlauf versionsgleich. Ein Upgrade auf eine neuere OpenWebUI-Version erfolgt erst danach kontrolliert und mit einer eigenen Datenbanksicherung. Falls ein älteres Image-Archiv trotz seines Namens das OpenWebUI-Image nicht enthält, verwendet das Skript ausschließlich den im Docker-Inventar gesicherten unveränderlichen Registry-Digest. Es fällt niemals auf latest zurück. Da lokale Docker-Image-IDs beim Wiederherstellen von einem Registry-Digest abweichen können, verifiziert es zusätzlich die gesicherte OCI-Build-Revision. Nach dem Datenimport wendet es außerdem die im Repository versionierten OpenWebUI-Filter erneut an. Dadurch bleiben auch deren Prioritäten unabhängig vom Alter der Datenbanksicherung reproduzierbar.

Der alte Host bleibt bis zum bestandenen Abnahmetest unverändert und dient nur als Referenz. Es werden keine Caches oder unbekannten Altverzeichnisse kopiert.