111 lines
4.9 KiB
Markdown
111 lines
4.9 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äche und Agent: Hermes auf Unraid unter
|
||
`/mnt/nvme-storage/appdata/Hermes-Agent`. Athena stellt dafür nur die
|
||
OpenAI-kompatible Router-API bereit. OpenWebUI ist abgeschaltetes Rückfallnetz.
|
||
- 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
|
||
|
||
Athena betreibt nur Inferenz, Router, Sprache/Bild, Backup und den
|
||
hostgebundenen Athena-Operator. Portable Fach-MCPs laufen als getrennte
|
||
Unterprozesse im **einen MCPHub-Container auf Unraid**. Sie bleiben unter
|
||
`/mcp/NAME` einzeln sichtbar und abschaltbar, brauchen aber nicht je einen
|
||
Docker-Container. `config/mcp-registry.json` ist die einzige Serverliste.
|
||
|
||
## 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
|
||
|
||
Portable MCPs werden nach dem Skill `mcphub-deployer` in das reproduzierbare
|
||
MCPHub-Image eingebaut. Dazu gehören gepinnte Quelle, genau ein Registry-Eintrag,
|
||
Secret-Datei nur im Appdata, Build, Handshake und eine read-only-Probe. Danach
|
||
wird ausschließlich MCPHub über Unraid DockerMan neu erstellt. Router, Qwen,
|
||
WireGuard und andere Container werden nicht neu gestartet.
|
||
|
||
Nur ein Werkzeug, das Athenas Host selbst verwalten muss, gehört in den
|
||
Athena-Operator. Es wird kein zweiter allgemeiner Terminal- oder Doku-MCP gebaut.
|
||
|
||
## 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`
|