118 lines
5.2 KiB
Markdown
118 lines
5.2 KiB
Markdown
# Athena – Betriebsanleitung
|
||
|
||
Diese Datei ist der kurze, verbindliche Einstieg für Menschen und Agenten.
|
||
Für normale Arbeiten reicht sie aus. Detaildokumente unter `docs/` werden nur
|
||
gelesen, wenn diese Datei ausdrücklich darauf verweist oder eine konkrete
|
||
Fehlersuche sie benötigt.
|
||
|
||
## Aufbau
|
||
|
||
- Host: Debian, ohne lokalen Notfallzugriff oder KVM.
|
||
- Arbeitsbaum und laufender Stack: `/opt/mike-ai/stack`.
|
||
- Persistente Daten, Modelle und Backups: `/data`.
|
||
- Lokale Konfiguration und Secrets: `/etc/mike-ai` (niemals in Git).
|
||
- Benutzerzugriff auf KI-Dienste: über WireGuard, nicht über das Uni-LAN.
|
||
- OpenAI-kompatible Modell-API: Profile Router auf Port 8081.
|
||
- Oberflächen: Hermes Agent und OpenWebUI.
|
||
- Inferenz: genau ein aktives llama.cpp-Textprofil; der Router wechselt bei
|
||
Bedarf zwischen Fast, Medium, Large, Ultra und Uncensored.
|
||
|
||
## Verzeichnisse
|
||
|
||
| Pfad | Zweck |
|
||
|---|---|
|
||
| `/opt/mike-ai/stack` | Einziger Git-Checkout und einzige Quelle für Deployments |
|
||
| `/data/models` | GGUF-Modelle, Projektoren und weitere große Modelldateien |
|
||
| `/data` | Persistente Anwendungsdaten und Docker-Backups |
|
||
| `/etc/mike-ai` | Lokale Env-Dateien, API-Schlüssel und SSH-Schlüssel |
|
||
| `/tmp` | Einmalige Hilfsprogramme und temporäre Arbeitsdateien |
|
||
|
||
Die früheren Checkouts `/data/mike-ai-operator/repository` und
|
||
`/root/AI-Profile-Router` sind keine Arbeitsquellen. Sie dürfen nach der
|
||
Migration höchstens als gekennzeichnetes Archiv existieren.
|
||
|
||
## Container-Prinzip
|
||
|
||
Ein eigener Container ist sinnvoll, wenn ein Dienst eigene Abhängigkeiten,
|
||
Zugangsdaten oder eine eigene Fehlergrenze hat. Deshalb bleiben die fachlichen
|
||
MCPs getrennt, beispielsweise Home Assistant, Unraid, ARR, Navidrome, Deemix,
|
||
Web und SSH. Es gibt jedoch keine zusätzlichen MCPs für einzelne
|
||
Zwischenschritte einer Installation.
|
||
|
||
Hermes ist die primäre Oberfläche für längere administrative und agentische
|
||
Aufgaben. OpenWebUI erhält weiterhin die Werkzeuge, die für kurze Abfragen
|
||
sinnvoll sind. Ein neuer MCP muss nicht automatisch in jede Oberfläche
|
||
eingebunden werden; das richtet sich nach dem Auftrag.
|
||
|
||
## Standardablauf für Änderungen
|
||
|
||
1. `athena_operator_inspect` einmal für den betroffenen Bereich aufrufen.
|
||
2. Mit `athena_operator_search_source` die konkrete Datei finden.
|
||
3. Mit `athena_operator_read_source` nur den benötigten Ausschnitt lesen.
|
||
4. Änderung über `athena_operator_change` ausführen.
|
||
5. Syntax, Compose, Dienstzustand und eine kleine Funktionsprobe prüfen.
|
||
6. Geänderte Dateien committen und pushen.
|
||
7. Ein manuelles Datenbackup nur nach speicherrelevanten Änderungen auslösen.
|
||
|
||
Nicht bei jedem Zwischenschritt die gesamte Plattform neu untersuchen. Keine
|
||
vollständigen Compose-, Installations- oder Dokumentationsdateien in den Chat
|
||
laden, wenn ein kleiner Ausschnitt genügt. Derselbe fehlgeschlagene Pfad oder
|
||
Werkzeugaufruf wird höchstens einmal wiederholt.
|
||
|
||
## Neuer MCP
|
||
|
||
Für einen neuen MCP sind gewöhnlich nur diese Teile nötig:
|
||
|
||
1. Servercode und Dockerfile unter `platform/mcp/`.
|
||
2. Ein Service im eingebundenen `platform/mcp/compose.yaml`.
|
||
3. Eine Env-Beispieldatei unter `config/`; echte Werte nach `/etc/mike-ai`.
|
||
4. Genau ein Eintrag in `config/mcp-registry.json`; daraus werden Hermes und
|
||
OpenWebUI automatisch erzeugt.
|
||
5. Ein kleiner Test sowie ein kurzer Eintrag in dieser Datei oder in der
|
||
Komponentenübersicht, falls wirklich zusätzliche Erklärung nötig ist.
|
||
|
||
Dann wird nur der neue MCP gebaut und gestartet. Router, Qwen, WireGuard,
|
||
Hermes und der komplette Stack werden nicht pauschal neu gestartet.
|
||
|
||
## Temporär oder dauerhaft
|
||
|
||
- „Nutze Programm X“: wenn es fehlt, nur temporär unter `/tmp` oder in einem
|
||
kurzlebigen Container verwenden und anschließend entfernen.
|
||
- „Installiere Programm X dauerhaft“: versioniert in den Stack aufnehmen.
|
||
- Bestehende Dienste auf Unraid oder im Heimnetz werden weiterverwendet; auf
|
||
Athena wird nicht ohne Grund eine zweite Instanz aufgebaut.
|
||
|
||
## Sicherheitsgrenze
|
||
|
||
Athena darf ohne ausdrücklichen, aktuellen Auftrag niemals heruntergefahren
|
||
oder neu gestartet werden. Ebenfalls tabu sind Änderungen an SSH, LAN,
|
||
WireGuard, Firewall, Bootloader, Kernel, Partitionen und Mounts. Diese Grenze
|
||
schützt die Erreichbarkeit des entfernten Hosts.
|
||
|
||
Innerhalb des vertrauenswürdigen WireGuard-Netzes dürfen die vorgesehenen
|
||
Container normal miteinander, mit dem Heimnetz und mit dem Internet
|
||
kommunizieren. Keine zusätzlichen Netzwerkbarrieren ohne konkreten Bedarf.
|
||
|
||
Secrets dürfen lokal von Athena und dem lokalen Modell verwendet werden. Sie
|
||
werden aber weder in Git noch in normalen Werkzeugausgaben oder Chatantworten
|
||
veröffentlicht.
|
||
|
||
## Fertig bedeutet
|
||
|
||
Eine Änderung ist erst fertig, wenn:
|
||
|
||
- der versionierte Arbeitsbaum die Änderung enthält,
|
||
- der betroffene Dienst den neuen Stand verwendet,
|
||
- ein fokussierter Test erfolgreich war,
|
||
- Git-Status und Commit bekannt sind,
|
||
- das automatische Backup läuft und bei Datenänderungen ein Archiv geprüft wurde.
|
||
|
||
Bei Unsicherheit wird der konkrete offene Punkt genannt. Es werden keine
|
||
Ergebnisse, Werkzeugaufrufe oder erfolgreichen Deployments erfunden.
|
||
|
||
## Referenzen
|
||
|
||
- Installation und Überblick: `README.md`
|
||
- Wiederherstellung: `docs/RECOVERY.md`
|
||
- Modellprofile: `docs/STANDARD_PROFILE_MATRIX.md`
|