From d835d41610cce2dcb08f30d7dbd5bd94141a4fe3 Mon Sep 17 00:00:00 2001 From: Hitonabi Date: Thu, 24 Sep 2026 20:37:57 +0200 Subject: [PATCH] doku: Architektur beschreibt die getrennten Bereiche der Oberflaeche und den Homelab-Teil als live Co-Authored-By: Claude Opus 5.5 --- docs/ARCHITEKTUR.md | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/ARCHITEKTUR.md b/docs/ARCHITEKTUR.md index 84023d5..7d76edf 100644 --- a/docs/ARCHITEKTUR.md +++ b/docs/ARCHITEKTUR.md @@ -5,8 +5,14 @@ Messwerten: [wissen/STACK.md](wissen/STACK.md)._ Der Homelab Orchestrator (vormals Mission Control 2, kurz „MC2") hat zwei Bereiche: „Box-Wart" für die KI-Box und „Homelab" für den Proxmox-PC. Zwei Instanzen, eine Oberfläche: Dieselbe Codebasis läuft auf der KI-Box (Rolle `box`) -und später als Container auf dem Proxmox-PC (Rolle `homelab`). Die Homelab-Instanz ist noch nicht eingerichtet -(Phase 3, braucht User-OK); dieses Dokument beschreibt deshalb vor allem die Rolle `box`. +und als Container 107 auf dem Proxmox-PC (Rolle `homelab`, seit 24.09.). Der Homelab-Teil hat unten einen eigenen +Abschnitt; der Rest beschreibt vor allem die Rolle `box`. + +In der Oberfläche sind beide Bereiche getrennt (seit 24.09.): Links steht die Menüführung mit einem Block je Bereich +— **KI-Box** (Cockpit `/`, Updates `/updates`, Modelle `/modelle`, dazu Dienste und das Hermes-Dashboard) und +**Homelab** (Cockpit `/homelab`, Updates `/homelab/updates`) —, jeder mit eigener Verbindungsanzeige und der Zahl +offener Updates. Keine Seite zeigt etwas aus dem anderen Bereich. Am Handy steckt dieselbe Leiste hinter dem +Menü-Knopf (`frontend/src/app/Seitenleiste.tsx`, `lib/navigation.ts`). Der Box-Wart hält die KI-Box aktuell, passt auf sie auf und sucht bessere Modelle. Er besteht aus vier eigenen Python-Prozessen, einer Bash-Schicht für Updates, Sicherung und Meldungen und aus Zustandsdateien unter @@ -77,9 +83,10 @@ Fremde Dienste, die der Box-Wart nur steuert oder überwacht: `llama-swap` (Syst - **`backend/kern/zeit.py`:** die eine Zeitzone `MC_LOCAL_TZ` (Standard `Europe/Berlin`) statt einer Kopie je Modul. - **`backend/kern/partner.py`:** Lebenszeichen der anderen Instanz über deren `/api/health` (5 s Zeitlimit, 15 s zwischengespeichert). -- **Rolle `box`** hängt alle Box-Router ein. **Rolle `homelab`** lädt nur `/api/health` und `/api/partner`; die - Homelab-Router folgen in Phase 3. `steward.py` betreibt Re-Warm und Config-Watch nur in der Rolle `box`; der - Wächter prüft im Homelab nur Platte und Partner. +- **Rolle `box`** hängt alle Box-Router ein. **Rolle `homelab`** lädt `/api/health`, `/api/partner`, die + Homelab-Router (`/api/homelab/…`) und einen eigenen Live-Strom; alles andere reicht die Oberfläche über + `/api/partner/…` an die Box weiter. `steward.py` betreibt Re-Warm und Config-Watch nur in der Rolle `box`; die + Prüfungen des Wächters im Homelab stehen im Abschnitt „Der Homelab-Teil“. - **`/api/health`** nennt `rolle` und `instanz`; `engine_reachable`, `gateway_reachable` und `brain` gibt es nur auf der Box. - **`GET /api/partner`** liefert das Lebenszeichen der anderen Instanz. **`/api/partner/`** reicht an @@ -116,7 +123,7 @@ Fremde Dienste, die der Box-Wart nur steuert oder überwacht: `llama-swap` (Syst - **Box-Adapter** `services/box_updates.py` (`ki_box_ziel()`): Betriebssystem, Motor, llama-swap und Hermes aus dem Zwischenspeicher der Update-Prüfung (10 Minuten, nach jedem Update sofort neu), Pins als `festgehalten`, gescheiterte Prüfungen als `unbekannt`. `GET /api/ziele` liefert die KI-Box; der Homelab-Teil liefert seine - Ziele ab Phase 3 unter `/api/homelab/ziele`, die Oberfläche legt beide zu einer Liste zusammen. + Ziele unter `/api/homelab/ziele`. Die Oberfläche zeigt beide getrennt, jedes in seinem Bereich. - **Strukturierter Update-Verlauf** `/mc2-update-verlauf.jsonl`: je Baustein eine JSON-Zeile (`lauf`, `anlass`, `ts`, `baustein`, `ergebnis`, `text`). Es schreiben `autoupdate.sh` (Helfer `ergebnis`/`verlauf`; die Telegram-Texte bleiben Zeichen für Zeichen gleich) und die Update-Knöpfe (Abschluss-Haken @@ -207,7 +214,7 @@ Routen. `Origin` (Skripte, `curl`), `Origin: null` bzw. `file://` (Lucy-Desktop), dieselbe Adresse wie die Oberfläche und die Entwicklungs-Ports 5173, 5180, 5181. `/v1` ist nicht betroffen. -## Der Homelab-Teil (Phasen 3 und 4, Code seit 24.09.; Einrichtung wartet auf das User-OK) +## Der Homelab-Teil (Phasen 3 und 4, live seit 24.09.) Derselbe Code in der Rolle `homelab`, in einem eigenen Container auf dem Proxmox-PC (`deploy/homelab/`). Er braucht **keinen Proxmox-Schlüssel**: Alles, was vom Host kommt, liefert der Ausführer. @@ -278,8 +285,14 @@ flowchart LR - **Wächter** in der Rolle `homelab`: Platte, Partner (die KI-Box), Ausführer (kein Bericht seit 30 min = rot), jede Weboberfläche der freigegebenen Gäste (außer mitten in ihrem Update-Lauf; das Ergebnis meldet der Lauf) und das wöchentliche Suchen (gelb, wenn es wiederholt scheitert). -- **Oberfläche**: Die Seite „Homelab“ zeigt alle Geräte als Karten — die KI-Box (`/api/ziele`) und alles aus - `/api/homelab/ziele` — mit Stand je Baustein, Rückweg und Knopf samt Rückfrage. +- **Oberfläche** (Bereich „Homelab“, nur Daten aus `/api/homelab/…`): + - **Cockpit** (`/homelab`): oben die Lage wie das Warnpanel der KI-Box — die große Leuchte (Störung vor Hinweis vor + laufendem Update vor offenen Updates) und eine Lampe je Gerät —, darunter die Hinweise des Homelab-Wächters und + die Geräteliste (App-Version, Paketstand, Erreichbarkeit; „Nach Updates suchen“ nur, wo der Stand unklar ist). + - **Updates** (`/homelab/updates`): nur die offenen Updates, eine Zeile je Update mit alter und neuer Version, + Rückweg in Kurzform (`rueckweg_art`) und Knopf samt Rückfrage aus dem Ziel-Modell; darunter der Verlauf der Läufe. + - Die Logik (Lage, Lampen, Reihenfolge) liegt in `frontend/src/lib/homelab.ts`, die Ansichten in + `components/homelab/` und `views/Homelab.tsx`. - **Meldungen** ohne Hermes: `notify.sh` im Container nimmt den Zweitweg direkt an die Bot-API (`/etc/mc2/telegram.env`), nachts sammelt eine eigene Morgenmeldung („[Morgenmeldung Homelab]“). - **Einrichtung** (Reihenfolge, jeder Schritt braucht das User-OK): `container-anlegen.sh` → `ausrollen.sh ` →