Simplify Athena stack and recovery

2026-08-25 22:27:26 +02:00
parent c4851305d1
commit 069da8b4f0
70 changed files with 887 additions and 5806 deletions
@@ -1,160 +1,71 @@
-# Lokale KI-Plattform
+# Athena AI

-Reproduzierbarer Docker-Stack für einen privaten Qwen-/llama.cpp-Host mit
-Open WebUI, Profilumschaltung, integrierter Vision, lokaler Websuche und
-WireGuard-Isolation.
+Ein reproduzierbarer Docker-Stack für Athenas lokale KI. Ein Compose-Projekt
+enthält Router, llama.cpp-Profile, OpenWebUI, Hermes, Sprache, Bildgenerierung,
+fachliche MCP-Container und das regelmäßige Datenbackup.

-## Zielbild
+## Aufbau

- Debian 13 als schlanker GPU-Host
- llama.cpp selbst gebaut und auf einen geprüften Commit festgelegt
- fünf schaltbare Profilcontainer plus ein isolierter Experimentalcontainer;
-  davon ist immer exakt ein Inferenzcontainer aktiv
- `/fast`, `/medium`, `/large`, `/ultra` und `/uncensored` über den Profile Router
- verbindliche Standardmatrix: Fast MIX 76,8K, Medium Pure 160K (Default),
-  Large Pure 192K, Ultra Pure 256K sowie Abliterated Q4_K_M 80K als
-  bewusst nicht standardmäßiges Uncensored-Spezialprofil
- `/ultra`: getestetes text-only 256K-Profil (IQ4_XS Pure, beide GPUs,
-  80:20); etwa 68 Token/s und erfolgreicher 220K-Prompt-Fülltest
- Open WebUI als einfache Chat-Oberfläche und Hermes Agent als zweite,
-  agentische Oberfläche für lange, werkzeugintensive Aufgaben
- native OpenWebUI-Websuche für allgemeine Recherche; SearXNG/Web-MCP als
-  manueller Spezialadapter ohne externen API-Schlüssel
- zentrale MCP-Werkzeugebene: getrennte Container für Athena-Plattformwissen,
-  den kontrollierten Athena Operator, Web, GitHub, HA, ARR, Unraid, Navidrome
-  und Sandbox, gemeinsam nutzbar durch Open WebUI und andere
-  Clients
- KI-Dienste ausschließlich über den containerisierten WireGuard-Gateway erreichbar
- KI-Ausgangsverkehr über das Heimnetz, bei Tunnelausfall fail-closed
- keine Secrets, Chats, Logs oder Modelldateien im Repository
+- `compose.yaml` ist der einzige Einstieg; `platform/mcp/compose.yaml` wird mit
+  Docker Composes standardisiertem `include` in dasselbe Projekt geladen.
+- Genau ein llama.cpp-Profil ist aktiv. Der Router schaltet zwischen Fast,
+  Medium, Large, Ultra und Uncensored.
+- Der **Athena Operator** ist der einzige administrative MCP. Er liefert mit
+  `athena_operator_inspect(subject=guide)` auch diese Plattformanleitung aus
+  `ATHENA.md`.
+- Home Assistant, ARR, Unraid, Navidrome, Deemix, GitHub und Web bleiben als
+  getrennte Fach-MCPs isolierbar und unabhängig aktualisierbar.
+- `config/mcp-registry.json` ist die einzige Liste der MCPs für Hermes und
+  OpenWebUI. `platform/mcp/sync-clients.py` erzeugt beide Registrierungen.
+- Modelle, Hermes-Daten und Backups liegen auf `/data`; Secrets ausschließlich
+  unter `/etc/mike-ai`.
+- KI-Oberflächen und APIs sind nur über WireGuard erreichbar.

-Die gemessenen Startparameter und Zuständigkeiten stehen in
-[`docs/STANDARD_PROFILE_MATRIX.md`](docs/STANDARD_PROFILE_MATRIX.md).
+## Installation – ein Befehl

-## Schnellstart
-
-Auf einem frisch installierten Debian 12/13 amd64:
+Nach dem Ausfüllen von `config/install.env`:

 ```bash
-cp config/install.env.example config/install.env
-chmod 600 config/install.env
-editor config/install.env
 sudo ./install.sh --config config/install.env
 ```

-Installiert werden Docker CE, NVIDIA Container Toolkit, WireGuard-Werkzeuge, der
-gepinnt gebaute llama.cpp-Server, die Modelle und der komplette Compose-Stack.
-Bei einer erstmaligen NVIDIA-Treiberinstallation fordert das Skript einen
-Neustart an; danach wird derselbe Befehl erneut ausgeführt.
+Das Skript installiert Docker und NVIDIA-Unterstützung, lädt die konfigurierten
+Modelle, baut den Stack und startet die benötigten Profile und MCPs.

