Dieser Leitfaden beschreibt, wie man das Voice-Plugin von Discourse mit einem LiveKit-Mediaserver verbindet. Standardmäßig laufen Sprachanrufe Peer-to-Peer: Jeder Teilnehmer sendet sein Audio direkt an alle anderen Teilnehmer. Das funktioniert hervorragend für kleine Räume, aber der Bandbreitenbedarf steigt mit der Raumgröße. Die Weiterleitung der Anrufe über LiveKit hält den Upload jedes Teilnehmers konstant, unabhängig davon, wie viele Personen beitreten.
Voraussetzungen
Stelle sicher, dass du vor Beginn Folgendes hast:
- Eine Discourse-Instanz, auf der das Voice-Plugin aktiviert ist
- Einen erreichbaren LiveKit-Server mit seinen API-Zugangsdaten. Du kannst LiveKit selbst hosten oder ein Managed-Angebot wie LiveKit Cloud nutzen.
- Administrationsrechte auf deiner Discourse-Instanz.
Schritt 1 – Voice-Plugin aktivieren
Voice wird mit Discourse ausgeliefert. Gehe zu Admin → Einstellungen → Plugins und
aktiviere die Einstellung Voice (voice_enabled).
Schritt 2 – LiveKit-Server bereitstellen und Zugangsdaten notieren
Du benötigst drei Dinge aus deiner LiveKit-Installation: die WebSocket-URL, den
API-Schlüssel und das API-Geheimnis.
Diese Schritte sind mit LiveKit Cloud relativ unkompliziert:
- Erstelle ein Projekt im LiveKit Cloud-Dashboard.
- Zeige auf der Seite Einstellungen → Schlüssel des Projekts den API-Schlüssel und das
API-Geheimnis an. - Notiere die WebSocket-URL (z. B.
wss://my-project.livekit.cloud).
Für selbst gehostete LiveKit-Installationen siehe bitte die jeweilige Dokumentation.
Schritt 3 – LiveKit-Verbindung in Discourse konfigurieren
Gehe zu Admin → Plugins → Voice, öffne die Einstellungen und fülle den LiveKit-Bereich aus:
| Einstellung | Was einzutragen ist |
|---|---|
voice_livekit_url |
Die WebSocket-URL, z. B. wss://livekit.example.com (oder ws:// für Labs mit reinem HTTP). |
voice_livekit_api_key |
Der API-Schlüssel aus Schritt 2. |
voice_livekit_api_secret |
Das API-Geheimnis aus Schritt 2. |
voice_livekit_room_policy |
Welche Räume LiveKit verwenden. |
Die Einstellung voice_livekit_room_policy bestimmt, wie Räume einen Transport auswählen:
| Richtlinie | Verhalten |
|---|---|
disabled |
Alle Anrufe laufen Peer-to-Peer (Standard). |
per_room |
Raum-Ersteller/-Verwalter aktivieren Räume individuell über ein Häkchen bei Mediaserver (SFU) verwenden im Raumformular. |
all_rooms |
Jeder Raum wird über LiveKit weitergeleitet. |
Schritt 5 – Optionale zusätzliche Einstellungen
Mit diesen Einstellungen lässt sich die Integration feinjustieren:
| Einstellung | Zweck |
|---|---|
voice_livekit_room_prefix |
Namensraum-Präfix für Raumnamen auf LiveKit. Bei mehreren Instanzen, die einen LiveKit-Server teilen, ein einzigartiges Präfix pro Instanz setzen. Leer bedeutet Standardmäßig der Datenbankname der Instanz. |
voice_livekit_mesh_fallback |
Wenn kein LiveKit-Token ausgestellt werden kann und der Raum leer ist, Start auf dem Peer-to-Peer-Mesh statt einer fehlgeschlagenen Teilnahme. Standardmäßig deaktiviert – stille Degradation kann einen LiveKit-Ausfall verbergen. |
voice_livekit_recording_enabled |
Erlaubt Raum-Moderatoren, Anrufe aufzunehmen, die auf LiveKit laufen. Aufnahmen werden von LiveKit Egress erstellt und im Speicher deiner LiveKit-Installation (S3, GCS, lokale Festplatte) gespeichert – nicht auf Discourse hochgeladen. |
voice_livekit_recording_filepath |
Der Dateipfad, der an LiveKit Egress übergeben wird, z. B. voice/{room_name}-{utc}. Unterstützt Platzhalter wie {room_name}, {room_id}, {time}, {utc}; die Dateierweiterung wird automatisch hinzugefügt. |
Schritt 6 – Optional: LiveKit-Webhooks aktivieren
Webhooks dienen als reine Rekonkordierungs-Sicherheitsmaßnahme. Wenn die Verbindung eines Teilnehmers abrupt abbricht oder ein Raum endet, ermöglichen Webhooks dem Plugin, Präsenz- und Raumstatus innerhalb von Sekunden aufzuräumen, anstatt auf das Ablaufen der Heartbeat-TTL zu warten. Sie sind optional – wenn sie nicht zugestellt werden können, funktionieren Anrufe weiterhin, der Aufräumprozess dauert nur etwas länger.
Füge auf dem LiveKit-Server den Webhook-Endpunkt hinzu (das Plugin zeigt das genaue Snippet auf seinem Admin-Dashboard an, bis der erste Webhook eingeht):
# livekit.yaml
webhook:
api_key: <your-api-key>
urls:
- https://forum.example.com/voice/livekit/webhook
Starte LiveKit neu. Zustellungen werden mit dem API-Geheimnis authentifiziert –
es muss kein zusätzlicher gemeinsamer Schlüssel konfiguriert werden.
Schritt 7 – Integration überprüfen
Discourse Voice Admin-Dashboard prüfen
Gehe zu Admin → Plugins → Voice → Dashboard. Sobald eine LiveKit-Einstellung
vorhanden ist, zeigt das Dashboard eine LiveKit Mediaserver-Statuskarte mit
Live-Prüfungen an:
- Konfigurationsstatus (welche Einstellungen vorhanden sind und die aktive Richtlinie),
- ob Zugriffstokens mit dem Schlüsselpaar signiert werden können,
- ob der Server erreichbar ist und wie viele Räume aktiv sind,
- die letzte automatische Verbindungsprüfung,
- ob Webhooks empfangen werden.
Verwende Aktualisieren, um eine manuelle Prüfung durchzuführen.
Hier ist ein Screenshot des Voice-Plugin-Dashboards mit aktiviertem LiveKit:
LiveKit-Dashboard prüfen
Auch im LiveKit-Dashboard gibt es Details zu den Anrufen. Hier ist ein Beispiel:
