Este guia explica como conectar o plugin Voice do Discourse a um servidor de mídia LiveKit. Por padrão, as chamadas de voz funcionam ponto a ponto (peer-to-peer): cada participante envia seu áudio diretamente para todos os outros participantes. Isso funciona muito bem para salas pequenas, mas a largura de banda cresce com o tamanho da sala. Roteando as chamadas através do LiveKit, a taxa de upload de cada participante permanece constante, independentemente do número de pessoas que entram.
Pré-requisitos
Antes de começar, certifique-se de ter:
- Um site do Discourse com o plugin Voice habilitado
- Um servidor LiveKit acessível, com suas credenciais de API. Você pode hospedar o LiveKit por conta própria ou usar uma oferta gerenciada, como o LiveKit Cloud.
- Acesso de administrador ao seu site do Discourse.
Etapa 1 — Habilitar o plugin Voice
O Voice é fornecido junto com o Discourse. Vá em Admin → Settings → Plugins e ative a configuração Voice (voice_enabled).
Etapa 2 — Provisionar um servidor LiveKit e anotar as credenciais
Você precisa de três informações da sua implantação do LiveKit: a URL do WebSocket, a chave da API e o segredo da API.
Esses passos são relativamente diretos com o LiveKit Cloud:
- Crie um projeto no dashboard do LiveKit Cloud.
- Na página Settings → Keys do projeto, revele a API key e o API secret.
- Anote a URL do WebSocket (por exemplo,
wss://my-project.livekit.cloud).
Para instalações do LiveKit auto-hospedadas, consulte a documentação respectiva.
Etapa 3 — Configurar a conexão com o LiveKit no Discourse
Vá em Admin → Plugins → Voice, abra as configurações e preencha a seção do LiveKit:
| Configuração | O que inserir |
|---|---|
voice_livekit_url |
A URL do WebSocket, por exemplo wss://livekit.example.com (ou ws:// para laboratórios HTTP simples). |
voice_livekit_api_key |
A chave da API da Etapa 2. |
voice_livekit_api_secret |
O segredo da API da Etapa 2. |
voice_livekit_room_policy |
Quais salas usam o LiveKit. |
A configuração voice_livekit_room_policy decide como as salas escolhem o transporte:
| Política | Comportamento |
|---|---|
disabled |
Todas as chamadas funcionam ponto a ponto (o padrão). |
per_room |
Criadores/gestores de sala ativam individualmente as salas com a caixa de seleção Use media server (SFU) no formulário da sala. |
all_rooms |
Todas as salas são roteadas através do LiveKit. |
Etapa 5 — Configurações extras opcionais
Essas configurações ajustam finamente a integração:
| Configuração | Propósito |
|---|---|
voice_livekit_room_prefix |
Prefixo de namespace para os nomes das salas no LiveKit. Com vários sites compartilhando um único servidor LiveKit, defina um prefixo único por site. Se vazio, usa o nome do banco de dados do site por padrão. |
voice_livekit_mesh_fallback |
Quando um token do LiveKit não pode ser emitido e a sala está vazia, inicia na malha ponto a ponto em vez de falhar na entrada. Desativado por padrão — a degradação silenciosa pode ocultar uma falha no LiveKit. |
voice_livekit_recording_enabled |
Permite que moderadores da sala gravem chamadas que funcionam no LiveKit. As gravações são produzidas pelo LiveKit Egress e armazenadas no armazenamento da sua implantação do LiveKit (S3, GCS, disco local) — não são enviadas para o Discourse. |
voice_livekit_recording_filepath |
O caminho de arquivo passado ao LiveKit Egress, por exemplo voice/{room_name}-{utc}. Suporta placeholders como {room_name}, {room_id}, {time}, {utc}; a extensão do arquivo é adicionada automaticamente. |
Etapa 6 — Opcional: habilitar webhooks do LiveKit
Webhooks são uma última linha de defesa para reconciliação. Quando a conexão de um participante é interrompida abruptamente ou uma sala termina, os webhooks permitem que o plugin limpe o estado de presença e da sala em segundos, em vez de esperar o TTL do heartbeat expirar. Eles são opcionais — se não puderem ser entregues, as chamadas ainda funcionam, apenas a limpeza leva um pouco mais de tempo.
No servidor LiveKit, adicione o endpoint do webhook (o plugin exibe o trecho exato em seu dashboard de administrador até que o primeiro webhook chegue):
# livekit.yaml
webhook:
api_key: <your-api-key>
urls:
- https://forum.example.com/voice/livekit/webhook
Reinicie o LiveKit. As entregas são autenticadas com o segredo da API — não é necessário configurar um segredo compartilhado adicional.
Etapa 7 — Verificar a integração
Verificar o dashboard de administração do Voice no Discourse
Vá em Admin → Plugins → Voice → Dashboard. Assim que qualquer configuração do LiveKit estiver presente, o dashboard exibirá um cartão de status do servidor de mídia LiveKit com verificações em tempo real:
- status da configuração (quais configurações estão presentes e a política ativa),
- se os tokens de acesso podem ser assinados com o par de chaves,
- se o servidor está acessível e quantas salas estão ativas,
- a última verificação automática de conectividade,
- se os webhooks estão sendo recebidos.
Use Refresh para executar uma sonda sob demanda.
Aqui está uma captura de tela do dashboard do plugin Voice com o LiveKit habilitado:
Verificar o dashboard do LiveKit
Há detalhes sobre as chamadas também no dashboard do LiveKit. Aqui está um exemplo:
