Document complete recovery requirements and reference state

This commit is contained in:
Mikei386
2026-08-20 13:05:27 +02:00
parent 0e4a9de5ba
commit bdd6c08643
4 changed files with 461 additions and 0 deletions
+3
View File
@@ -46,6 +46,9 @@ llama.cpp :8080 + profilabhängige MCP-Server
- [Architektur](docs/ARCHITECTURE.md) - [Architektur](docs/ARCHITECTURE.md)
- [Komponentenverzeichnis](docs/COMPONENTS.md) - [Komponentenverzeichnis](docs/COMPONENTS.md)
- [Aktueller produktiver Referenzstand](docs/CURRENT_REFERENCE.md)
- [Noch benötigte Wiederherstellungsartefakte](docs/RECOVERY_REQUIREMENTS.md)
- [Disaster Recovery und Abnahme](docs/DISASTER_RECOVERY.md)
- [Saubere Installation](docs/INSTALLATION.md) - [Saubere Installation](docs/INSTALLATION.md)
- [Betrieb und Profilwechsel](docs/OPERATIONS.md) - [Betrieb und Profilwechsel](docs/OPERATIONS.md)
- [Sicherheitsmodell](docs/SECURITY.md) - [Sicherheitsmodell](docs/SECURITY.md)
+163
View File
@@ -0,0 +1,163 @@
# Aktueller produktiver Referenzstand
Stand: 20. August 2026. Dieses Dokument beschreibt die funktionierende
Referenz vor dem geplanten Neuaufbau. Es ist keine Empfehlung, jede Altlast des
Hosts zu übernehmen.
## Hardware und Betriebssystem
| Bereich | Referenz |
|---|---|
| Betriebssystem | Debian 13 `trixie` |
| Kernel | 6.12.101+deb13-amd64 |
| CPU | AMD Ryzen 5 5600, 6 Kerne/12 Threads |
| RAM | 48 GiB DDR4-2666 |
| GPU | NVIDIA GeForce RTX 5080, 16 GiB VRAM |
| NVIDIA-Treiber | 610.57.04 |
| System-SSD | Samsung 980 PRO 1 TB |
| Daten-SSD | Samsung 980 PRO 2 TB |
Die früher verwendete Radeon RX 470 ist ausgebaut und gehört nicht zur
Zielplattform.
## Produktiver Text-Stack
| Eigenschaft | Aktueller Wert |
|---|---|
| Runtime | llama.cpp |
| Repository | `https://github.com/ggml-org/llama.cpp.git` |
| Commit | `4df29be4f4c3673f428170fda944a5b19f743bb8` |
| Compiler | GCC 14.2 |
| Hauptdienst | `mike-ai-llama-ui.service` |
| llama.cpp-Port | 8080, auf dem alten Host noch im LAN gebunden |
| Client-Port | 8081 über den Router |
| MCP-Konfiguration | `/etc/mike-ai/mcp-servers.json` |
### Aktives Fast-Profil
- Qwen3.8-27B IQ4-MIX
- Kontext 73.728
- vollständig auf CUDA0
- Flash Attention
- KV-Cache Q4_0 für K und V
- MTP Draft, maximal zwei Tokens
- sechs Threads und sechs Batch-Threads
- Batch 64, Micro-Batch 32
- ein paralleler Slot
- Jinja und automatisches Reasoning
- Temperatur 0,2, Top-p 0,8, Top-k 20
### Profile
| Profil | Virtuelles Modell | Kontext | Besonderheit |
|---|---|---:|---|
| Fast | `qwen-fast` | 73.728 | IQ4-MIX, MTP2, vollständig GPU |
| Medium | `qwen-medium` | 94.208 | IQ4_XS Pure, ohne MTP |
| Long | `qwen-long` | 131.072 | IQ4-MIX, MTP2, FFN-Blöcke 0–11 auf CPU |
## Router
- Dienst: `mike-ai-profile-router.service`
- Port: 8081
- Upstream: `127.0.0.1:8080`
- Commit des Plattform-Repositories: siehe jeweils aktuelles `main`
- Umschaltskript: `/usr/local/bin/llama-profile`
- Timeout für Profilwechsel und Requests: 600 Sekunden
Der Router übernimmt:
- OpenAI-kompatibles Chat-Proxying und Streaming
- virtuelle Modelle und automatische Profilumschaltung
- Tool Calls
- Vision-Hotswap mit Cache für Folgefragen
- FLUX-Hotswap zur Bildgenerierung
- Whisper Speech-to-Text
- XTTS Text-to-Speech
- Zustands- und Modellendpunkte
## Vision
| Bereich | Referenz |
|---|---|
| Text-/Visionmodell | Qwen3.8-27B Q3_K_M |
| Projektor | BF16-mmproj |
| Kontext | 32.768 |
| temporärer Port | 8086 |
| maximale Ausgabe | 4.096 Tokens |
Vision wird nicht dauerhaft parallel geladen. Der Router entlädt das
Textprofil, analysiert das Bild und stellt danach das ursprüngliche Profil
wieder her.
## Bildgenerierung
- Modell: FLUX.2 klein Base 4B
- Runtime: PyTorch/Diffusers
- CPU-Offload aktiviert
- Standard: 30 Schritte
- High: 50 Schritte
- Worker wird nach jedem Job vollständig beendet
- Qwen wird anschließend mit dem vorherigen Profil wiederhergestellt
## Sprache
### Whisper
- Modell: large-v3-turbo
- lokale Standardsprache: Deutsch
- CPU-Ausführung
- acht Threads im produktiven Worker
- Port 8084, nur localhost
- ffmpeg für Eingabeumwandlung
### XTTS
- Modell: Coqui XTTS-v2
- CPU-only
- Stimme: `claribel`
- Deutsch und Englisch
- Port 8085, auf dem alten Host noch im LAN gebunden
- eigenes Python-3.11-Venv
## Websuche
- Docker Compose
- SearXNG, per Digest gepinnt
- TinySearch 0.5.1, per Digest gepinnt
- TinySearch nur auf `127.0.0.1:8000`
- lokale ONNX-Embeddings
- kompakte Web-MCP-Fassade mit vier Werkzeugen
- strukturierte API-Pfade für GitHub und Hugging Face
## MCP-Referenz
Aktuell existieren funktionale Adapter für:
- Websuche
- Home Assistant
- Sonarr/Radarr
- Unraid read-only
- eigener Unraid-Administrationsserver
Der frühere allgemeine Shell-MCP und doppelte, schreibende Werkzeuge gehören
nicht zum Sicherheitsziel und werden nicht ungeprüft wiederhergestellt.
## Bekannte Probleme des alten Hosts
- Systempartition vollständig gefüllt
- Datenpartition nahezu vollständig gefüllt
- etwa 1,27 TB Modelle, darunter Duplikate
- mehrere alte llama.cpp-Builds
- RX-Dienste trotz ausgebauter Karte
- aktivierte Benchmark-/Race-Dienste
- alte systemd-Overrides und Sicherungskopien
- unvollständiger großer Modelldownload
- zu viele MCP-Werkzeuge gleichzeitig im Kontext
Diese Punkte erklären den Neuaufbau, sind aber keine Bestandteile der neuen
Plattform.
Zusätzliche bekannte Sicherheitsabweichung: llama.cpp auf Port 8080 und XTTS
auf Port 8085 sind im alten Zustand breiter gebunden als im Zielsystem. Beim
Neuaufbau werden beide auf localhost begrenzt; Clients verwenden ausschließlich
den Router auf Port 8081.
+107
View File
@@ -0,0 +1,107 @@
# Disaster Recovery und Abnahme
## Definition „vollständig wiederhergestellt“
Eine Installation gilt erst dann als wiederhergestellt, wenn nicht nur Prozesse
laufen, sondern alle fachlichen Funktionen geprüft wurden.
## Phase A – Basissystem
- [ ] Betriebssystem und Kernel dokumentierter Stand
- [ ] Uhrzeit, Zeitzone und NTP korrekt
- [ ] Netzwerk nach Neustart automatisch verfügbar
- [ ] NVIDIA-Treiber geladen
- [ ] RTX und kompletter VRAM sichtbar
- [ ] System- und Modelllaufwerk korrekt gemountet
- [ ] mindestens 15 Prozent frei auf dem Systemlaufwerk
- [ ] Docker und Compose funktionieren
- [ ] keine RX- oder Benchmark-Altlast aktiviert
## Phase B – Textmodell
- [ ] llama.cpp entspricht dem festgelegten Commit
- [ ] Modelldateien stimmen mit SHA256 überein
- [ ] Fast startet mit 73.728 Kontext
- [ ] Medium startet mit 94.208 Kontext
- [ ] Long startet mit 131.072 Kontext
- [ ] GPU-/CPU-Verteilung entspricht den Profilen
- [ ] Fast erreicht den festgelegten Geschwindigkeitstoleranzbereich
- [ ] MTP funktioniert und verursacht keine Qualitätsregression
- [ ] Rolling-/Kontextverhalten ist bewusst definiert und getestet
## Phase C – Router
- [ ] `/status` meldet den richtigen Upstream
- [ ] `/v1/models` liefert drei virtuelle Modelle
- [ ] `/fast`, `/medium` und `/long` wechseln zuverlässig
- [ ] automatischer Wechsel über virtuellen Modellnamen funktioniert
- [ ] paralleler Wechsel wird sauber gesperrt
- [ ] Streaming funktioniert
- [ ] Tool Calls funktionieren
- [ ] Fehler sind OpenAI-kompatibel
- [ ] ein abgebrochener Client hinterlässt keinen blockierten Job
## Phase D – Web und MCP
- [ ] SearXNG und TinySearch gesund
- [ ] Websuche liefert kompakte, quellengebundene Ergebnisse
- [ ] GitHub- und Hugging-Face-Routing geprüft
- [ ] Home Assistant read-only Diagnose geprüft
- [ ] ARR read-only Suche geprüft
- [ ] Unraid read-only Diagnose geprüft
- [ ] schreibende Werkzeuge standardmäßig nicht geladen
- [ ] Tool-Schemas bleiben innerhalb des festgelegten Kontextbudgets
- [ ] kein Secret erscheint in Toolantworten oder Logs
## Phase E – Vision, Bild und Sprache
- [ ] neues Bild löst genau einen Vision-Hotswap aus
- [ ] Folgefrage verwendet Cache und keinen zweiten Hotswap
- [ ] Bilddaten werden vor dem Textmodell sanitisiert
- [ ] Qwen-Profil wird nach Vision wiederhergestellt
- [ ] FLUX erzeugt Standard- und High-Bild
- [ ] Qwen-Profil wird nach FLUX wiederhergestellt
- [ ] Whisper transkribiert deutsche und englische Testdatei
- [ ] XTTS erzeugt deutsche WAV- und MP3-Ausgabe
- [ ] STT/TTS blockieren das Textmodell nicht unzulässig
## Phase F – Sicherheitsprüfung
- [ ] Port 8080 von normalen Clients nicht erreichbar
- [ ] Hilfsports nur localhost
- [ ] Router nur aus erlaubtem Netz erreichbar
- [ ] Dienste laufen mit minimalen Rechten
- [ ] Environment-Dateien Modus 0600
- [ ] kein allgemeiner Shell-MCP im Standardprofil
- [ ] Schreibaktionen verlangen Vorschau und Approval Ticket
- [ ] Secret-Restore wurde ohne Klartextausgabe durchgeführt
## Phase G – Fachlicher Benchmark
Der gespeicherte Standardbenchmark wird mindestens mit Fast und Long ausgeführt:
- Home-Assistant-Automatisierung analysieren
- Logs lesen und Fehlerursache begründen
- sichere Korrektur vorschlagen
- Webrecherche mit Quellen durchführen
- Docker-/Unraid-Diagnose simulieren
- Tool-Limits, Halluzinationen und unnötige Aufrufe bewerten
Die neue Installation muss innerhalb einer vorher festgelegten Toleranz zur
Referenz liegen. Nur „Dienst läuft“ genügt nicht.
## Recovery-Protokoll
Für jeden Wiederaufbau werden festgehalten:
- Datum
- verwendeter Repository-Commit
- Modellmanifest-Version
- Hardware
- Dauer je Phase
- Abweichungen
- Testergebnis
- verantwortliche Freigabe
Erst nach Abschluss aller Pflichtpunkte darf der alte Host gelöscht oder als
Fallback außer Betrieb genommen werden.
+188
View File
@@ -0,0 +1,188 @@
# 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/Long IQ4-MIX
- Qwen Medium IQ4_XS Pure
- Qwen Q3 Vision
- BF16 Vision-Projektor
- Whisper large-v3-turbo
- FLUX.2 klein
- XTTS-v2 und verwendete Stimme
## 2. Externe Komponenten und Commits – offen
Für jedes separate Projekt benötigen wir Repository und Commit:
- Home-Assistant-MCP
- ARR-MCP
- Unraid read-only MCP
- gegebenenfalls eigener Unraid-Administrations-MCP
- LLama-GUI, falls sie erhalten bleibt
Jede 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 – offen
Ein idempotentes Bootstrap-Skript muss noch erstellen:
- Paketquellen und benötigte Debian-Pakete
- NVIDIA-Treiber und exakte Version
- CUDA Toolkit und Buildabhängigkeiten
- Docker und Compose
- Python 3.13 und Python 3.11/uv
- Dienstbenutzer und Gruppen
- 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
- optionale GitHub-, Hugging-Face- und Brave-Schlüssel
- SSH-Hostschlüssel und bekannte Hosts
Noch festzulegen:
- 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 – 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 | localhost |
| 8081 | vertrauenswürdiges LAN/VPN |
| 8084 | localhost |
| 8085 | localhost |
| 8000 | localhost |
| 5240 | optional nur Administration |
## 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 XTTS
- TinySearch-/SearXNG-Image-Digests
Noch offen:
- vollständiges `pip freeze` je produktivem Venv
- CUDA-kompatible Wheel-Quelle
- FLUX-Revision
- XTTS-Modellrevision
- 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 – offen
Der gewünschte Endzustand ist:
```text
bootstrap-host
install-runtime
verify-model-manifest
install-platform
restore-secrets
enable-selected-mcp-profiles
run-acceptance-tests
```
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.