Corrigir a qualidade das chamadas de vídeo do Nextcloud Talk e a conexão com o servidor TURN.

Os problemas de chamadas do Nextcloud Talk são frequentemente descritos como "má qualidade de vídeo", mas as causas subjacentes não são todas as mesmas. Um usuário pode ter largura de banda suficiente e ainda assim não conseguir se conectar porque um firewall bloqueia o tráfego WebRTC ponto a ponto. Outra chamada pode se conectar com sucesso através do TURN, mas parecer mais lenta porque toda a mídia está sendo retransmitida. Uma reunião maior pode apresentar dificuldades mesmo com um servidor TURN funcionando perfeitamente, porque a implementação ainda está usando a topologia ponto a ponto integrada em vez do Backend de Alto Desempenho.

A abordagem mais útil para solucionar problemas é, portanto, separar conectividade , caminho de mídia e escalabilidade . Em 6 de outubro de 2026, a documentação upstream do Nextcloud Talk ainda descrevia o TURN como alternativa quando a conectividade direta com WebRTC não era possível e recomendava a porta 443 para máxima compatibilidade. Também observava que um servidor TURN ainda poderia ser necessário quando o Backend de Alto Desempenho estivesse em uso. Consulte a documentação oficial do Nextcloud Talk sobre TURN e o guia oficial de configuração do coturn para Talk .

O que você deve corrigir primeiro: a largura de banda, o TURN ou o backend de alto desempenho?

Use o padrão de sintomas para escolher a próxima ação em vez de alterar várias configurações de uma só vez.

Passo 1: identifique se a falha está relacionada à conectividade ou à qualidade da mídia.

Comece com dois testes rápidos. Primeiro, faça uma chamada entre dois clientes em redes simples, como duas conexões de banda larga comuns. Em seguida, repita o teste a partir de uma rede restritiva, como Wi-Fi corporativo, uma VPN ou um ponto de acesso móvel. Se apenas a rede restritiva falhar, o TURN é um forte suspeito. Se ambas as chamadas forem bem-sucedidas, mas a qualidade do vídeo for ruim, colete evidências da rede e do dispositivo antes de alterar a arquitetura de retransmissão.

A sequência de conexão documentada do Nextcloud tenta primeiro a conectividade direta ponto a ponto, usa STUN para descobrir endereços acessíveis e recorre ao TURN quando um caminho direto não pode ser estabelecido. Isso significa que o TURN é principalmente uma alternativa de conectividade , e não um otimizador universal de qualidade de vídeo. Um caminho retransmitido pode ser mais confiável, mas também é mais longo e transfere a largura de banda da mídia para o servidor TURN.

Etapa 2: configurar o coturn para o Nextcloud Talk

Para implantações auto-hospedadas, o coturn é a implementação TURN mais comum documentada pelo Nextcloud. O Nextcloud recomenda autenticação com segredo compartilhado para essa integração. Gere um segredo aleatório forte e use o mesmo valor tanto no coturn quanto nas configurações de administração do Talk.

openssl rand -hex 32

Uma configuração mínima normalmente inclui uma porta de escuta, impressão digital, autenticação por segredo compartilhado, um domínio e restrições de pares. A localização exata do arquivo depende do seu sistema operacional e pacote de software. Uma configuração representativa é:

listening-port=443
fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_RANDOM_SECRET
realm=turn.example.com
total-quota=0
bps-capacity=0
stale-nonce
no-multicast-peers

Versões antigas do coturn podem exigir opções que as versões mais recentes não precisam mais, portanto, não copie uma configuração antiga cegamente. A documentação do coturn no Nextcloud indica explicitamente as diretivas dependentes da versão. Verifique a versão do coturn instalada em relação às instruções atuais do coturn no Nextcloud .

Se o Coturn estiver atrás de um NAT, configure corretamente o mapeamento de endereços públicos para privados. A própria documentação de configuração do Coturn explica o external-ipmapeamento e exige que as portas de retransmissão sejam mapeadas de forma consistente através do NAT. Consulte o exemplo de configuração do Coturn upstream .

