Runbooks & Fehlerbehebung (Betrieb)

Diese Seite bündelt häufige Betriebsprobleme und verweist auf die passenden Detail-Runbooks. Vorgehen immer: Symptom → erste Prüfung → Detail-Runbook.

Anmeldung schlägt fehl (kein OTP-Code)

Erste Prüfung: SMTP-Status in den Systemeinstellungen (letzte Health-Prüfung). Häufig falscher Host/Port/Absender oder im Server-Betrieb nicht erreichbarer SMTP-Dienst. → OTP-Anmeldung einrichten

Suche liefert keine/schlechte Treffer

Erste Prüfung: aktives Vektor-Backend. Ohne Qdrant/sqlite-vec läuft BM25 (geringere Trefferqualität). Reindex nach Restore/Import abwarten. → Qdrant einrichten · RAG & Suche

PII wird nicht pseudonymisiert

Erste Prüfung: Presidio-Health. Bei Ausfall erfolgt keine Pseudonymisierung (kein lokaler Ersatz). → Presidio einrichten

Modell/MCP antwortet nicht

Erste Prüfung: API-Schlüssel und Provider-Status. Nach einem Restore/Peer-Abgleich müssen Schlüssel korrekt umgeschlüsselt sein. → LLM-API-Schlüssel · MCP-Server

Health-Probe rot / Container startet neu

Erste Prüfung: /ready und Logs. Eine „ready”-Prüfung (z. B. Datenbank) schlägt fehl. → Monitoring & Health-Checks

Nach Update fehlen Spalten / Startfehler

Ursache meist die Zwei-Stellen-Regel (EF-Migration ohne passenden DbInitializer-Eintrag). Beim Start läuft nur DbInitializer.InitializeAsync. → Updates & Versionswechsel

Wiederherstellung schlägt fehl

Erste Prüfung: Passphrase korrekt? App-Version ≥ Sicherungs-Version? → Backup & Restore

Clients haben abweichende Konfiguration

Erste Prüfung: Diff im Tab Verbindungen; Host erreichbar? → Peer-Sync / Servermodus im Betrieb

Diagnosegrundlagen

• Audit-Protokolle (Wissens-Schreibvorgänge, PII). → Audit-Protokoll (PII)
• Nutzung (Token/Kosten/Latenz) für Auffälligkeiten. → Nutzungsstatistiken
• Telemetrie (OTLP) und Health-Endpunkte für die Infrastruktur. → Monitoring & Health-Checks