Merge branch 'worktree-agent-ab032f7900d8a5a63' into wartung/snapshots-reiter

docs/ARCHITEKTUR.md

@@ -10,9 +10,9 @@ 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`).
+**Homelab** (Cockpit `/homelab`, Updates `/homelab/updates`, Snapshots `/homelab/snapshots`) —, 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
@@ -250,13 +250,17 @@ flowchart LR
   `snapshot_loeschen`, `sichern`, `sicherung_zurueck`, `sicherung_loeschen`, `host_update`, `host_neustart`) und
   prüft selbst, ob ein Gast das Etikett `community-script` oder `watcher` trägt und nicht `watcher-aus` — dem Server
   vertraut er dabei nicht. Seit 24.09. schickt er außerdem jede Minute Messwerte (eigener Faden, siehe „Monitoring“).
+  `snapshot` nimmt seit 25.09. einen Anlass (`update`, Standard, oder `knopf`) und wählt damit eine feste Beschreibung
+  („Vor einem Update durch …“ bzw. „Auf Knopfdruck im Homelab Orchestrator angelegt“) — freien Text nimmt er nicht.
 - **Bericht** (nur lesend, auch von Hand: `python3 ausfuehrer.py --bericht`): Host-Version und Paket-Updates, je
   Gast Status, IP, Etiketten, Snapshots, ob ein Snapshot geht (Bind-Mounts wie beim PBS verhindern ihn), die
   Community-Script-Kennung (aus `/usr/bin/update` im Gast), die App-Version (je App eigener Weg: `/root/.<app>`,
   `AdGuardHome --version`, `netbird version`, `dpkg-query`, Docker-Image-Datum) und die Paket-Updates im Gast samt
   Alter der Paketlisten. Dazu der Sicherungsspeicher (`host.sicherung`: Name und frei, oder was fehlt), je Container
   ohne Snapshot, ob eine Sicherung geht (`sicherung_moeglich`, sonst `sicherung_grund`), und die eigenen
-  Sicherungen je Gast.
+  Sicherungen je Gast. Seit 25.09. dazu `snapshot_details` (Name, `zeit` = snaptime, Beschreibung, `eigen` = Name
+  `mc2-…`; ohne Belegung, die kennt Proxmox bei LVM-Thin nicht) und `sicherung_details` (Archiv, `zeit` = ctime,
+  `groesse`); die Namenslisten `snapshots` und `sicherungen` bleiben unverändert.
 - **Sicherung statt Snapshot** (Ausführer, seit 24.09.): Wo kein Snapshot geht, sichert `sichern` den Container per
   `vzdump` — auf den ersten lokalen Speicher, der Sicherungen annimmt (Art `dir`/`btrfs`, nicht geteilt; heute
   `local` = `/var/lib/vz`), oder auf `sicherung_speicher` aus `/etc/mc2-ausfuehrer.json`. Nie auf einen Speicher der
@@ -278,7 +282,8 @@ flowchart LR
   Warnung in der Rückfrage; scheitert der Schritt, beginnt das Update nicht) → `update` des Community-Scripts
   (`PHS_SILENT=1`) bzw. Pakete → 20 s warten → frischer Bericht → Prüfung (Gast läuft, Weboberfläche antwortet,
   App-Version neu). Rot → zurück auf den Snapshot bzw. die Sicherung zurückspielen + dringende Meldung; grün → ältere
-  `mc2-`-Snapshots bzw. `mc2-sicherung`-Sicherungen dieses Gasts weg (die neueste bleibt) + Meldung. Läufe in
+  `mc2-`-Snapshots bzw. `mc2-sicherung`-Sicherungen dieses Gasts weg (die neueste bleibt, ebenso per Knopf auf der Seite
+  Snapshots angelegte: `snapshots.knopf_namen`) + Meldung. Läufe in
   `/var/lib/mc2/homelab-laeufe.json` und im strukturierten Update-Verlauf. Host: Pakete per Knopf mit Warnung,
   Neustart als eigener Knopf.
 - **Wartezeit nach Skriptänderung** (`karenz.py`): `update` lädt `ct/<kennung>.sh` ungepinnt von GitHub
@@ -315,8 +320,8 @@ flowchart LR
     „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
+  jüngsten 60 mit ganzer Ausgabe, ältere mit den letzten 4000 Zeichen), Update-Läufe mit ihren Schritten, die Aktionen
+  der Seite Snapshots (Art `snapshot`, seit 25.09.), 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
@@ -362,19 +367,41 @@ flowchart LR
   nicht eingebunden oder hängt = rot; eine Sicherung älter als erlaubt (Zeitplan nur mit Uhrzeit = täglich: 26 h,
   sonst 8 Tage) = gelb, bei allen Geräten oder unerreichbarem Ziel rot. Empfehlungen, größter Gewinn zuerst: Platz,
   den ein Gast freigegeben hat, der im Pool aber belegt bleibt (VM ohne Discard; Container per `pct fstrim`,
-  zusammengefasst ab 1 GB), ungenutzte und verwaiste Platten, Snapshots (Größe unbekannt, zuletzt). Seit 25.09. auch
+  zusammengefasst ab 1 GB), ungenutzte und verwaiste Platten, Snapshots (seit 25.09. ein einziger Vorschlag mit
+  Verweis auf die Seite Snapshots; Größe unbekannt, zuletzt). Seit 25.09. auch
   die Systemplatte des Hosts (`host.systemplatte`, `statvfs("/")` wie df) und alte Kernel: `host.kernel_alt` = was
   `apt-get -s autoremove` entfernen würde, nur Kernel-Pakete, nie laufender, nächster (`kernel_neu`) oder
   festgepinnter Kernel, mit Größe samt initrd; `host.kernel_bleiben`. Der Vorschlag hat einen Knopf
   (`POST /api/homelab/ziele/pve/kernel-aufraeumen` → Lauf `kernel` → Ausführer-Aktion `kernel_aufraeumen`, die die
   Liste selbst neu bestimmt und `apt-get -y purge` ausführt; Ergebnis `aufgeraeumt`). `neustart_noetig` kommt
   außerdem, wenn ein neuerer Kernel installiert ist als der laufende (Proxmox legt dafür kein reboot-required an).
+- **Snapshots verwalten** (`snapshots.py`, seit 25.09., User-Wunsch): `GET /api/homelab/snapshots` liefert je Gerät
+  (ohne den Container des Orchestrators) die Snapshots mit Zeitpunkt, Beschreibung und Herkunft (`update`, `knopf`,
+  `proxmox`), die Sicherungen des Orchestrators mit Größe, was gerade läuft (`laeuft`) und das Ergebnis der letzten
+  Aktion der Seite (6 h lang); Knöpfe samt Rückfrage schickt der Homelab-Teil mit, wie im Ziel-Modell. Ohne
+  `snapshot_details` (Ausführer vor dem 25.09.) kommt der Zeitpunkt aus dem Namen. Aktionen:
+  `POST …/snapshots/{id}/anlegen`, `…/snapshots/{id}/{name}/loeschen`, `…/snapshots/{id}/{name}/zuruecksetzen`,
+  `…/sicherungen/{id}/{datei}/loeschen` — nur freigegebene Gäste, löschen und zurücksetzen nur `mc2-…`, Sicherungen
+  nur, was der Bericht als eigene nennt; der Ausführer prüft das ohnehin selbst noch einmal. Jede Aktion ist ein Lauf
+  in `homelab-laeufe.json` (Bausteine `snapshot-anlegen`, `snapshot-loeschen`, `snapshot-zurueck`,
+  `sicherung-loeschen`) mit denselben Sperren wie „Jetzt updaten“ (`START_SPERRE`, je Gerät einer,
+  `SAMMELLAUF_SPERRE`), zusätzlich nicht, solange irgendwo ein Update läuft (`_sperre`: Der Ausführer arbeitet einen
+  Auftrag nach dem anderen ab — hinter einem Update liefe die Aktion in ihr Zeitlimit und käme später unbeobachtet
+  dran), und nur mit verbundenem Ausführer (nicht im Nur-Lesen-Modus). Abgelehnt wird mit 409; die Liste nennt
+  denselben Grund (`sperre`). Danach ein frischer Bericht. Zurücksetzen: `zurueck` (stoppt, setzt zurück, startet),
+  20 s, Prüfung wie nach einem Update, immer eine Meldung (Betreff „[Homelab-Snapshot]“, bei Fehler oder roter Prüfung
+  „[Alarm] Homelab-Snapshot“); anlegen und löschen melden nur ihr Scheitern. Nicht im Update-Verlauf, in der
+  Oberfläche nicht unter „Verlauf“ oder „Zuletzt eingespielt“. Per Knopf angelegte Snapshots erkennt `knopf_namen` an
+  der Beschreibung oder am Lauf; kein grünes Update räumt sie weg.
 - **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.
+  - **Snapshots** (`/homelab/snapshots`, seit 25.09.): je Gerät die Snapshots und Sicherungen mit Knöpfen
+    (`components/homelab/SnapshotListe.tsx`, Texte in `lib/snapshots.ts`); am Handy untereinander, ab `md` die Knöpfe
+    rechts, ab `xl` fünf Spalten.
   - 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

docs/BEDIENUNG.md

@@ -18,7 +18,7 @@ hinter dem Menü-Knopf oben links:
 - **Übersicht** — die Startseite, alles auf einen Blick.
 - **KI-Box** (Indigo): **Cockpit**, **Updates**, **Modelle**, **Monitoring**, **Dienste und Protokolle**, dazu
   das Hermes-Dashboard.
-- **Homelab** (Violett): **Cockpit**, **Updates**, **Monitoring**, **Protokoll**.
+- **Homelab** (Violett): **Cockpit**, **Updates**, **Snapshots**, **Monitoring**, **Protokoll**.
 - Ganz unten die **Einstellungen**.
 
 Jeder Bereich zeigt oben, ob er online ist, und neben „Updates“ die Zahl der Updates, die bereitstehen. Frühere
@@ -116,7 +116,9 @@ Werte zu jedem Zeitpunkt; „Werte als Tabelle“ klappt die letzten Punkte als
   Platz bringt“: Vorschläge mit ungefährem Gewinn, dem Ort und dem Klickweg in Proxmox, größter zuerst; aufgeklappt,
   sobald Pool oder Systemplatte knapp werden. Gelöscht wird nichts von selbst — nur alte Kernel haben einen Knopf
   („Alte Kernel entfernen“, mit Rückfrage): Entfernt wird, was Proxmox selbst für entbehrlich hält, nie der laufende
-  oder der Kernel für den nächsten Start; die Gäste laufen weiter.
+  oder der Kernel für den nächsten Start; die Gäste laufen weiter. Alle Snapshots stehen dort seit 25.09. als **ein**
+  Vorschlag („5 Snapshots des Orchestrators — verwalten unter Homelab → Snapshots“) mit dem Verweis „Zu den
+  Snapshots“.
 
 ## Homelab · Updates
 
@@ -136,6 +138,29 @@ Werte zu jedem Zeitpunkt; „Werte als Tabelle“ klappt die letzten Punkte als
   bleibt stehen. Während des Laufs zeigt ein Kasten jeden Schritt mit Zustand; am Ende kommt eine Nachricht.
 - **Verlauf:** die letzten Updates im Homelab mit Ergebnis.
 
+## Homelab · Snapshots
+
+Seit 25.09. Je Gerät (die Container und die Arcane-VM) seine Snapshots, beim Proxmox Backup Server die Sicherungen,
+die der Orchestrator dort vor Updates anlegt (ein Snapshot geht beim PBS nicht).
+
+- **Eine Zeile je Snapshot:** Name, Herkunft („vor Update“ = Rückweg eines Updates, „per Knopf“ = hier angelegt,
+  „von Hand“ = in Proxmox angelegt), Zeitpunkt und Alter, die Beschreibung aus Proxmox. Wie viel ein Snapshot im
+  Speicherpool belegt, sagt Proxmox nicht; er wächst mit jeder Änderung seit seinem Zeitpunkt.
+- **Snapshot anlegen:** legt sofort einen an, das Gerät läuft dabei weiter. So angelegte räumt kein Update weg — sie
+  bleiben, bis du sie löschst. Wo keiner geht (PBS) oder das Gerät nicht freigegeben ist (Etikett „watcher“ fehlt),
+  steht der Grund statt des Knopfs.
+- **Zurücksetzen:** setzt das Gerät auf diesen Snapshot zurück. Alles, was sich seitdem darin geändert hat, ist danach
+  weg; das Gerät wird gestoppt und wieder gestartet und ist ein paar Minuten nicht erreichbar. Danach prüft der
+  Orchestrator, ob es wieder antwortet, und schickt eine Nachricht (dringend, wenn nicht). Die Rückfrage sagt das
+  vorher; wer den jetzigen Stand behalten will, legt vorher einen Snapshot an.
+- **Löschen:** löscht einen Snapshot oder eine Sicherung des Orchestrators endgültig; am Gerät selbst ändert sich
+  nichts. Von Hand angelegte Snapshots lassen sich hier nur ansehen, gelöscht werden sie in Proxmox.
+- Während etwas läuft, steht beim Gerät „Läuft: …“, danach das Ergebnis. Eine Nachricht kommt beim Zurücksetzen immer,
+  beim Anlegen und Löschen nur, wenn es scheitert. Solange irgendwo ein Update oder „Alle aktualisieren“ läuft oder der
+  Ausführer schweigt, ruhen die Knöpfe, und oben steht warum: Der Ausführer erledigt einen Auftrag nach dem anderen.
+- Nach einem grünen Update räumt der Orchestrator ältere Rückwege dieses Geräts selbst weg — nicht die per Knopf
+  angelegten.
+
 ## Homelab · Monitoring
 
 Wie beim Monitoring der KI-Box: Zeitraum oben, darunter der Proxmox-Host (CPU, Speicher, Temperatur, Systemplatte,
@@ -144,7 +169,8 @@ Netz) und für jeden Gast CPU und Speicher. Die Werte kommen jede Minute vom Aus
 ## Homelab · Protokoll
 
 Was der Homelab-Teil getan hat, neueste zuerst und nach Tagen: Aufträge an den Ausführer (Snapshot, Update, Suche …),
-Update-Läufe, Hinweise des Wächters, gesendete Meldungen und die nächtliche Paketsuche. Oben filterst du nach Art;
+Update-Läufe, was auf der Seite Snapshots geschah, Hinweise des Wächters, gesendete Meldungen und die nächtliche
+Paketsuche. Oben filterst du nach Art;
 „Berichte zeigen“ blendet auch die Berichte ein, die alle zehn Minuten kommen. „Ausgabe zeigen“ klappt die Ausgabe
 eines Auftrags auf.