UDP, TCP ou TLS: qual você deve habilitar?

Para mídia em tempo real, o UDP geralmente é o protocolo de transporte preferido, pois evita o comportamento de retransmissão do TCP e o bloqueio de cabeçalho de fila. No entanto, algumas redes corporativas e de visitantes bloqueiam o UDP completamente. O TCP ou o TURN sobre TLS podem fornecer uma alternativa viável em redes que permitem apenas tráfego semelhante ao da web.

Para máxima acessibilidade, o Nextcloud recomenda escutar na porta 443 e oferece suporte a TURN/TLS. O uso de ambos turn:melhora turns:a compatibilidade, mas também implica na gestão de certificados e caminhos de transporte adicionais. Se todos os usuários estiverem em redes controladas onde o UDP funciona, uma arquitetura mais simples, com UDP como prioridade, pode ser mais fácil de operar. Se os usuários se conectarem regularmente de hotéis, escritórios de clientes, escritórios com acesso restrito ou VPNs, o fallback para TCP/TLS geralmente compensa a configuração adicional.

Passo 3: abra corretamente as portas de escuta e de retransmissão.

Um erro comum é abrir apenas a porta de escuta TURN. O cliente primeiro contata o coturn em seu servidor de escuta, mas o coturn também aloca endpoints de retransmissão para mídia. As configurações padrão do coturn para upstream usam portas UDP 49152-65535para alocação de retransmissão. Se esse intervalo estiver bloqueado pelo firewall do host, grupo de segurança na nuvem, roteador upstream ou dispositivo NAT, a autenticação pode ser bem-sucedida, mas a mídia ainda falha.

Você pode manter o intervalo de retransmissão padrão ou reduzi-lo deliberadamente com `--relay-range` min-porte `--relay max-port-range`. A escolha é simples: um intervalo amplo é operacionalmente fácil e oferece bastante capacidade de alocação; um intervalo estreito é mais fácil de definir na política de firewall, mas pode se tornar um gargalo de capacidade se muitas retransmissões simultâneas precisarem de portas. Defina um intervalo reduzido com base na simultaneidade esperada, em vez de escolher um número pequeno arbitrário.

Se o host TURN tiver um endereço privado atrás de um roteador, preserve o mapeamento de porta um-para-um para o intervalo de retransmissão selecionado e defina o mapeamento de endereço público no coturn. Se o host tiver um IP público diretamente em sua interface, a etapa de mapeamento NAT é desnecessária.

Passo 4: adicione o servidor TURN no Nextcloud Talk

Abra a área administrativa do Nextcloud e acesse as configurações do Talk. Adicione o servidor TURN usando o host e a porta, sem http://URL https://. A documentação atual do Nextcloud sobre o Talk indica que o esquema TURN é selecionado separadamente, portanto, o campo do servidor deve estar no formato turn.example.com:443` <nome_do_servidor>:<porta>`.

Insira o mesmo segredo compartilhado configurado no coturn e habilite os protocolos que seu servidor realmente aceita. Se você usa TLS, selecione o esquema TURN correspondente e certifique-se de que o certificado corresponda ao nome de host TURN. Você também pode usar seu próprio serviço TURN como servidor STUN, o que simplifica o gerenciamento de hosts, embora manter STUN e TURN separados possa ser útil quando você deseja domínios de falha independentes ou relays geograficamente distribuídos.

Não divulgue o segredo compartilhado em capturas de tela, tickets ou exemplos de configuração públicos. O Nextcloud o utiliza para derivar credenciais TURN temporárias para os clientes.

Etapa 5: teste os candidatos do ICE e, em seguida, teste a partir de uma rede restritiva.

