Betrieb und Beobachtung

Du betreibst den tibi-server als Container. Diese Seite zeigt Startprofile, Gesundheit, Suche, Jobs und typische Störungen. Details zur Datei stehen unter Server-Konfiguration.

Startprofile

Der Starter (docker-compose-local.yml) kennt zwei Profile:

tibi tibi-dev

Profil	Service	Wofür
tibi	tibiserver (Image tibi-server:nova)	Normalbetrieb: fertiges Image, Projekt unter ./ als /data gemountet
tibi-dev	tibiserver-dev (Build aus tibi-server/Dockerfile.air)	Entwicklung am Server: Live-Reload, Server-Code gemountet

Dazu laufen mongo (MongoDB 8) und maildev (Mails auf maildev:25, Web-UI zum Lesen).

Starten und Logs ansehen

docker compose --profile tibi up -d
docker compose logs -f tibiserver

Beim Start loggt der Server die wirksame Konfiguration (using following server config:). Prüfe dort zuerst DB.Dial, DB.Prefix und API.Port.

Gesundheit und Metriken

Signal	Adresse	Was du siehst
Version	GET /api/v1/version	{"version":"…"} — der Server lebt und die Config lädt
Prometheus	GET /metrics	u. a. tibi_request_duration_seconds je Methode, Status, Namespace, Collection
Sentry	nur bei gesetzter sentry.dsn	Fehler + Traces mit Client-IP und Transaktionsname

1. curl http://localhost:8080/api/v1/version — kommt JSON, läuft der Router.
2. curl http://localhost:8080/metrics — kommen tibi_*-Zeilen, läuft die Instrumentierung.
3. Antwortzeiten steigen? In /metrics nach status- und col-Labels filtern.

Audit

audit.enabled: true schreibt System-Änderungen (User, Projekt, Login, Shutdown) mit TTL weg. Vorgabe sind 30 Tage (720h über audit.defaultTTL). Lies sie über GET /api/v1/audit (audit.read-Recht nötig).

Suche und Reload

Die Volltextsuche läuft pro Projekt in einem Worker. Nach Config-Änderungen musst du neu laden:

Endpunkt	Wirkung
POST /api/v1/_/:project/_/admin/reload	Lädt Projekt-Config neu (Recht project.reload)
POST /api/v1/_/:project/_/admin/regenerate-search	Baut Suchindex neu auf (project.regenerate-search)
GET /api/v1/_/:project/_/admin/search-worker/status	Status des Such-Workers
GET /api/v1/_/:project/_/admin/embedding/status	Status der Embedding-Provider/Gruppen (project.regenerate-search; Fehlertexte der Mitglieder sind redigiert)
GET /api/v1/admin/embedding/status	Derselbe Status serverweit (server.shutdown, mit vollen Fehlertexten)

Der Embedding-Status nennt je Gruppe die Referenz und je Mitglied state und breaker:

state	Bedeutung	Vorgehen
live	Mitglied antwortet	—
degraded	Sicherung offen, letzte Aufrufe scheiterten	Log-Zeile des Mitglieds prüfen; COOLDOWN_AFTER_UNHEALTHY und CHECK_INTERVAL steuern die Rückkehr
quarantined	Startprüfung fehlgeschlagen (Vektoren weichen ab, Sparse-Form anders, nicht deterministisch)	Modell/Version/Gewichte der Gegenstelle prüfen; mit CHECK_INTERVAL > 0 kommt sie automatisch zurück, sonst Neustart
offline	Gruppe hat kein verifiziertes Mitglied (oder Config-Fehler)	Warnzeile embedding group … offline im Log; Ursache in MEMBERS/PREFERRED_ORDER/Provider-Config beheben

Ist die Gruppe weg, bleiben neue Dokumente ohne Vektoren liegen (sie werden beim nächsten Schreibvorgang oder per regenerate-search nachgezogen) — Suchanfragen auf solche Sammlungen brechen mit einer Meldung ab, die die Gruppe nennt.

Nach Config-Änderung: Reload plus Suchindex neu aufbauen

curl -X POST http://localhost:8080/api/v1/_/meinprojekt/_/admin/reload \
  -H "X-Admin-Token: $TOKEN"
