Fehlerbehebung

Häufige Probleme und wie Sie sie diagnostizieren.

/readyz liefert 503

Das Backend meldet sich als unhealthy. Prüfen Sie, was fehlschlägt:

docker compose ps
docker compose logs backend | tail -50
docker compose exec backend wget -qO- http://localhost:8095/readyz

/readyz prüft Postgres + Redis + LiveKit. Die JSON-Antwort listet auf, welche Abhängigkeit ausgefallen ist. Üblicherweise:

• Postgres ist noch nicht bereit (10–20 s nach docker compose up warten)
• Redis-Passwort stimmt nicht zwischen .env und dem Container überein
• LiveKit-Signaling nicht erreichbar (prüfen, ob die Env-Variable LIVEKIT_HOST auflösbar ist)

LiveKit connection refused / WebSocket schlägt fehl

docker compose logs livekit | tail -30

Zwei häufige Ursachen:

1. API-Key/Secret stimmen nicht überein. infra/livekit.yaml enthält keys: { <KEY>: <SECRET> }, und das Backend liest LIVEKIT_API_KEY / LIVEKIT_API_SECRET aus .env. Sie müssen exakt übereinstimmen. Im Zweifelsfall beide Seiten neu generieren.
2. UDP-Ports blockiert. WebRTC-Medien laufen über UDP 50000–50200 (konfigurierbar in infra/livekit.yaml). Auf einem Host mit Firewall müssen diese offen sein. Der TCP-Fallback nutzt 7881 — langsamer, funktioniert aber auch in restriktiven Netzwerken.

Cookie wird nach dem Login nicht gesetzt

Symptom: Die Login-API liefert 200 OK, aber der Browser springt sofort zurück auf /login. Das Session-Cookie wurde nicht akzeptiert.

Ursachen:

• Die Env-Variable DOMAIN stimmt nicht mit dem aufgerufenen Host überein (Cookie-Domain-Mismatch)
• Sie greifen über HTTP statt HTTPS zu — Secure-Cookies erfordern in modernen Browsern TLS
• Sie befinden sich hinter einem Proxy, der Set-Cookie entfernt — Caddy-Logs prüfen

docker compose logs caddy | grep -i cookie

401 Unauthorized auf geschützten Routen

Access-Tokens haben eine TTL von 15 Minuten. Nach Ablauf erneuert das Studio sie bei der nächsten Anfrage stillschweigend über den opaken Refresh-Token (30 Tage, gleitend). Wenn Sie gehäuft 401-Fehler sehen:

• Refresh-Token ebenfalls abgelaufen → Benutzer muss sich neu anmelden
• Uhrzeitabweichung zwischen Client und Server > 30 s → NTP auf dem Host korrigieren
• Refresh-Token widerrufen (anderswo abgemeldet) → neu anmelden

Postgres-Migration schlägt fehl

docker compose exec backend goose -dir /app/migrations \
  postgres "$DATABASE_URL" status

Falls goose nicht mehr synchron ist (eine Migration wurde manuell angewendet oder ein vorheriger Lauf ist mitten in der Migration abgestürzt), können Sie:

# See the state
goose -dir migrations postgres "$DATABASE_URL" status

# Force to a known version (CAREFUL — does not run the SQL)
goose -dir migrations postgres "$DATABASE_URL" version
goose -dir migrations postgres "$DATABASE_URL" up-by-one

Bei einer komplett beschädigten Entwicklungs-DB: löschen und neu anlegen:

docker compose down postgres
docker volume rm commentary_postgres-data
docker compose up -d postgres backend

Kommentator-Kiosk zeigt „keine Berechtigung” für das Mikrofon

Der Browser hat den Mikrofonzugriff blockiert. Der Kiosk funktioniert nur mit Chrome (nutzt AudioContext.sinkId für das Routing des Ausgabegeräts). In Chrome:

1. Auf das Schloss-Symbol in der Adressleiste klicken
2. Website-Einstellungen → Mikrofon → Zulassen
3. Seite neu laden

Prüfen Sie unter macOS / Windows zusätzlich die Mikrofonberechtigung für Chrome auf Betriebssystemebene.

Caddy erhält kein TLS-Zertifikat

docker compose logs caddy | grep -i acme

Typische Probleme:

• Port 80 blockiert oder bereits von einem anderen Dienst belegt (Caddy benötigt :80 für HTTP-01)
• DNS ist noch nicht propagiert — 5 Minuten warten, dann docker compose restart caddy
• Rate-Limit bei Let’s Encrypt erreicht (5 Zertifikate pro Domain pro Woche) — warten oder vorübergehend den Staging-Endpunkt via acme_ca https://acme-staging-v02.api.letsencrypt.org/directory im Caddyfile verwenden

Immer noch blockiert?

Eröffnen Sie ein Issue mit der Ausgabe von:

docker compose ps
docker compose logs --tail=100 backend caddy livekit

Entfernen Sie alle Secrets, bevor Sie die Ausgabe veröffentlichen.