Questa guida illustra come connettere il plugin Voice di Discourse a un server multimediale LiveKit. In modo predefinito, le chiamate vocali avviano in modalità peer-to-peer: ogni partecipante invia il proprio audio direttamente a tutti gli altri partecipanti. Questo funziona bene per sale piccole, ma la larghezza di banda aumenta con la dimensione della sala. Instradare le chiamate tramite LiveKit mantiene costante l’upload di ciascun partecipante, indipendentemente dal numero di persone che si uniscono.
Prerequisiti
Prima di iniziare, assicurati di avere:
- Un sito Discourse con il plugin Voice abilitato
- Un server LiveKit raggiungibile, con le relative credenziali API. Puoi auto-ospitare LiveKit o utilizzare un servizio gestito come LiveKit Cloud.
- Accesso amministrativo al tuo sito Discourse.
Passaggio 1 — Abilita il plugin Voice
Voice è incluso in bundle con Discourse. Vai su Amministrazione → Impostazioni → Plugin e
attiva l’impostazione Voice (voice_enabled).
Passaggio 2 — Configura un server LiveKit e annota le credenziali
Hai bisogno di tre elementi dal tuo deployment LiveKit: l’URL WebSocket, la
chiave API e il segreto API.
Questi passaggi sono relativamente semplici con LiveKit Cloud:
- Crea un progetto nella dashboard di LiveKit Cloud.
- Dalla pagina Impostazioni → Chiavi del progetto, rivela la chiave API e il
segreto API. - Annota l’URL WebSocket (ad esempio
wss://my-project.livekit.cloud).
Per installazioni LiveKit auto-ospitate, consulta la rispettiva documentazione.
Passaggio 3 — Configura la connessione LiveKit in Discourse
Vai su Amministrazione → Plugin → Voice, apri le impostazioni e compila la sezione LiveKit:
| Impostazione | Cosa inserire |
|---|---|
voice_livekit_url |
L’URL WebSocket, ad esempio wss://livekit.example.com (o ws:// per lab HTTP plain). |
voice_livekit_api_key |
La chiave API dal Passaggio 2. |
voice_livekit_api_secret |
Il segreto API dal Passaggio 2. |
voice_livekit_room_policy |
Quali sale utilizzano LiveKit. |
L’impostazione voice_livekit_room_policy determina come le sale selezionano il trasporto:
| Politica | Comportamento |
|---|---|
disabled |
Tutte le chiamate avviano in modalità peer-to-peer (predefinito). |
per_room |
I creatori/manager della sala abilitano individualmente le sale con la casella Usa server multimediale (SFU) nel modulo della sala. |
all_rooms |
Ogni sala è instradata tramite LiveKit. |
Passaggio 5 — Impostazioni aggiuntive facoltative
Queste impostazioni regolano finemente l’integrazione:
| Impostazione | Scopo |
|---|---|
voice_livekit_room_prefix |
Prefisso di namespace per i nomi delle sale su LiveKit. Con più siti che condividono un unico server LiveKit, imposta un prefisso univoco per ogni sito. Se vuoto, predefinito sul nome del database del sito. |
voice_livekit_mesh_fallback |
Quando non è possibile emettere un token LiveKit e la sala è vuota, avvia sulla mesh peer-to-peer invece di fallire l’ingresso. Disattivato di default — la degradazione silenziosa può nascondere un’interruzione di LiveKit. |
voice_livekit_recording_enabled |
Consente ai moderatori della sala di registrare le chiamate che avviano su LiveKit. Le registrazioni sono prodotte da LiveKit Egress e memorizzate sullo storage del deployment LiveKit (S3, GCS, disco locale) — non vengono caricate su Discourse. |
voice_livekit_recording_filepath |
Il percorso file passato a LiveKit Egress, ad esempio voice/{room_name}-{utc}. Supporta segnaposto come {room_name}, {room_id}, {time}, {utc}; l’estensione del file viene aggiunta automaticamente. |
Passaggio 6 — Facoltativo: abilita i webhook di LiveKit
I webhook sono una rete di sicurezza solo di riconciliazione. Quando la connessione di un partecipante si interrompe
improvvisamente o una sala termina, i webhook consentono al plugin di pulire la presenza e lo stato della sala
entro pochi secondi, invece di aspettare la scadenza del TTL del heartbeat. Sono
facoltativi — se non possono essere consegnati, le chiamate funzionano comunque, la pulizia richiede solo
un po’ più di tempo.
Sul server LiveKit, aggiungi l’endpoint del webhook (il plugin mostra lo snippet esatto
nella sua dashboard di amministrazione fino all’arrivo del primo webhook):
# livekit.yaml
webhook:
api_key: <your-api-key>
urls:
- https://forum.example.com/voice/livekit/webhook
Riavvia LiveKit. Le consegne sono autenticate con il segreto API —
nessun segreto condiviso aggiuntivo da configurare.
Passaggio 7 — Verifica l’integrazione
Controlla la dashboard di amministrazione Voice di Discourse
Vai su Amministrazione → Plugin → Voice → Dashboard. Non appena è presente un’impostazione LiveKit,
la dashboard mostra una scheda di stato Server multimediale LiveKit con
controlli in tempo reale:
- stato della configurazione (quali impostazioni sono presenti e la politica attiva),
- se i token di accesso possono essere firmati con la coppia di chiavi,
- se il server è raggiungibile e quante sale sono attive,
- l’ultimo controllo di connettività automatico,
- se i webhook vengono ricevuti.
Usa Aggiorna per eseguire una sonda su richiesta.
Ecco uno screenshot della dashboard del plugin Voice con LiveKit abilitato:
Controlla la dashboard di LiveKit
Ci sono dettagli sulle chiamate anche nella dashboard di LiveKit. Ecco un esempio:
