WEBRTC_TURN_SETUP

Este guia configura um servidor TURN com coturn para chamadas de áudio/vídeo do chat privado. O tráfego de mídia pode ser retransmitido pelo TURN quando a conexão direta (STUN) não funciona — por exemplo, usuários em redes/ISPs diferentes ou CGNAT.

Os frontends (Vue e Next) obtêm a lista de servidores ICE em GET /chat-privado/webrtc/ice-servers, que lê as variáveis abaixo do backend.

---

Variáveis no .env do backend

Adicione (ou edite) estas chaves no arquivo .env do backend (não no frontend):

Variável	Obrigatória	Descrição
WEBRTC_TURN_URLS	Não*	Uma ou mais URLs TURN, separadas por vírgula. Ex.: turn:turn.seudominio.com:3478 ou turn:203.0.113.10:3478
WEBRTC_TURN_USERNAME	Não*	Usuário configurado no coturn (user=... antes dos dois pontos)
WEBRTC_TURN_CREDENTIAL	Não*	Senha configurada no coturn (depois dos dois pontos em user=usuario:senha)

* As três devem existir juntas para o TURN ser incluído na resposta da API. Se alguma faltar, o backend continua respondendo só com STUN públicos (sem relay).

Opcional:

Variável	Descrição
WEBRTC_ICE_SERVERS_JSON	JSON com array extra de objetos no formato RTCIceServer (mesclado após os STUN padrão). Use só se souber o que está fazendo.

Exemplos de .env (backend)

Só TURN em UDP/TCP 3478 (sem TLS):

WEBRTC_TURN_URLS=turn:turn.exemplo.com.br:3478
WEBRTC_TURN_USERNAME=zpro_turn
WEBRTC_TURN_CREDENTIAL=uma_senha_longa_e_aleatoria

TURN + TURNS (TLS na 5349), se o coturn estiver com certificado:

WEBRTC_TURN_URLS=turn:turn.exemplo.com.br:3478,turns:turn.exemplo.com.br:5349
WEBRTC_TURN_USERNAME=zpro_turn
WEBRTC_TURN_CREDENTIAL=uma_senha_longa_e_aleatoria

Importante: use o mesmo usuário e senha no coturn (user=zpro_turn:uma_senha_longa_e_aleatoria) e reinicie o processo Node (PM2/systemd) após alterar o .env.

---

1. Instalar coturn no Ubuntu

sudo apt update
sudo apt install -y coturn

Ativar o serviço:

sudo sed -i 's/^#\?TURNSERVER_ENABLED=.*/TURNSERVER_ENABLED=1/' /etc/default/coturn
sudo systemctl enable coturn

---

2. Configurar /etc/turnserver.conf

Edite o arquivo (ex.: sudo nano /etc/turnserver.conf) e ajuste ao seu ambiente.

Exemplo mínimo (credenciais estáticas — alinhado ao .env acima)

Substitua:

• SEU_IP_PUBLICO — IP público da VPS (ou par IP_PUBLICO/IP_INTERNO se a VM estiver atrás de 1:1 NAT).

• exemplo.com.br — domínio ou nome lógico (campo realm).

• zpro_turn e uma_senha_longa_e_aleatoria — iguais a WEBRTC_TURN_USERNAME e WEBRTC_TURN_CREDENTIAL.

listening-port=3478
tls-listening-port=5349

external-ip=SEU_IP_PUBLICO

realm=exemplo.com.br
server-name=turn.exemplo.com.br

fingerprint
lt-cred-mech
user=zpro_turn:uma_senha_longa_e_aleatoria

# Opcional: mais log para depuração
# verbose

Se a VPS não tiver IP público direto na interface (NAT do provedor):

external-ip=IP_VISTO_NA_INTERNET/IP_DA_INTERFACE_DA_VPS

TLS (turns: na porta 5349)

1

Obtenha certificado

Obtenha certificado (ex.: Let’s Encrypt).

2

No mesmo arquivo

cert=/etc/letsencrypt/live/turn.exemplo.com.br/fullchain.pem
pkey=/etc/letsencrypt/live/turn.exemplo.com.br/privkey.pem

3

No .env

Inclua turns:turn.exemplo.com.br:5349 em WEBRTC_TURN_URLS (como no exemplo acima).

Reinicie o coturn:

sudo systemctl restart coturn
sudo systemctl status coturn

---

3. Firewall (UFW na VPS)

sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 5349/tcp
sudo ufw reload

No painel da nuvem (security group / firewall), abra as mesmas portas.

---

4. DNS (recomendado)

Aponte um registro A (ou AAAA) para o subdomínio usado no TURN, ex.:

• turn.exemplo.com.br → IP público da VPS

Use esse nome em WEBRTC_TURN_URLS em vez do IP, se possível (facilita certificado TLS e mudanças de IP).

---

5. Verificação rápida

• Página Trickle ICE: adicione um servidor TURN com o mesmo host, porta, usuário e senha do coturn e confira se aparecem candidatos relay.

• Nos logs do coturn (journalctl -u coturn -f) devem aparecer alocações quando houver chamada usando relay.

---

6. Reiniciar o backend

Após editar o .env do backend:

# Exemplo com PM2
pm2 restart all

---

Referência no código

• Montagem da lista ICE: backend/src/utils/webrtcIceServersZPRO.ts

• Rota HTTP: GET /chat-privado/webrtc/ice-servers (autenticada)

• Frontends consomem essa rota e montam o RTCPeerConnection

---

Segurança

• Use senha forte e exclusiva para o usuário TURN.

• Em produção, prefira TLS (turns:) quando possível.

• Credenciais ficam somente no servidor (backend .env); não coloque senha TURN em variáveis NEXT_PUBLIC_* no frontend.

Para credenciais temporárias por usuário (shared secret / REST do coturn), seria necessário estender o backend — este guia cobre o modo usuário/senha estático, que já é suportado pelas variáveis WEBRTC_TURN_*.