-## Dienste
+## Bedienung

-| Dienst | Erreichbarkeit | Zweck |
-|---|---|---|
-| Open WebUI | `<WG-IP>:8080` | Chat und Administration |
-| Hermes Dashboard | `<WG-IP>:9119` | agentischer Chat, Sitzungen, Skills und MCP-Verwaltung |
-| Hermes API | `<WG-IP>:8642` | authentifizierte Agent-API |
-| Profile Router | `<WG-IP>:8081` | OpenAI-kompatible API, Profilwahl |
-| llama.cpp | nur Docker-intern | Inferenz und integrierte Vision |
-| Profile Controller | nur Docker-intern | eng begrenzter Profil-/FLUX-Hot-Swap |
-| FLUX Worker | nur Docker-intern, normalerweise gestoppt | Bildgenerierung auf RTX 5080 |
-| XTTS-v2 | `<WG-IP>:8092`, RTX 3060 | primäre mehrsprachige Sprachausgabe |
-| TTS Gateway | `<WG-IP>:8085` | Annmarie Nele, Queue und Piper-Fallback |
-| Piper | `<WG-IP>:8091`, CPU | ausfallsichere deutsche Ersatzstimme |
-| MCP-Tool-Stack | `<WG-IP>:8201-8208` | Athena-Kontext, Athena Operator, Web, GitHub, Home Assistant, ARR, Unraid und Navidrome |
+```bash
+# Gesamten Stack anzeigen
+docker compose --env-file /etc/mike-ai/stack.env ps

-XTTS-v2, TTS-Gateway, Piper-Fallback und der FLUX.2-Klein-Hot-Swap sind
-reproduzierbare Kerndienste; STT
-bleibt optional. Web-, Home-Assistant-,
-GitHub-, ARR-, Unraid- und Navidrome-Werkzeuge besitzen dagegen bereits getrennte Container unter
-`platform/mcp/`. Open WebUI erreicht sie über das interne `mike-ai-tools`-Netz;
-Pi, Hermes und andere Clients verwenden die direkten WireGuard-Ports aus
-`docs/VPN_SERVICE_PORTS.md`. llama.cpp erhält keine MCP-Konfiguration und keine
-Infrastruktur-Secrets. Die Bildanalyse ist Bestandteil des multimodalen
-Qwen-Modells.
+# Eine gezielte Änderung ausrollen
+docker compose --env-file /etc/mike-ai/stack.env up -d --build mcp-arr

-Hermes läuft als eigener, per OCI-Digest gepinnter Container direkt neben
-OpenWebUI. Beide sprechen dieselbe Router-API und damit dieselben Qwen-Profile;
-Hermes ist kein zusätzlicher Modellserver. Seine Sitzungen, Skills,
-Konfiguration und isolierte Arbeitsfläche liegen unter `/data/hermes`.
+# Sofortiges Datenbackup zusätzlich zum Fünf-Stunden-Zeitplan
+docker exec mike-ai-backup backup
+```

-Open WebUI erhält über die vorgesehenen statischen Anpassungspunkte ein globales
-Dark-Theme namens **Midnight Aurora**. CSS und Start-Loader liegen unter
-`platform/openwebui/theme/` und werden schreibgeschützt in den Container
-eingebunden. Der Hintergrund bewegt sich bewusst langsam; Browser mit aktivierter
-Option „Bewegung reduzieren“ erhalten automatisch eine unbewegte Variante.
-Kurze Werkzeugbestätigungen werden ebenfalls lokal aus statischen Clips
-abgespielt. Sie laufen nur bei aktivierter automatischer Sprachausgabe, kosten
-keine Modell-Tokens und verraten dem Modell keine zusätzlichen Daten.
+OpenWebUI: `http://<WireGuard-IP>:8080`
+
+Router-API: `http://<WireGuard-IP>:8081/v1`
+
+Hermes: `http://<WireGuard-IP>:9119`
+
+## Wiederherstellung – ein Befehl
+
+Nach einer frischen Installation und eingehängtem `/data`:
+
+```bash
+sudo ./restore.sh /data/docker-backups/athena-latest.tar.gz
+```
+
+Details, Prüfschritte und der exakte Sicherungsumfang stehen in
+[`docs/RECOVERY.md`](docs/RECOVERY.md).

 ## Dokumentation

-Beginne mit [`ATHENA.md`](ATHENA.md). Sie ist die kurze, verbindliche Betriebs-
-und Operator-Anleitung. Die umfangreichen Dateien unter `docs/` sind nur
-gezielte Detail- und Historienreferenzen.
+- [`ATHENA.md`](ATHENA.md) – kurze Maschinen- und Operatoranleitung
+- [`docs/STANDARD_PROFILE_MATRIX.md`](docs/STANDARD_PROFILE_MATRIX.md) – Profile und Messwerte
+- [`docs/RECOVERY.md`](docs/RECOVERY.md) – Backup und Neuaufbau

