# 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`. Munin läuft entweder mit **SQLite** (Standard, eine Datei je Workspace) oder mit **PostgreSQL** (`DB_DRIVER=postgres`, ein Schema je Workspace). Wo sich die Schritte unterscheiden, steht beides da. Welches gilt, zeigt die Zeile `Speicher:` beim Start. Für die PostgreSQL-Befehle: `$DATABASE_URL` ist dieselbe Adresse wie beim Server, das Passwort kommt aus `PGPASSWORD` oder `~/.pgpass`. --- ## 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 und Suchprotokoll 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 /live` antwortet `ok`, solange der Prozess läuft (`/healthz` ist der alte Name) | | Bereitschaft | `GET /ready` antwortet `ok`, wenn die Datenbank antwortet, sonst `503 nicht bereit`. Der Grund steht im Log (`Bereitschaft: …`) | Mit PostgreSQL: | Was | Wo | |---|---| | Kontroll-Datenbank | Schema `munin_control` in der Datenbank aus `DATABASE_URL` | | Ein Workspace | Schema `munin_ws_` (Bindestrich der ID als `_`). Der Name steht als Kommentar daran und unter *Workspaces* in der Weboberfläche | | Sicherungen | `BACKUP_DIR//control.dump` und `…/workspaces/munin_ws_.dump` | Welcher Workspace hinter einer ID steckt: ```sh # SQLite sqlite3 /data/control.db "SELECT id, name FROM workspaces;" # PostgreSQL: Schema und Name psql "$DATABASE_URL" -c "SELECT nspname, obj_description(oid, 'pg_namespace') FROM pg_namespace WHERE nspname LIKE 'munin%' ORDER BY 1;" ``` --- ## Läuft er? ```sh curl -s https:///live # Prozess läuft? erwartet: ok curl -s https:///ready # Datenbank erreichbar? 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) Speicher: SQLite — Workspaces: /data/workspaces, Kontrolle: /data/control.db Schreibbudget: 1000 Aufrufe je Projekt und Stunde (Vorgabe) ``` Mit PostgreSQL lautet die zweite Zeile etwa `Speicher: PostgreSQL — db.intern:5432/munin (Schemas munin_control, munin_ws_…)`. `/live` prüft nur, ob der Prozess antwortet. `/ready` prüft zusätzlich die Kontroll-Datenbank (unter PostgreSQL also auch, ob der Datenbankserver erreichbar ist), aber nicht jede einzelne Workspace-Datei. Siehe dazu [Datenbank beschädigt](#datenbank-beschädigt) und [PostgreSQL ist weg](#postgresql-ist-weg). Mehr Einzelheiten zeigt dem Plattform-Admin die Seite **System** (`/admin/system`). Ganz oben steht der Kasten **Zustand** mit allem, was zu tun ist: Verbindungen knapp, WAL-Datei zu groß, Export fehlgeschlagen oder überfällig, Sortierung der PostgreSQL-Datenbank falsch, Keys laufen ab oder sind ungenutzt. Darunter die Aktivität der letzten 30 Tage, Bestand und Platz je Workspace, Datenbank, Bereitschaft, offene Verbindungen je Workspace gegen das Budget (mit PostgreSQL), wie oft auf Verbindungen gewartet wurde, Fassung, Schema-Stand und Laufzeit. Der Container-Healthcheck im Dockerfile hängt an `/live`: Fehlt nur die Datenbank, soll der Container nicht neu starten, das hülfe nicht. Ein Load-Balancer oder Monitoring gehört an `/ready`. --- ## Server startet nicht **Man sieht:** Der Container beendet sich sofort, `/live` 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) | Mit PostgreSQL kommen diese hinzu: | Meldung | Ursache | Abhilfe | |---|---|---| | `DB_DRIVER=postgres, aber DATABASE_URL ist nicht gesetzt` | Umgebungsvariable fehlt | setzen, siehe README „Mit PostgreSQL“ | | `PostgreSQL ist noch nicht erreichbar (Versuch …)` und am Ende `PostgreSQL ist nicht erreichbar` | Datenbank läuft nicht, falscher Host/Port, Firewall, falsches Passwort | Die Meldung nennt den Grund. Mit `psql "$DATABASE_URL" -c 'SELECT 1'` vom selben Rechner gegenprüfen | | `zu wenige PostgreSQL-Verbindungen: … max_connections auf mindestens N erhöhen` | `max_connections` reicht nicht für alle Workspaces | Beim Datenbank-Admin `max_connections` auf mindestens N setzen lassen und PostgreSQL neu starten. Munin danach neu starten | | `Schema … konnte nicht angelegt werden: permission denied` | Der Benutzer aus `DATABASE_URL` darf keine Schemas anlegen | `GRANT CONNECT, CREATE ON DATABASE munin TO munin;` (oder ihn zum Eigentümer machen), siehe [Rechte des Datenbankbenutzers](#rechte-des-datenbankbenutzers) | | `Schema … konnte nicht gelöscht werden: must be owner of schema` | Das Schema gehört einem anderen Benutzer, etwa nach einem Zurückspielen als anderer Benutzer | Eigentum übertragen: `ALTER SCHEMA munin_ws_ OWNER TO munin;` (für alles auf einmal `REASSIGN OWNED BY TO munin;`, als Superuser) | | `Warnung: Die Datenbank sortiert nach "…" statt "C"` | Datenbank ohne `LOCALE 'C'` angelegt | Läuft trotzdem, Listen sind nur anders sortiert. Beheben lässt es sich nur durch eine neue Datenbank mit `LOCALE 'C'` und Zurückspielen einer Sicherung | --- ## 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. Mit PostgreSQL betrifft das die Platte des Datenbankservers. PostgreSQL rollt einen Schreibvorgang, der nicht mehr passt, ebenso vollständig zurück. Platz schaffen ist dort Sache des Datenbank-Admins; auf Munins Seite wachsen dann nur noch Sicherungen und Export. --- ## Rechte des Datenbankbenutzers Munin arbeitet mit **einem** Datenbankbenutzer (`DATABASE_URL`) für alles. Er braucht genau zwei Rechte auf der Datenbank, oder er ist ihr Eigentümer: ```sql GRANT CONNECT, CREATE ON DATABASE munin TO munin; ``` | Vorgang | Was in PostgreSQL passiert | Nötiges Recht | |---|---|---| | Verbinden | Anmeldung an der Datenbank | `CONNECT` auf der Datenbank | | Erster Start, Workspace anlegen | `CREATE SCHEMA munin_control` bzw. `munin_ws_` | `CREATE` auf der Datenbank | | Workspace öffnen (Migrationen) | `CREATE TABLE`, `CREATE INDEX` im Schema | Eigentum am Schema — hat er, weil er es angelegt hat | | Normaler Betrieb | `SELECT`, `INSERT`, `UPDATE`, `DELETE` | Eigentum an den Tabellen — ebenso | | Workspace umbenennen | `COMMENT ON SCHEMA …` | Eigentum am Schema | | Workspace löschen | `DROP SCHEMA munin_ws_ CASCADE` | **nur** Eigentum am Schema (oder Superuser). Ein eigenes Löschrecht gibt es in PostgreSQL nicht; auch alle Rechte an allen Tabellen reichen nicht | | Verbindungsbudget prüfen | `SHOW max_connections` | keins | Nicht nötig: Superuser, `CREATEDB`, `CREATEROLE`, Rechte am Schema `public`. **Erprobt am 2026-10-16:** Munin mit `CONNECT, CREATE` auf einer Datenbank, die einem anderen Benutzer gehört — Start, Workspace anlegen, `/ready` ok, die Schemas gehören danach Munins Benutzer. Ein Benutzer mit allen Tabellenrechten, aber ohne Eigentum, kann das Schema nicht löschen (`must be owner of schema`). **Sicherung und Wiederherstellung:** `pg_dump` braucht nur Lesezugriff; `pg_restore` und das Umbenennen eines Schemas (`ALTER SCHEMA … RENAME`) laufen am besten als derselbe Benutzer wie Munin. Dann gehört das zurückgespielte Schema wieder ihm, und er kann es später auch löschen. Wurde als ein anderer Benutzer zurückgespielt: `ALTER SCHEMA munin_ws_ OWNER TO munin;` und `ALTER TABLE … OWNER TO munin;`, einfacher als Superuser `REASSIGN OWNED BY TO munin;`. **Bewusst kein zweiter Benutzer** für die Verwaltung: siehe AUSBAUSTUFEN.md 4.10, „Entscheidung: ein Datenbankbenutzer“. --- ## PostgreSQL ist weg **Man sieht:** `/live` antwortet `ok`, `/ready` aber `503 nicht bereit`. Seiten und MCP-Aufrufe enden mit Fehlern, im Log steht `Bereitschaft: Datenbank antwortet nicht …` (einmal, beim Wechsel) und Meldungen wie `connection refused` oder `the database system is shutting down`. 1. Läuft die Datenbank? `pg_isready -d "$DATABASE_URL"` oder `psql "$DATABASE_URL" -c 'SELECT 1'`. 2. Ist sie wieder da, sollten Anfragen von selbst wieder gehen: Go verwirft abgebrochene Verbindungen und baut neue auf. Im Log steht dann `Bereitschaft: Datenbank antwortet wieder`, und `/ready` meldet `ok`. **Noch nicht erprobt.** Gehen sie nach einer Minute nicht, Munin neu starten (`docker restart munin`). Dabei geht nichts verloren, der Suchindex baut sich beim ersten Zugriff neu auf. Schreibvorgänge, die während des Ausfalls scheiterten, haben nichts geschrieben. Agenten bekommen einen Fehler und versuchen es erneut. --- ## 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** oben bei *Wer* den Namen des Keys wählen, bei Bedarf den Zeitraum (*von*, *bis*) eingrenzen: Was wurde damit getan, von welchen Adressen? Unbekannte Adressen deuten auf Missbrauch hin. Die gefilterte Ansicht hat eine eigene Adresse und lässt sich weitergeben. 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:///ready ``` 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. ### Einen Workspace zurückholen (PostgreSQL) Am 2026-10-16 durchgespielt (Sicherung, Zurückspielen über einen bestehenden Workspace, Start auf einer zurückgespielten Datenbank). Das alte Schema wird nicht gelöscht, sondern umbenannt. Der neue Name beginnt nicht mit `munin_ws_`, damit weder Munin noch `scripts/backup.sh` ihn für einen Workspace halten. ```sh # 1. Welches Schema? (Schema ↔ Name) psql "$DATABASE_URL" -c "SELECT nspname, obj_description(oid, 'pg_namespace') FROM pg_namespace WHERE nspname LIKE 'munin_ws_%';" # 2. Sicherung prüfen: Lässt sie sich lesen? pg_restore --list //workspaces/munin_ws_.dump > /dev/null && echo lesbar # 3. Server stoppen docker stop munin # 4. Das jetzige Schema zur Seite legen, nicht löschen psql "$DATABASE_URL" -c 'ALTER SCHEMA munin_ws_ RENAME TO munin_vorher_ws_;' # 5. Zurückspielen. Legt das Schema samt Namenskommentar wieder an. pg_restore --dbname="$DATABASE_URL" --no-owner //workspaces/munin_ws_.dump # 6. Starten und prüfen docker start munin curl -s https:///ready ``` Danach wie oben **zurückgezogene Keys erneut zurückziehen**. Läuft alles, kann das alte Schema weg: `DROP SCHEMA munin_vorher_ws_ CASCADE;` Fehlen `pg_restore` oder `psql` auf dem Rechner oder sind sie älter als der Server, gehen dieselben Befehle über einen PostgreSQL-Container, z.B. `docker exec -i pg_restore … < datei.dump`. ### Alles zurückholen (PostgreSQL) Am sichersten in eine **neue, leere Datenbank** und dann `DATABASE_URL` darauf umstellen. Die alte bleibt so unberührt, bis klar ist, dass alles stimmt: ```sql CREATE DATABASE munin_neu OWNER munin TEMPLATE template0 LOCALE 'C' ENCODING 'UTF8'; ``` ```sh for f in //control.dump //workspaces/*.dump; do pg_restore --dbname="postgres://munin@:5432/munin_neu" --no-owner "$f" done ``` Dann `DATABASE_URL` auf `munin_neu` ändern und Munin neu starten. Auch hier gelten danach zurückgezogene Keys und Workspace-Admins wieder. ### 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. Mit PostgreSQL gilt dasselbe: Schema **und** `munin_control` müssten zurück. Der bessere Weg: die ganze Sicherung in eine eigene Datenbank zurückspielen (siehe oben), einen zweiten Munin mit `DATABASE_URL` darauf und anderem `PORT` starten, dort den Workspace als ZIP herunterladen und im echten Server in einen neuen Workspace importieren. --- ## 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. Mit PostgreSQL ist eine beschädigte Datenbank Sache des Datenbank-Admins. Betrifft es nur einen Workspace, lässt er sich wie oben einzeln zurückholen. --- ## 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, `/ready`, 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`. | | wöchentlich | Ein Blick auf *System* → *Zustand*. Steht dort „Alles in Ordnung“, ist nichts zu tun. | | monatlich | Marke *ungenutzt* bei Keys und Workspace-Admins (Übersicht unter *Workspaces*, Summe unter *System* → *Zustand*). Vergessene Zugänge zurückziehen. Keys mit *läuft bald ab*: noch gebraucht? Dann rechtzeitig ersetzen. Unter *System* → *Aktivität*: Projekte ganz ohne Aktivität mit dem Team klären. | | vierteljährlich | **Probe der Sicherung:** `scripts/sicherung-pruefen.sh /` (siehe unten). Endet es mit `PROBE BESTANDEN`, ist die Sicherung zurückspielbar. Eine Sicherung, die nie zurückgespielt wurde, ist nur eine Hoffnung. | | vor jedem Update | Sicherung von Hand, siehe oben | ### Probe der Sicherung Ein Befehl, für beide Datenbanken. Das Skript spielt die Sicherung zurück (SQLite: in ein Arbeitsverzeichnis samt `PRAGMA integrity_check`; PostgreSQL: in eine leere Probe-Datenbank), startet Munin darauf mit eigenem Port und eigenen Geheimnissen, wartet auf `/ready`, vergleicht die Zahl der Workspaces mit der Sicherung und räumt auf. Der echte Server wird nicht berührt. ```sh # SQLite (braucht sqlite3 und Go, oder MUNIN_BIN=/pfad/zu/munin) scripts/sicherung-pruefen.sh / # PostgreSQL: einmalig eine leere Probe-Datenbank anlegen … psql "$DATABASE_URL" -c "CREATE DATABASE munin_probe OWNER munin TEMPLATE template0 LOCALE 'C' ENCODING 'UTF8';" # … dann bei jeder Probe DB_DRIVER=postgres PROBE_DATABASE_URL="postgres://munin@:5432/munin_probe" \ scripts/sicherung-pruefen.sh / ``` Ist die Probe-Datenbank nicht leer, bricht das Skript ab, statt etwas zu überschreiben. Das schützt davor, versehentlich die echte Datenbank anzugeben. Am 2026-10-16 ausprobiert: SQLite und PostgreSQL bestanden, eine absichtlich beschädigte SQLite-Sicherung durchgefallen, die echte Datenbank als Probe abgelehnt. Von Hand, falls das Skript nicht zur Hand ist (SQLite, 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 ``` Mit PostgreSQL, in eine eigene Probe-Datenbank auf demselben Server: ```sh psql "$DATABASE_URL" -c "CREATE DATABASE munin_probe OWNER munin TEMPLATE template0 LOCALE 'C' ENCODING 'UTF8';" probe_url="postgres://munin@:5432/munin_probe" for f in //control.dump //workspaces/*.dump; do pg_restore --dbname="$probe_url" --no-owner "$f" done DB_DRIVER=postgres DATABASE_URL="$probe_url" PORT=18080 SESSION_SECRET=$(openssl rand -hex 32) \ ADMIN_TOKEN=probe-probe-probe-1 go run . # danach aufräumen: psql "$DATABASE_URL" -c "DROP DATABASE munin_probe;" ``` Die Probe darf mit eigenen Geheimnissen laufen. Sie braucht weder die echten noch erreicht sie den echten Server.