From 5af3ca75db102c6ced8cbf1ea07c7474b8771065 Mon Sep 17 00:00:00 2001 From: Hitonabi Date: Fri, 25 Sep 2026 10:09:21 +0200 Subject: [PATCH] =?UTF-8?q?doku:=20=E2=80=9EAlle=20aktualisieren=E2=80=9C,?= =?UTF-8?q?=20Protokoll=20und=20Arcane-Schl=C3=BCssel=20in=20ARCHITEKTUR,?= =?UTF-8?q?=20BETRIEB=20und=20OFFENE-FAEDEN?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nur die eigenen Abschnitte: neue Punkte im Homelab-Teil vor „Arcane und Docker“ bzw. vor „Wöchentliches Suchen“, der Arcane-Punkt, eine Zeile in der Betreff-Tabelle und der offene Punkt Arcane-Schlüssel (jetzt in der Oberfläche eintragbar). Co-Authored-By: Claude Opus 5.5 --- docs/ARCHITEKTUR.md | 46 ++++++++++++++++++++++++++++++++++-- docs/BETRIEB.md | 23 ++++++++++++++++++ docs/wissen/OFFENE-FAEDEN.md | 7 +++--- 3 files changed, 71 insertions(+), 5 deletions(-) diff --git a/docs/ARCHITEKTUR.md b/docs/ARCHITEKTUR.md index 3e0d436..e40b795 100644 --- a/docs/ARCHITEKTUR.md +++ b/docs/ARCHITEKTUR.md @@ -278,10 +278,52 @@ flowchart LR gerade berichtet, bevorzugt nachts 02:00–05:00 (war die Instanz letzte Nacht aus, eben gleich). Keine Meldungen; scheitert die Suche für einen Gast zweimal hintereinander, wird es ein gelber Hinweis des Wächters. Zustand in `/var/lib/mc2/homelab-pflege.json`. Weil damit zwei Prozesse Aufträge anlegen, schreibt `kanal.py` unter `flock`. +- **„Alle aktualisieren“** (`sammellauf.py`, seit 24.09.): alle Updates mit Knopf nacheinander, jeder Schritt ein + gewöhnlicher Lauf von „Jetzt updaten“ (`updates.starten`), auf dessen Ende der nächste wartet. Dabei ist nur, was + „neu“ ist und eine Aktion hat; was in der Wartezeit steht, fehlt. Docker über Arcane nur, wenn es echt läuft (ein + Probelauf ändert nichts). Reihenfolge: die Gäste nach VMID außer NPMplus und AdGuard, dann NPMplus, dann AdGuard + (Nadelöhre für Proxy und DNS), ganz zuletzt die Pakete des Proxmox-Hosts; der Neustart des Hosts ist nie dabei. + `GET /api/homelab/alle/plan` zeigt diese Reihenfolge mit dem Rückweg je Schritt und einem Hinweis (was keinen + Rückweg hat, dass der Host zuletzt kommt). `POST /api/homelab/alle` startet, wenn es etwas zu tun gibt, der + Ausführer verbunden ist (und nicht im Nur-Lesen-Modus) und gerade kein einzelnes Update läuft. + - Endet ein Schritt mit `zurueckgerollt` oder `fehler` (auch „Update nicht begonnen“), hört der Sammellauf auf: die + übrigen Schritte `uebersprungen`, Status `abgebrochen`, dringende Meldung. Lehnt `updates.starten` einen Schritt ab + (etwa weil die Wartezeit inzwischen greift), wird nur dieser übersprungen. Läuft alles durch, kommt eine + Sammelmeldung („Homelab: 5 Updates eingespielt, alle Prüfungen grün.“); die Erfolgsmeldungen der Schritte hält + `updates._ende` so lange zurück (`gemeldet: false` am Lauf), Fehlermeldungen nicht. Im Update-Verlauf stehen die + Schritte als ein Lauf mit dem Anlass „Alle aktualisieren“. + - Höchstens ein Sammellauf; solange er läuft, lehnt „Jetzt updaten“ ab („Es läuft gerade ‚Alle aktualisieren‘.“). + Prüfen und Anlegen geschehen unter `updates.START_SPERRE`. Stand in `/var/lib/mc2/homelab-sammellauf.json` (die + letzten 20; `GET /api/homelab/sammellauf` liefert den laufenden oder den letzten). Startet der Homelab-Teil mitten + im Lauf neu, macht `updates.unterbrochene_abschliessen()` beim Start daraus `abgebrochen` mit dem Text + „unterbrochen (Neustart)“ und meldet es dringend. +- **Protokoll** (`protokoll.py`, seit 24.09.): `GET /api/homelab/protokoll?grenze=200&berichte=0` führt zusammen, was + geschah, neueste zuerst: Aufträge an den Ausführer (`kanal.py` hebt jetzt die letzten 500 erledigten auf; die + jüngsten 60 mit ganzer Ausgabe, ältere mit den letzten 4000 Zeichen), Update-Läufe mit ihren Schritten, + Sammelläufe, den Verlauf der Hinweise des Wächters (der Verlauf in `mc2-waechter.json` trägt seit 24.09. die Stufe + mit), die Zeilen des Melde-Logs (`MC_NOTIFY_LOG`, im Container `/var/lib/mc2/notify.log`) und die Ereignisse des + wöchentlichen Suchens (`homelab-pflege.json`, Liste `ereignisse`). Berichte nur mit `berichte=1`: die Aufträge + `bericht` der Läufe und die Berichte, die der Ausführer von sich aus schickt (ihr Eingang steht in + `/var/lib/mc2/ausfuehrer-berichte.json`, die letzten 150). Den Betreff einer Meldung schreibt `notify.sh` nicht ins + Log; er folgt aus dem Absender (Lauf, Sammellauf, Wächter, Telegram-Test, Morgenmeldung). Nichts im Protokoll + enthält Geheimnisse: Die Schlüssel dieser Instanz (Arcane, Ausführer) und alles, was wie ein Token aussieht + (Bot-Token, Bearer, `name=wert` mit verräterischem Namen, Zugangsdaten in Adressen), wird zu `***`; Steuerzeichen der + Konsole fallen weg. +- **Einstellungen des Homelab-Teils** (`einstellungen.py`, seit 24.09.): `GET /api/homelab/einstellungen` (Arcane: + Adresse aus dem Bericht, Herkunft des Schlüssels `hinterlegt`/`fehlt`/`umgebung`, echt und woher; Wartezeit in + Stunden; Ausführer). `POST …/arcane-schluessel` prüft den Schlüssel zuerst bei Arcane mit denselben Aufrufen, die die + Übersicht braucht (`/api/environments`, dann deren Images); nur wenn Arcane ihn annimmt, landet er in + `/var/lib/mc2/arcane.key` (0600). Er steht nie in einer Antwort, einem Protokoll oder einer Fehlermeldung; den Body + liest der Dienst selbst, damit keine 422-Antwort ihn wiederholt. `DELETE …/arcane-schluessel` löscht die Datei, + `POST …/arcane-echt` (`{"an": bool}`) schaltet echte Docker-Updates in `/var/lib/mc2/homelab-einstellungen.json`. + Was nicht geht, beantworten diese Endpunkte wie „Alle aktualisieren“ mit `{"ok": false, "detail": …}` und HTTP 200. - **Arcane und Docker** (`services/homelab/arcane.py`): Arcanes eigene Version kommt öffentlich über `/api/app-version`; die Docker-Images mit neuerem Stand und der Updater brauchen einen Arcane-API-Schlüssel - (`MC_ARCANE_KEY`, Kopfzeile `X-API-Key`). Docker-Updates laufen zuerst nur als Probelauf (`dryRun`); echt erst - mit `MC_ARCANE_ECHT=1`. Die Arcane-VM braucht dafür kein Etikett, weil der Ausführer nicht beteiligt ist. + (Kopfzeile `X-API-Key`): `MC_ARCANE_KEY` in `/etc/mc2/homelab.env`, sonst der Schlüssel aus den Einstellungen + (`arcane.key`); beides wird bei jedem Zugriff gelesen, ein neuer Schlüssel gilt ohne Neustart. Docker-Updates laufen + zuerst nur als Probelauf (`dryRun`); echt, wenn der Schalter in den Einstellungen an ist. Setzt die Umgebung + `MC_ARCANE_ECHT`, gewinnt sie (`1` = echt). Die Arcane-VM braucht dafür kein Etikett, weil der Ausführer nicht + beteiligt ist. - **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), die Platten der laufenden Container (ab 80 % gelb, ab 90 % rot — ext4 hält 5 % für root zurück; der Ausführer schickt `platte` mit) und das diff --git a/docs/BETRIEB.md b/docs/BETRIEB.md index 63963b6..170bfcd 100644 --- a/docs/BETRIEB.md +++ b/docs/BETRIEB.md @@ -58,6 +58,7 @@ sudo journalctl -u llama-swap -n 100 # Motor (System-Dienst) | `[Box-Problem]` | Wächter | neuer roter Hinweis; nach 6 h erneut mit „Immer noch:" | | `[Box wieder ok]` | Wächter | ein gemeldeter roter Hinweis ist erledigt | | `[Homelab-Problem]` / `[Homelab wieder ok]` | Wächter der Homelab-Instanz | wie oben, sobald diese Instanz läuft | +| `[Homelab-Update]` / `[Alarm] Homelab-Update` | „Jetzt updaten“ und „Alle aktualisieren“ im Homelab | Ergebnis je Lauf, dringend bei Rot; bei „Alle aktualisieren“ (seit 24.09.) nur Fehler einzeln, am Ende eine Sammelmeldung, dringend bei Abbruch | | `[Modell-Radar]` | `backend/radar_lauf.py` | ein Kandidat hat den Nachttest bestanden | | `[Sicherung]` | `backend/services/probe_wiederherstellung.py` | die monatliche Probe-Wiederherstellung war rot (normale Dringlichkeit) | | `[Stack-Radar]` | `jobs/stack-radar.sh` | Samstagsbericht | @@ -251,6 +252,28 @@ laufen lassen. Achtung: `ausfuehrer-einrichten.sh` schreibt `/etc/mc2-ausfuehrer - **Wartezeit nach Skriptänderung:** Ist `ct/.sh` bei community-scripts jünger als `MC_HOMELAB_KARENZ_H` Stunden (Standard 48), zeigt die Karte „Update bereit“ ohne Knopf und nennt, ab wann es geht. Ändern oder abschalten (`0`): `MC_HOMELAB_KARENZ_H=…` in `/etc/mc2/homelab.env` im Container, dann `systemctl restart mc2-homelab`. +- **Arcane-Schlüssel (seit 24.09. über die Oberfläche):** in Arcane unter Einstellungen → API-Schlüssel anlegen, dann in + der Oberfläche unter Einstellungen (Karte Homelab) eintragen. Der Homelab-Teil fragt Arcane erst, ob der Schlüssel + gilt (Umgebungen und Images lesen); nur dann speichert er ihn in `/var/lib/mc2/arcane.key` (0600, Eigentümer `mc2`), + und die Übersicht sieht die Docker-Images ohne Neustart. Lehnt Arcane ab (etwa „HTTP 401“) oder antwortet nicht, + wird nichts gespeichert. Der Schlüssel erscheint danach nirgends mehr (Antwort, Protokoll, Journal). Löschen: + derselbe Knopf in der Oberfläche oder `rm /var/lib/mc2/arcane.key`. `MC_ARCANE_KEY` in `/etc/mc2/homelab.env` geht + weiter vor; solange es gesetzt ist, lehnt die Oberfläche das Eintragen ab und sagt warum. +- **Docker-Updates echt statt Probelauf:** Schalter in den Einstellungen, gespeichert in + `/var/lib/mc2/homelab-einstellungen.json` (`{"arcane": {"echt": true}}`). Setzt `/etc/mc2/homelab.env` + `MC_ARCANE_ECHT`, gewinnt die Umgebung (`1` = echt, sonst Probelauf), und der Schalter sagt es. +- **„Alle aktualisieren“ (seit 24.09.):** spielt alle Updates mit Knopf nacheinander ein — die Gäste nach VMID, dann + NPMplus, dann AdGuard, zuletzt die Pakete des Proxmox-Hosts (ohne Neustart). Ist ein Schritt rot (zurückgerollt oder + gescheitert), bleibt der Rest stehen, und es kommt eine dringende Meldung; sonst am Ende eine Sammelmeldung. + Solange er läuft, lehnen die einzelnen Knöpfe „Jetzt updaten“ ab. Stand: + `curl -s http://192.168.178.31:9001/api/homelab/sammellauf` bzw. `/var/lib/mc2/homelab-sammellauf.json`. Startet + `mc2-homelab` mitten im Lauf neu (auch durch einen Deploy), gilt er als abgebrochen („unterbrochen (Neustart)“, mit + dringender Meldung); der Schritt, der gerade lief, steht auf „fehler“ — den Stand des Geräts in der Übersicht prüfen. +- **Protokoll (seit 24.09.):** `curl -s 'http://192.168.178.31:9001/api/homelab/protokoll?grenze=50' | jq` zeigt + Aufträge, Läufe, Sammelläufe, Hinweise, Meldungen und das wöchentliche Suchen, neueste zuerst; `&berichte=1` auch die + Berichte des Ausführers. Die Quellen bleiben die Dateien in `/var/lib/mc2` (`ausfuehrer-auftraege.json` hebt jetzt + die letzten 500 erledigten Aufträge auf, `ausfuehrer-berichte.json` die Eingänge der letzten 150 Berichte) und das + Melde-Log `/var/lib/mc2/notify.log`. - **Wöchentliches Suchen:** Der Steward legt für jeden freigegebenen, laufenden Container, dessen Paketlisten älter als 7 Tage sind, den Auftrag `suchen` an (nur `apt-get update` bzw. `apk update` im Gast, es wird nichts installiert): nachts 02:00–05:00, höchstens einmal je Gast und Tag, nicht während eines Updates; war die Instanz nachts aus, gleich diff --git a/docs/wissen/OFFENE-FAEDEN.md b/docs/wissen/OFFENE-FAEDEN.md index 463c307..16ab454 100644 --- a/docs/wissen/OFFENE-FAEDEN.md +++ b/docs/wissen/OFFENE-FAEDEN.md @@ -31,9 +31,10 @@ Technik: [ARCHITEKTUR.md](../ARCHITEKTUR.md), Abschnitt „Der Homelab-Teil“; Proxmox-Host gelegt (`/root/mc2-archiv/adguard-querylog-bis-2026-08-09.json.zst`, 44 MB) und aus dem Container genommen; jetzt 71 % belegt. Damit es nicht wieder vollläuft: in AdGuard unter Einstellungen → Allgemein → Abfrageprotokoll die Aufbewahrung z. B. auf 30 Tage stellen. Volle Gastplatten meldet seit 24.09. der Wächter. -1. **Arcane-API-Schlüssel fehlt.** Ohne ihn zeigt die Arcane-Karte die Docker-Images als „unklar“. Anlegen in Arcane - (Einstellungen → API-Schlüssel), dann `MC_ARCANE_KEY=…` in `/etc/mc2/homelab.env` im Container 107 und - `systemctl restart mc2-homelab mc2-homelab-steward`. Docker-Updates bleiben Probelauf bis `MC_ARCANE_ECHT=1`. +1. **Arcane-API-Schlüssel fehlt (User).** Ohne ihn zeigt die Arcane-Karte die Docker-Images als „unklar“. Seit 24.09. + in der Oberfläche eintragbar: in Arcane unter Einstellungen → API-Schlüssel anlegen, dann in der Oberfläche unter + Einstellungen (Karte Homelab) einfügen. Arcane prüft ihn vor dem Speichern; ein Neustart ist nicht nötig. + Docker-Updates bleiben Probelauf, bis der Schalter „Docker-Updates echt“ dort an ist. 2. **Feste IP für Container 107.** Er hat seine Adresse per DHCP (192.168.178.31); Partner-Adresse der Box, Ausführer-Konfiguration und der Deploy-Schritt 8 hängen daran. In der Fritzbox die Adresse fest zuordnen. 3. **Die Arcane-VM (106) trägt kein Etikett.** Für Arcane und Docker braucht es keins (eigene Schnittstelle); für