Tutoriais de VPS
WebSocket falha no Nginx: WSS, Upgrade, caminhos e desconexões
Localize falhas de handshake ou quedas posteriores, configure WSS e Upgrade e confira caminhos, Origin, autenticação, heartbeat e reconexão.

A página abre, mas chat, terminal remoto ou notificações ficam esperando. Filtre WS em Network. Uma conexão que nunca abre e outra que abre e depois cai exigem verificações diferentes. Anote status do handshake e tempo até a queda antes de alterar o proxy.
O guia usa HTTP/1.1 Upgrade: navegador → entrada HTTPS/WSS → Nginx → aplicação local. Backend 127.0.0.1:3000 e caminho /ws/ são exemplos; adapte domínio, porta e endpoint.
Em HTTP/1.1, Upgrade normalmente retorna 101 Switching Protocols antes de trocar frames; veja RFC 6455. Um 200 comum não comprova Upgrade.
| Sintoma | O que conferir | Próximo passo |
|---|---|---|
| Mixed Content antes do handshake | Página HTTPS usando ws:// | Endpoint wss:// correto |
| 200 ou 404 | Início, rota errada ou reescrita | URL final e proxy_pass |
| 301/302 | Domínio, barra, HTTPS ou login | Endpoint final direto |
| 400/426 | Upgrade, versão ou requisitos | Logs do proxy e aplicação |
| 401/403 | Sessão, Origin, subprotocolo ou WAF | Identificar a camada que rejeita |
| 502 | Backend, endereço ou porta | Acesso a partir do Nginx |
| 101 e queda após inatividade | Timeout, heartbeat ou gateway | Intervalos e limites |
Relacione horário e endpoint aos logs. O mesmo status pode vir de camadas diferentes. Oculte cookies e tokens antes de compartilhar.
Use wss:// com certificado válido e correspondente, não ws:// público. Veja a documentação cliente da MDN. Nas ferramentas do frontend real, você pode observar:
const ws = new WebSocket("wss://ws.example.com/ws/");
ws.addEventListener("open", () => console.log("connected"));
ws.addEventListener("message", event => console.log("received", event.data));
ws.addEventListener("close", event => console.log("closed", event.code, event.wasClean));
ws.addEventListener("error", () => console.log("check Network and server logs"));
É código de diagnóstico. Preserve login, subprotocolo e cliente específico necessários; não cole chaves do backend no navegador. O construtor WebSocket não define Authorization arbitrário como fetch.
O certificado da página não comprova DNS, TLS e origem de outro subdomínio WebSocket. Para login ou ciclos de redirecionamento, veja o diagnóstico.
Upgrade e Connection são cabeçalhos por salto e precisam ser transmitidos explicitamente; veja Nginx WebSocket. Coloque map em http {}, fora de server {}. Reutilize um equivalente existente:
map $http_upgrade $ws_connection_upgrade {
default upgrade;
'' close;
}
Integre location ao servidor HTTPS existente, mantendo certificados e ajustes:
location /ws/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $ws_connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 90s;
}
Usa HTTP/1.1 no backend e Connection: close quando não há Upgrade. Não force Connection: upgrade no site inteiro. Os 90 segundos são ilustrativos e devem acompanhar heartbeat e gateways.
proxy_pass não tem barra final; mantém /ws/echo como /ws/echo. Acrescentá-la pode substituir o prefixo, conforme proxy_pass. Se a aplicação só aceita /socket, copiar /ws/ não faz os endpoints corresponderem.
Após balanceador que termina TLS, $scheme descreve o que Nginx recebeu, não necessariamente o protocolo externo. Transmita pela cadeia confiável; não confie em cabeçalhos públicos autodeclarados.
Faça backup, confirme a origem efetiva e valide antes de carregar:
sudo nginx -t
sudo systemctl reload nginx
Painéis, Ingress e contêineres podem gerar configuração em outro lugar; edite a fonte real.
A requisição sem credenciais usa Sec-WebSocket-Key do exemplo do protocolo:
curl --http1.1 -i --max-time 5 'https://ws.example.com/ws/' \
-H 'Origin: https://app.example.com' \
-H 'Connection: Upgrade' \
-H 'Upgrade: websocket' \
-H 'Sec-WebSocket-Version: 13' \
-H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ=='
Confira 101, Upgrade, Connection e Sec-WebSocket-Accept correto. O comando observa cinco segundos; um handshake bem-sucedido pode terminar com timeout ao esgotá-los. Não use -L para ocultar redirecionamentos nem -k para comprovar certificado.
Isso verifica cabeçalhos, não o protocolo completo. Use o cliente real para enviar e receber uma mensagem e confira a operação após reconectar.
Socket.IO tem caminho, versões, heartbeat e mensagens próprios. Use seu cliente e a documentação do proxy, não um teste arbitrário de WebSocket nativo.
proxy_read_timeout mede intervalos entre leituras, não duração total. Backend silencioso pode causar fechamento; um intervalo repetível ajuda a investigar.
Ping/Pong do protocolo e heartbeat JSON da aplicação são diferentes. A API do navegador não envia Ping diretamente. O servidor pode enviar ou o protocolo da aplicação pode pedir respostas. Tráfego contínuo do cliente sem resposta do backend pode não reiniciar a contagem de leitura upstream.
Combine intervalo do heartbeat, espera da resposta e menor limite da cadeia. Não use dias para esconder backend travado e manter conexões inúteis. Confira os valores reais do framework.
Na Cloudflare, confira WebSocket e regras de segurança. Sua documentação alerta sobre quedas em atualizações de infraestrutura; o cliente precisa de reconexão adequada.
WebSocket nativo não é corrigido adicionando Allow-Origin de fetch. Preserve validação de Origin e identidade. Para HTTP comum, use o diagnóstico CORS.
No 403, confira origem permitida, Cookie de login, subprotocolo e gateways. Compare respostas sem desativar autenticação.
1006 indica fechamento anormal sem frame normal de fechamento. Não é código de negócio enviado pelo servidor em um frame; veja CloseEvent. Confira última mensagem, reinício/OOM, proxy e CDN. O código sozinho não identifica firewall ou Nginx.
Confirme Upgrade, caminho, Origin e identidade. Troque mensagens nos dois sentidos. Depois teste inatividade prevista e interrupção/restabelecimento de rede para reconexão e sessão.
O artigo original fez seis verificações isoladas com Nginx 1.19.6 e backend simulado em loopback: handshake/cabeçalhos, eco de texto, HTTP comum, origem rejeitada, caminho e versão errados. HTTP retornou 200, rejeição 403, caminho 404 e versão 426. Um frame de texto completou ida e volta. Não foram verificados TLS, CDN, navegador, inatividade longa ou sessões reais.