CEIR-OS Bedienungsanleitung - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Fehlerbehebung

Diese Seite beschreibt häufige Probleme beim Betrieb von CEIR-OS und deren Lösungen.

Snowstorm startet nicht

Symptom: Der Container ceir-snowstorm startet wiederholt neu oder bleibt im Status "starting".

Ursache 1: Elasticsearch hat nicht genug Speicher

# Elasticsearch-Logs prüfen
docker logs ceir-elasticsearch 2>&1 | tail -20

Lösung: ES_JAVA_OPTS in der .env anpassen:

ES_JAVA_OPTS="-Xms2g -Xmx2g"

Danach neu starten:

docker compose down
docker compose up -d

Ursache 2: Elasticsearch ist noch nicht healthy

Snowstorm wartet auf den Elasticsearch Health Check. Prüfe:

curl -s http://localhost:9200/_cluster/health | jq .status

Der Status muss green oder yellow sein.

Ursache 3: SNOMED-Import fehlgeschlagen

docker logs ceir-snomed-importer

Falls der Import abgebrochen wurde, lösche die Marker-Datei und starte neu:

docker compose down
docker volume rm ceir-os_sct_files
docker compose up -d

Snowstorm DNS-Auflösung fehlgeschlagen

Symptom: Der Terminology MCP Server kann Snowstorm nicht erreichen. lookup_code für SNOMED CT schlägt fehl, obwohl Snowstorm läuft.

Ursache: Wenn Snowstorm einzeln neu gestartet wird (z.B. docker restart ceir-snowstorm), verliert der Container seinen DNS-Alias im Docker-Netzwerk. Andere Container können snowstorm dann nicht mehr auflösen.

Diagnose:

# Doctor-Service ausführen — prüft DNS und alle Routen
docker compose run --rm doctor

Lösung: Snowstorm und abhängige Services über Docker Compose neu erstellen:

docker compose up -d --force-recreate snowstorm terminology-mcp

Wichtig: docker restart reicht nicht — es muss --force-recreate sein, damit Docker die DNS-Einträge im Netzwerk neu registriert.

SNOMED-Import dauert sehr lange

Der initiale Import kann je nach Paketgröße 10-30 Minuten dauern. Fortschritt prüfen:

docker logs -f ceir-snomed-importer

Während des Imports ist Snowstorm bereits gestartet, aber noch nicht vollständig funktional.

MII OntoServer nicht erreichbar

Symptom: search_across_versions liefert Fehler für ICD-10-GM, OPS oder ATC.

Ursache 1: mTLS-Zertifikate fehlen oder sind ungültig

# Terminology MCP Logs prüfen
docker logs ceir-terminology-mcp 2>&1 | grep -i cert

Prüfe:

• Sind die Zertifikat-Dateien im CERTS_PATH-Verzeichnis vorhanden?
• Ist CERT_PASSPHRASE korrekt gesetzt?
• Sind die Base64-kodierten Werte (falls verwendet) vollständig?

Ursache 2: Netzwerkprobleme

Der MII OntoServer ist ein externer Dienst. Prüfe die Erreichbarkeit:

docker exec ceir-terminology-mcp curl -k https://mii-termserv.de/fhir/metadata

Tools funktionieren nicht in OpenWebUI

Symptom: Das LLM antwortet ohne Tool-Aufrufe, Codes werden geraten.

Ursache 1: Ollama ist direkt verbunden (Bridge umgangen)

Prüfe die OpenWebUI-Konfiguration:

docker inspect ceir-webui | jq '.[0].Config.Env' | grep -i ollama

ENABLE_OLLAMA_API muss false sein. Wenn es true ist, kommuniziert OpenWebUI direkt mit Ollama und umgeht die MCP Bridge.

Lösung: Stelle sicher, dass in der docker-compose.yml:

- ENABLE_OLLAMA_API=false
- ENABLE_OPENAI_API=true
- OPENAI_API_BASE_URL=http://mcp-bridge:8000/v1

Ursache 2: MCP Bridge hat keine Tools entdeckt

curl -s http://localhost:8000/health | jq .

Wenn tools: 0, sind die MCP-Server nicht erreichbar. Prüfe die Logs:

docker logs ceir-mcp-bridge 2>&1 | grep -i discover

Ursache 3: Modell unterstützt kein Tool Calling

Nicht alle Modelle unterstützen Tool Calling zuverlässig. Empfohlene Modelle:

LOINC-Suche liefert keine deutschen Labels

Symptom: search_common_loinc oder get_german_label geben keine deutschen Übersetzungen zurück.

Ursache: LOINC-Daten nicht gemountet

Prüfe:

docker exec ceir-terminology-mcp ls /app/loinc/

Das Verzeichnis muss die LOINC-Distribution enthalten. Prüfe den LOINC_PATH in der .env:

LOINC_PATH=/pfad/zu/Loinc_2.81

Docker-Speicherprobleme

Symptom: Container werden mit "OOMKilled" beendet.

Lösung: Docker-Ressourcen erhöhen (Docker Desktop > Settings > Resources):

Für Elasticsearch spezifisch:

ES_JAVA_OPTS="-Xms1g -Xmx1g"

Port-Konflikte

Symptom: Container startet nicht wegen "port already in use".

Prüfe, welcher Prozess den Port belegt:

lsof -i :8090  # Snowstorm
lsof -i :3000  # Terminology MCP
lsof -i :8000  # MCP Bridge

Lösung: Ändere den Port in der .env:

SNOWSTORM_PORT=9090
TERMINOLOGY_PROXY_PORT=3100
BRIDGE_PORT=8001

Health Checks für alle Services

CEIR-OS enthält einen integrierten Doctor-Service, der alle Services, DNS-Auflösung und funktionale Routen prüft:

docker compose run --rm doctor

Der Doctor führt 20 Checks aus:

Alternativ gibt es das Host-seitige Script ./doctor.sh, das zusätzlich Container-Status und Cross-Service-Konnektivität von außen prüft.

Für einzelne Services:

# Snowstorm
curl -s http://localhost:8090/fhir/metadata | jq .software

# Terminology MCP
curl -s http://localhost:3002/health | jq .

# MCP Bridge
curl -s http://localhost:8000/health | jq .

Vollständiger Neustart

Falls nichts anderes hilft:

# Alle Container stoppen und entfernen
docker compose down

# Optional: Volumes löschen (ACHTUNG: SNOMED-Import muss wiederholt werden!)
docker compose down -v

# Neu starten
docker compose up -d

# Logs beobachten
docker compose logs -f