curl -X POST http://localhost:8080/api/v1/_/meinprojekt/_/admin/regenerate-search \
  -H "X-Admin-Token: $TOKEN"

Backups und Snapshots meldet der Server per Fortschritts-Stream (SSE, text/event-stream). Bricht ein Download ab, hole zuerst die Analyse (backup/analyze-download), dann die Datei neu.

Jobs

Jobs sind geplante Skripte je Projekt (Cron in der Projekt-config.yml, gleiche goja-Laufzeit wie Hooks):

• Sie laufen im JOB_CONTEXT — ohne HTTP-Request, mit fast allen Hook-Paketen.
• Sie laufen unter der Projekt-UID (suexec-Isolation, siehe Sicherheit).
• Schlägt ein Job fehl, steht die Ursache im Server-Log; Quotas und Nutzung landen in der LLM-Nutzungsablage.

Datei-Cleanup

Löschst du ein Dokument mit Datei-Feldern, räumt der Server dessen Upload-Verzeichnis (<uploadPfad>/<docId>/) unter der Projekt-UID weg — kein separater Job, sondern Teil des Löschens:

Auslöser	Wann genau	Bei Fehler
DELETE …/<collection>/<id>	Nach erfolgreichem DB-Löschen, nur bei Sammlungen mit Datei-Feldern	Dokument ist weg; Antwort trägt warning: "Document deleted, but file cleanup partially failed", Details im Server-Log (delete cleanup failed for <ns>/<col>/<id>)
Bulk-Delete	Pro Dokument wie oben	Gleich, pro Dokument
PUT, wenn alle Datei-Referenzen entfernt wurden	Nur wenn danach kein file.src mehr im Dokument steht	400 mit der Fehlerursache — das Dokument-Update schlägt fehl
Hook-Funktionen db.delete / db.deleteMany	Wie Einzel-Delete	Nur Log (db.delete cleanup failed …)

Kein Schalter, kein Kehr-Job

Es gibt keinen Config-Schalter und keinen periodischen Waisen-Lauf: Was beim Löschen nicht wegkommt (z. B. Server-Absturz dazwischen), bleibt liegen. Der Pfad-Schutz (SafeRemoveAll) löscht nur innerhalb des Upload-Verzeichnisses mit Mindest-Tiefe — außerhalb liegende Pfade werden verweigert statt gelöscht. Waisen findest du per Dateisuche im Upload-Pfad (media/ bzw. uploadPath der Sammlung).

Störungen

Bild	Ursache (häufig)	Maßnahme
Start-Panic invalid number in env API_PORT	Port fehlt oder <= 0	API_PORT setzen, siehe Server-Konfiguration
version antwortet nicht	Container down, falscher Port	docker compose ps, Logs prüfen
Login wird immer langsamer	Ratelimit-Backoff nach Fehlversuchen	Warten (Retry-After), Zugangsdaten prüfen
Suche findet nichts Neues	Worker hängt oder Index alt	Worker-Status abfragen, regenerate-search
413 bei Upload	Body-Limit erreicht (Server → Projekt → Collection)	API_UPLOAD_MAX_BODY_SIZE bzw. Collection-Limit erhöhen
warning: Document deleted, but file cleanup …	Upload-Verzeichnis ließ sich nicht entfernen (Rechte, Pfad)	Log-Zeile delete cleanup failed … prüfen, Rest per Dateisuche im Upload-Pfad entfernen
Leere Seite trotz Daten	CORS blockt den Browser	Origins in der Collection-Config prüfen

Begriffe wie Collection, Hook oder Namespace klärt Begriffe. Zum Einrichten siehe Schnellstart.

Verifiziert am d272041 2026-10-17 (tibi-server); Compose-Profile am e3f92eb 2026-10-14 (tibi-svelte-starter). Datei-Cleanup aus internal/filecleanup/cleanup.go und Aufrufern (collection_delete.go, collection_bulk_delete.go, collection_put.go, hook/context_db.go). Embedding-Status aus internal/controller/admin_embedding_status.go und internal/embedding/registry.go (Snapshot/Health-Loop).