Após salvar a configuração do Talk, utilize a verificação administrativa que verifica se o servidor TURN retorna candidatos ICE utilizáveis. Um resultado positivo comprova que o navegador conseguiu obter candidatos válidos do serviço TURN configurado. Isso não garante que todas as redes de usuários, todos os caminhos de retransmissão e todas as chamadas de grande porte terão um bom desempenho.

Repita uma chamada real de pelo menos uma rede restritiva. Isso é importante porque uma verificação no servidor pode ser bem-sucedida enquanto a rede do usuário ainda bloqueia UDP, resolução de DNS ou um determinado protocolo de transporte. Se o UDP falhar, mas o TCP/TLS na porta 443 funcionar, mantenha o caminho alternativo. Se todos os caminhos falharem, inspecione os logs do firewall, os logs do coturn, o DNS, a validade do certificado, o segredo compartilhado e o mapeamento NAT.

Quando você deve adicionar o Backend de Alto Desempenho?

O TURN e o Backend de Alto Desempenho resolvem problemas diferentes. O TURN retransmite o tráfego quando os clientes não conseguem estabelecer o caminho WebRTC necessário. O Backend de Alto Desempenho altera a forma como a mídia com múltiplos participantes é gerenciada, de modo que cada participante não precise enviar um fluxo separado para todos os outros participantes.

A própria interface Talk do Nextcloud alerta que a execução sem o Backend de Alto Desempenho destina-se apenas a chamadas muito pequenas, geralmente descritas no projeto como tendo entre dois e três participantes. Se o seu problema só ocorre quando o número de participantes aumenta, adicionar o TURN pode permitir que mais clientes sejam alcançados, mas não eliminará a sobrecarga de upload ponto a ponto e de CPU. Consulte os requisitos de sistema do Nextcloud Talk e as orientações do Backend de Alto Desempenho do projeto antes de escalar as chamadas em grupo.

Mesmo com o backend de alto desempenho, mantenha o TURN disponível quando os usuários se conectarem de redes restritivas. O Nextcloud documenta um intervalo de mídia WebRTC padrão 20000-40000para o backend e observa especificamente que um cliente limitado à porta 443 ainda pode exigir que o TURN retransmita pacotes para esse intervalo de backend.

TURN autohospedado vs. TURN gerenciado

Lista de verificação prática para ajuste

• Prefira o WebRTC direto sempre que possível. Geralmente, isso minimiza o custo do retransmissor e a latência.
• Utilize o protocolo TURN para garantir confiabilidade. Considere-o como um caminho alternativo para condições adversas de NAT e firewall.
• Use UDP primeiro e TCP/TLS para compatibilidade. A porta 443 é a opção de ouvinte mais amigável para firewalls, recomendada pelo Nextcloud.
• Abra o intervalo de retransmissão, não apenas o de escuta. Certifique-se de que as regras de firewall e NAT estejam de acordo com a configuração min-portreal max-port.
• Monitore a largura de banda do TURN. Chamadas retransmitidas podem movimentar um volume substancial de tráfego de mídia pelo host TURN, portanto, a capacidade da rede geralmente importa mais do que a CPU.
• Separe os problemas de escala dos problemas de conectividade. Para reuniões maiores, avalie o Backend de Alto Desempenho em vez de forçar mais tráfego através da TURN.
• Valide a partir de redes de usuários reais. Um teste ICE é necessário, mas redes de hotéis, corporativas, VPN e móveis podem se comportar de maneira diferente.

Resumindo

Se o Nextcloud Talk funcionar em algumas redes, mas não em outras, configure um serviço TURN acessível e verifique o listener, o segredo compartilhado, o mapeamento NAT e as portas de retransmissão. Se as chamadas conectarem, mas a qualidade for ruim, primeiro meça a rede do cliente e a carga do endpoint, pois o TURN pode adicionar latência em vez de removê-la. Se o problema aumentar com o número de participantes, a solução arquitetural mais apropriada geralmente é o Backend de Alto Desempenho, mantendo o TURN como caminho de compatibilidade para redes restritas.