-### API-Schnellreferenz
-
-Für Zettelrobbe und andere OpenAI-kompatible Clients gilt im Heimnetz:
-
-```text
-Base URL: http://192.168.1.212:8081/v1
-API-Key:  Inhalt von /etc/mike-ai/router-api-key auf Athena
-```
-
-Den Schlüssel auf Athena ausschließlich lokal mit
-`sudo cat /etc/mike-ai/router-api-key` anzeigen und direkt in den Secret-Store
-des Clients kopieren. Er gehört niemals in Git, eine URL oder einen Chat. Die
-entsprechende Open-WebUI-Adresse auf Port `8080` ist keine API-Basisadresse.
-
- [`ATHENA.md`](ATHENA.md) – verbindlicher Einstieg für Menschen und Agenten
- [`docs/PLATFORM_OVERVIEW.md`](docs/PLATFORM_OVERVIEW.md) – technische Detailübersicht
- [`docs/QWEN_OPERATOR_CONTEXT.md`](docs/QWEN_OPERATOR_CONTEXT.md) – historische Langreferenz, nicht als Startkontext verwenden
- [`docs/PLATFORM_CONTEXT_MCP.md`](docs/PLATFORM_CONTEXT_MCP.md) – kompakte read-only Plattformaussicht
- [`docs/GITHUB_MCP.md`](docs/GITHUB_MCP.md) – sicherer GitHub-Nur-Lesen-Betrieb und bewusst aktivierbarer Wartungsmodus
- [`docs/TOOLING_RELIABILITY_2026-08-24.md`](docs/TOOLING_RELIABILITY_2026-08-24.md) – Werkzeugumbau, Abnahme und Rollback
- [`config/operator-system-prompt.txt`](config/operator-system-prompt.txt) – knapper System-Prompt für ein getrenntes Operator-Profil
-
- [Roadmap für den neuen Host](docs/NEW_HOST_ROADMAP.md)
- [Zielarchitektur und Sicherheitsgrenzen](docs/ARCHITECTURE.md)
- [Installation und Abnahme](docs/INSTALLATION.md)
- [WireGuard-Heimseite](docs/WIREGUARD_HOME_PEER.md)
- [Checkliste für den unbeaufsichtigten Standort](docs/REMOTE_SITE_CHECKLIST.md)
- [Temporärer Notfallzugriff über SSH](docs/EMERGENCY_UNI_ACCESS.md)
- [Betrieb und Profilwechsel](docs/OPERATIONS.md)
- [Sicherheitsmodell](docs/SECURITY.md)
- [Disaster Recovery](docs/DISASTER_RECOVERY.md)
- [Vollständige Bare-Metal-Wiederherstellung](docs/BARE_METAL_RECOVERY.md)
- [Protokoll des Athena-Leerhostaufbaus](docs/ATHENA_REBUILD_LOG.md)
- [Komponenten](docs/COMPONENTS.md)
-
-## Wichtige Dateien
-
-```text
-install.sh                              kompletter Bootstrap
-config/install.env.example              öffentliche Konfigurationsvorlage
-compose.yaml                            produktiver Stack
-platform/docker/llama-cpp/Dockerfile    CUDA-llama.cpp-Build
-platform/docker/profile-controller/     sichere Profilsteuerung
-platform/hermes/                         Hermes-Konfiguration und Installer
-router/                                 OpenAI-kompatibler Profile Router
-```
-
-## Sicherheitsregeln
-
- `config/install.env` ist lokal, Modus 0600, und wird ignoriert.
- API-, Controller-, WebUI- und WireGuard-Schlüssel entstehen erst am Host.
- Nur der kleine Profile Controller sieht den Docker-Socket.
- llama.cpp veröffentlicht weder Port noch WebUI.
- Quellrouting ohne alternative Route verhindert Traffic-Leaks bei
-  WireGuard-Ausfall (fail-closed).
- Das Uni-Netz und das Heimnetz dürfen diesen Host nicht als Transit benutzen.
-
-Die Profilwerte wurden auf RTX 5080 und RTX 3060 vermessen und bilden die
-verbindliche Standardmatrix. Neue Varianten ersetzen sie erst nach demselben
-Vergleichstest und einer dokumentierten Entscheidung.
-
-Der integrierte Vision-Projektor der Profile Fast, Medium, Large und Uncensored läuft
-gezielt auf der RTX 3060. Das hält den knappen VRAM der RTX 5080 für Modell und
-Kontext frei und beschleunigte den dokumentierten synthetischen Vision-Test
-gegenüber CPU-Vision um etwa den Faktor 8,5 bei der Gesamtzeit.
+Git enthält keine Secrets, Chatdaten oder Modellgewichte.