# Betriebshandbuch Was tun, wenn etwas schiefgeht? Diese Seite ist für den Ernstfall geschrieben, auch für jemanden, der Munin nicht selbst gebaut hat. Jeder Abschnitt beginnt mit dem, was man sieht, und endet mit dem, was man tut. Die Befehle gehen vom Docker-Aufbau aus dem README aus: Container `munin`, Volume unter `/data`. Ohne Docker gilt dasselbe mit dem eigenen `DATA_DIR` statt `/data`, und die Ausgabe des Prozesses statt `docker logs`. --- ## Auf einen Blick | Was | Wo | |---|---| | Kontroll-Datenbank | `DATA_DIR/control.db`: Workspaces, welcher Key zu welchem Workspace gehört, Workspace-Admins | | Ein Workspace | `DATA_DIR/workspaces/.db`: Projekte, Einträge, Keys, Protokoll dieses Workspace | | Zugehörige Hilfsdateien | `…db-wal` und `…db-shm` neben jeder Datenbank. Sie gehören im laufenden Betrieb dazu, **nie einzeln löschen, solange der Server läuft** | | Logs | Standardausgabe des Prozesses: `docker logs munin` | | Sicherungen | `BACKUP_DIR//` von `scripts/backup.sh`, siehe README „Datensicherung“ | | Markdown-Export | `EXPORT_DIR`, falls gesetzt. Lesbar, aber **keine** vollständige Sicherung (keine Keys, keine Historie) | | Geheimnisse | `SESSION_SECRET`, `ADMIN_TOKEN` als Umgebungsvariablen, siehe README „Konfiguration“ | | Lebenszeichen | `GET /healthz` antwortet `ok` | Welcher Workspace hinter einer ID steckt: ```sh sqlite3 /data/control.db "SELECT id, name FROM workspaces;" ``` --- ## Läuft er? ```sh curl -s https:///healthz # erwartet: ok docker logs --tail 50 munin ``` Beim Start schreibt Munin diese Zeilen ins Log. Fehlen sie, ist der Start gescheitert: ``` Munin läuft auf http://localhost:8080 (3 Workspaces) Workspaces: /data/workspaces (Kontrolle: /data/control.db) Schreibbudget: 1000 Aufrufe je Projekt und Stunde (Vorgabe) ``` `/healthz` prüft nur, ob der Prozess antwortet, nicht die Datenbanken. Ein `ok` heißt also nicht, dass jeder Workspace lesbar ist. Siehe dazu [Datenbank beschädigt](#datenbank-beschädigt). --- ## Server startet nicht **Man sieht:** Der Container beendet sich sofort, `/healthz` antwortet nicht. `docker logs munin` zeigt die Ursache in der letzten Zeile: | Meldung | Ursache | Abhilfe | |---|---|---| | `SESSION_SECRET ist nicht gesetzt` / `zu kurz` | Umgebungsvariable fehlt oder hat weniger als 32 Zeichen | Aus dem Passwortspeicher setzen. **Nicht** neu erzeugen, wenn es ein altes gibt, sonst sind alle Anmeldungen weg | | `ADMIN_TOKEN ist nicht gesetzt` / `zu kurz` | dasselbe, mindestens 16 Zeichen | dasselbe | | `Datenverzeichnis konnte nicht angelegt werden` | Volume fehlt oder gehört nicht dem Benutzer im Container (UID 10001) | `chown -R 10001:10001` auf das Volume, oder richtig einhängen | | `unable to open database file`, `permission denied` | dasselbe für eine einzelne Datei, oft nach einem Zurückkopieren als root | Besitzer der Datei korrigieren | | `address already in use` | Ein anderer Prozess belegt den Port | anderen Prozess beenden oder `PORT` ändern | | `database disk image is malformed` | beschädigte Datenbank | [Datenbank beschädigt](#datenbank-beschädigt) | --- ## Platte voll **Man sieht:** Lesen geht noch, Schreiben schlägt fehl. Im Log steht `database or disk is full`, Agenten bekommen Fehler bei `remember`. SQLite bleibt dabei heil. Ein Schreibvorgang, der nicht mehr passt, wird vollständig zurückgerollt, halbe Einträge gibt es nicht. 1. Nachsehen, was wächst: `du -sh /data/* /data/workspaces/* /* ` 2. Platz schaffen, in dieser Reihenfolge: - alte Sicherungen löschen und `RETENTION_DAYS` im Cronjob setzen, falls es fehlt - Docker-Logs begrenzen (`--log-opt max-size=50m`) 3. **Nicht** die `-wal`- oder `-shm`-Dateien löschen. Darin stehen Änderungen, die noch nicht in der Hauptdatei sind. Sobald wieder Platz ist, schreibt Munin ohne Neustart weiter. --- ## Ein Key ist in falsche Hände geraten Zum Beispiel in ein öffentliches Repository eingecheckt, in einem Chat gepostet, oder der Laptop ist weg. 1. Mit Admin-Rechten anmelden, ins Projekt wechseln, **Zugänge** → beim betroffenen Key **Zurückziehen**. Das wirkt sofort, für MCP-Aufrufe und für Sitzungen in der Weboberfläche. Jede Anfrage prüft den Key neu in der Datenbank. 2. Unter **Protokoll** in der Spalte *Wer* nach dem Namen des Keys suchen (ein Filter fehlt bisher, die Suche des Browsers hilft): Was wurde damit getan, von welchen Adressen? Unbekannte Adressen deuten auf Missbrauch hin. 3. Hat der Key geschrieben, was er nicht sollte: Einträge über ihre **Historie** auf eine frühere Fassung zurücksetzen, Gelöschtes aus dem **Papierkorb** holen. 4. Dem Team einen neuen Key ausstellen. Wer den Key nicht kennt, findet ihn über den Workspace: Der Plattform-Admin sieht alle Workspaces, ein Workspace-Admin alle Projekte seines Workspace. --- ## Ein Workspace-Admin-Token (`wa_…`) ist in falsche Hände geraten Ein solches Token öffnet den ganzen Workspace. 1. Als Plattform-Admin **Workspaces** → **Bearbeiten** → Abschnitt *Workspace-Admins* → **Zurückziehen**. Das wirkt sofort, auch für eine laufende Sitzung. 2. **Protokoll (alle)** des Workspace prüfen: angelegte oder gelöschte Projekte, neue Keys. Keys, die in der fraglichen Zeit angelegt wurden, zurückziehen. 3. Neues Token für die Person ausstellen. --- ## `ADMIN_TOKEN` ist in falsche Hände geraten Mit dem `ADMIN_TOKEN` kann sich jeder als Plattform-Admin anmelden und kommt an jeden Workspace. ```sh openssl rand -hex 24 # neues ADMIN_TOKEN ``` 1. Neuen Wert im Passwortspeicher ablegen und in der Konfiguration des Containers setzen. 2. Container neu starten. **Alle Sitzungen des Plattform-Admins enden damit sofort**, auch die eines Angreifers, der sich schon angemeldet hat. Jede Admin-Sitzung trägt einen Fingerabdruck des Tokens, mit dem sie entstanden ist, und der Server vergleicht ihn bei jeder Anfrage (seit 2026-10-06, siehe `auth.PlatformSubject`). Teams und Workspace-Admins bleiben angemeldet, MCP-Agenten merken nichts. 3. [Prüfen, was in der fraglichen Zeit geschah](#was-ist-in-der-fraglichen-zeit-geschehen). ## `SESSION_SECRET` ist in falsche Hände geraten Mit dem `SESSION_SECRET` kann jeder gültige Anmelde-Cookies selbst ausstellen, für jeden Zugang. Da der Fingerabdruck des `ADMIN_TOKEN` ebenfalls aus dem `SESSION_SECRET` berechnet wird, schließt das den Plattform-Admin ein, ohne dass das Token je bekannt war. Das ist der schwerste Fall. ```sh openssl rand -hex 32 # neues SESSION_SECRET openssl rand -hex 24 # neues ADMIN_TOKEN, zur Sicherheit gleich mit ``` 1. Beide Werte im Passwortspeicher ersetzen und in der Konfiguration des Containers setzen. 2. Container neu starten. Alle sind danach aus der Weboberfläche abgemeldet und melden sich mit ihrem Key neu an. **MCP-Agenten merken nichts davon**, sie nutzen ihre Keys direkt, nicht die Cookies. 3. [Prüfen, was in der fraglichen Zeit geschah](#was-ist-in-der-fraglichen-zeit-geschehen). ### Was ist in der fraglichen Zeit geschehen? - Anmeldungen des Plattform-Admins stehen **nur im Server-Log**, nicht im Protokoll: `docker logs munin 2>&1 | grep "Anmeldung Plattform-Admin"`. Unbekannte Adressen sind ein Warnsignal. Ein selbst ausgestelltes Cookie (geleaktes `SESSION_SECRET`) hinterlässt diese Zeile allerdings nicht. - In jedem Workspace das **Protokoll (alle)**: neue Projekte, Keys und Workspace-Admins. Die Liste der Workspaces auf unbekannte Einträge prüfen. Was nicht von dir stammt, zurückziehen oder löschen. --- ## Ein Agent dreht durch **Man sieht:** Ein Projekt füllt sich mit Unsinn, oder Agenten melden, dass das Schreibbudget erschöpft ist. Das Schreibbudget (Vorgabe 1.000 Aufrufe je Projekt und Stunde) begrenzt den Schaden bereits. Ein Agent, der in einer Schleife hängt, wird nach spätestens einer Stunde gebremst. 1. **Nutzung** im Projekt zeigt, welcher Key wie viel geschrieben hat. 2. Den Key des Agenten **zurückziehen** (siehe oben) oder das Team bitten, den Agenten zu stoppen. 3. Aufräumen über **Historie** und **Papierkorb**. 4. Braucht ein Projekt dauerhaft mehr: Der Plattform-Admin setzt unter *Projekte → Bearbeiten* eine eigene Obergrenze. --- ## Einträge versehentlich gelöscht oder überschrieben Fast immer ohne Sicherung lösbar: - **Überschrieben:** Eintrag öffnen → **Historie** → frühere Fassung wiederherstellen. Jede Fassung bleibt erhalten. - **Gelöscht:** **Papierkorb** im Projekt, 30 Tage lang. - **Endgültig gelöscht oder älter als 30 Tage im Papierkorb:** nur noch aus einer Sicherung. Für einzelne Einträge reicht oft der Markdown-Export: Datei heraussuchen, als ZIP packen und über **Import** im Projekt wieder einlesen. - **Ganzes Projekt gelöscht:** nur aus einer Sicherung, siehe unten. --- ## Aus einer Sicherung wiederherstellen Der Ablauf ist am 2026-10-06 einmal vollständig durchgespielt worden (Sicherung im laufenden Betrieb, Zurückkopieren, Start). ### Vorher bedenken Eine Sicherung setzt **alles** in der zurückgespielten Datei auf ihren Stand zurück, nicht nur das, was man retten will: - Einträge und Fassungen nach der Sicherung sind weg. - Keys, die nach der Sicherung **angelegt** wurden, gelten nicht mehr. - Keys, die nach der Sicherung **zurückgezogen** wurden, **gelten wieder.** Nach dem Zurückspielen deshalb unter *Zugänge* nachsehen und erneut zurückziehen. Das ist der gefährlichste Nebeneffekt. Wer nur ein paar Einträge braucht, spielt die Sicherung besser in ein **getrenntes Verzeichnis** zurück, startet dort einen zweiten Server auf einem anderen Port, exportiert die Einträge und importiert sie im echten Server. Dann bleibt alles andere unberührt. ### Einen Workspace zurückholen Die Kontroll-Datenbank bleibt dabei, wie sie ist. Die anderen Workspaces merken nichts davon. ```sh # 1. Welche Datei? (ID ↔ Name) sqlite3 /data/control.db "SELECT id, name FROM workspaces;" # 2. Sicherung prüfen, bevor man sich auf sie verlässt sqlite3 //workspaces/.db "PRAGMA integrity_check;" # erwartet: ok # 3. Server stoppen docker stop munin # 4. Die Hilfsdateien der alten Fassung entfernen. Nach einem Absturz liegen # sie noch da, und SQLite würde sonst ihren Inhalt in die zurückgespielte # Datei übernehmen. rm -f /data/workspaces/.db-wal /data/workspaces/.db-shm # 5. Die kaputte oder falsche Datei zur Seite legen, nicht löschen mv /data/workspaces/.db /data/workspaces/.db.vorher # 6. Zurückkopieren, Besitzer richtig setzen cp //workspaces/.db /data/workspaces/ chown 10001:10001 /data/workspaces/.db # 7. Starten und prüfen docker start munin curl -s https:///healthz ``` Danach in der Weboberfläche den Workspace öffnen und **zurückgezogene Keys erneut zurückziehen** (siehe oben). Läuft alles, kann `.db.vorher` weg. ### Alles zurückholen Wie oben, aber mit `control.db` und **allen** Dateien unter `workspaces/`, und mit allen `-wal`/`-shm`-Dateien. Zusätzlich zu den Keys gelten dann auch Workspace-Admins wieder, die nach der Sicherung zurückgezogen wurden. ### Ein gelöschter Workspace Beim Löschen verschwinden die Datei **und** sein Eintrag in der Kontroll-Datenbank. Nur die Datei zurückzukopieren reicht deshalb nicht, der Server kennt den Workspace nicht mehr. Es braucht auch die `control.db` aus derselben Sicherung, und die setzt alles Zentrale zurück: andere Workspaces, Workspace-Admins, die Zuordnung neuer Keys. Das ist eine bewusste Entscheidung. Meist ist der Weg über einen getrennten zweiten Server mit Export und Import der bessere. --- ## Datenbank beschädigt **Man sieht:** `database disk image is malformed` im Log, oder ein Workspace lässt sich nicht öffnen, während andere gehen. Workspace-Dateien werden erst beim ersten Zugriff geöffnet, deshalb kann der Fehler auch erst Stunden nach dem Start auftauchen. ```sh docker stop munin sqlite3 /data/workspaces/.db "PRAGMA integrity_check;" ``` Alles außer `ok` heißt: [aus der Sicherung zurückholen](#einen-workspace-zurückholen). Nicht versuchen, die Datei zu reparieren. Mit der letzten guten Sicherung ist man schneller und sicherer am Ziel. Häufigste Ursache ist eine Datei, die im laufenden Betrieb mit `cp` statt mit `scripts/backup.sh` kopiert und dann zurückgespielt wurde. --- ## Eine neue Fassung einspielen Das Schema der Datenbanken wird beim Start automatisch angepasst (`internal/store/migrations*`). Der Weg zurück auf eine ältere Fassung ist danach nicht garantiert. Deshalb: 1. `scripts/backup.sh` von Hand laufen lassen. 2. Neues Abbild bauen, Container ersetzen. 3. Log auf die Startzeilen prüfen, `/healthz`, einmal in der Weboberfläche suchen und ein MCP-`recall` absetzen. 4. Geht etwas schief: altes Abbild starten **und** die Sicherung aus Schritt 1 zurückspielen. Ein Neustart beendet laufende Anfragen sauber (bis zu 10 Sekunden). Agenten verbinden sich danach von selbst neu. --- ## Regelmäßig | Wann | Was | |---|---| | wöchentlich | Läuft die Sicherung? Ein Blick ins Log des Cronjobs und auf den neuesten Ordner in `BACKUP_DIR`. | | monatlich | Marke *ungenutzt* bei Keys und Workspace-Admins (Übersicht unter *Workspaces*). Vergessene Zugänge zurückziehen. | | vierteljährlich | **Probe der Sicherung:** die neueste Sicherung in ein leeres Verzeichnis kopieren, `PRAGMA integrity_check` für jede Datei, einen zweiten Server mit `DATA_DIR` darauf und anderem `PORT` starten, einmal anmelden und suchen. Eine Sicherung, die nie zurückgespielt wurde, ist nur eine Hoffnung. | | vor jedem Update | Sicherung von Hand, siehe oben | Die Probe der Sicherung ohne Docker, auf einem beliebigen Rechner mit Go und sqlite3: ```sh probe=$(mktemp -d) cp -r //. "$probe/" for f in "$probe"/control.db "$probe"/workspaces/*.db; do echo "$f: $(sqlite3 "$f" 'PRAGMA integrity_check;')" done DATA_DIR="$probe" PORT=18080 SESSION_SECRET=$(openssl rand -hex 32) \ ADMIN_TOKEN=probe-probe-probe-1 go run . # im Browser: http://localhost:18080, Anmeldung mit probe-probe-probe-1 ``` Die Probe darf mit eigenen Geheimnissen laufen. Sie braucht weder die echten noch erreicht sie den echten Server.