Tutoriales de VPS
WebSocket falla en Nginx: WSS, Upgrade, rutas y desconexiones
Localiza fallos de handshake o cortes posteriores, configura WSS y Upgrade y revisa rutas, Origin, autenticación, heartbeat y reconexión.

La web abre, pero chat, terminal remoto o notificaciones siguen esperando. Filtra WS en Network. Una conexión que nunca abre y otra que abre y después se corta requieren comprobaciones diferentes. Anota estado del handshake y tiempo hasta el corte antes de cambiar el proxy.
Se utiliza la cadena habitual HTTP/1.1 Upgrade: navegador → entrada HTTPS/WSS → Nginx → aplicación local. Backend 127.0.0.1:3000 y ruta /ws/ son ejemplos; adapta dominio, puerto y endpoint.
En HTTP/1.1, Upgrade normalmente devuelve 101 Switching Protocols antes de intercambiar tramas; consulta RFC 6455. Un 200 ordinario no demuestra Upgrade.
| Síntoma | Primera comprobación | Próximo paso |
|---|---|---|
| Mixed Content antes del handshake | Página HTTPS con ws:// | Endpoint wss:// correcto |
| 200 o 404 | Inicio, ruta equivocada o reescrita | URL final y proxy_pass |
| 301/302 | Dominio, barra, HTTPS o login | Endpoint final directo |
| 400/426 | Cabeceras Upgrade, versión o requisitos | Logs de proxy y aplicación |
| 401/403 | Sesión, Origin, subprotocolo o WAF | Localizar la capa que rechaza |
| 502 | Backend, dirección o puerto | Acceso desde Nginx |
| 101 y corte tras inactividad | Timeout, heartbeat o gateway anterior | Intervalos y límites |
Relaciona hora y endpoint con los logs. El mismo estado puede venir de distintas capas. Oculta cookies y tokens antes de compartir.
Utiliza wss:// con certificado válido coincidente, no ws:// público. Consulta la guía cliente de MDN. En las herramientas del frontend real puedes 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"));
Es código diagnóstico. Conserva login, subprotocolo y cliente específico requeridos; no pegues claves del backend en el navegador. El constructor WebSocket no permite definir Authorization arbitrario como fetch.
Que funcione el certificado de la web no demuestra DNS, TLS y origen del subdominio WebSocket. Para login o redirecciones, consulta el diagnóstico de bucles.
Upgrade y Connection son cabeceras por salto y deben transmitirse explícitamente; consulta Nginx WebSocket. Coloca map dentro de http {}, fuera de server {}. Reutiliza uno equivalente existente:
map $http_upgrade $ws_connection_upgrade {
default upgrade;
'' close;
}
Integra location en el servidor HTTPS existente, conservando certificados y 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;
}
Utiliza HTTP/1.1 al backend y Connection: close sin Upgrade. No fuerces Connection: upgrade en toda la web. Los 90 segundos son ilustrativos; deben concordar con heartbeat y gateways.
proxy_pass no tiene barra final y conserva /ws/echo como /ws/echo. Añadirla puede sustituir el prefijo, según proxy_pass. Si la aplicación acepta solo /socket, copiar /ws/ no iguala endpoints.
Tras un balanceador que termina TLS, $scheme describe lo recibido por Nginx, no necesariamente el protocolo externo. Transmítelo por la cadena fiable; no confíes en cabeceras públicas autodeclaradas.
Respalda el archivo, confirma su origen efectivo y valida antes de cargar:
sudo nginx -t
sudo systemctl reload nginx
Paneles, Ingress y contenedores pueden generar configuración desde otro lugar; modifica la fuente real.
La petición sin credenciales usa Sec-WebSocket-Key del ejemplo del 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=='
Comprueba 101, Upgrade, Connection y Sec-WebSocket-Accept correcto. El comando observa cinco segundos; un handshake correcto puede acabar con timeout al agotarlos. No uses -L para ocultar redirecciones ni -k para demostrar validez TLS.
Verifica cabeceras, no el protocolo completo. Con el cliente real, envía y recibe un mensaje y comprueba operación después de reconectar.
Socket.IO tiene ruta, versiones, heartbeat y formato propios. Utiliza su cliente y la documentación de proxy; no lo pruebes como cualquier WebSocket nativo.
proxy_read_timeout mide intervalos entre lecturas, no duración total. Un backend silencioso puede provocar cierre; un intervalo repetible ayuda a diagnosticar.
Ping/Pong del protocolo y heartbeat JSON de aplicación son distintos. La API del navegador no envía Ping directamente. El servidor puede enviarlo o el protocolo de aplicación puede pedir respuestas. Tráfico continuo del cliente sin respuesta del backend quizá no reinicie el contador de lectura upstream.
Combina intervalo del heartbeat, espera de respuesta y límite más corto de la cadena. No pongas días para ocultar un backend bloqueado y retener conexiones inútiles. Usa valores reales del framework.
Con Cloudflare, revisa WebSocket y reglas de seguridad. Su documentación advierte de cortes por actualizaciones de infraestructura; el cliente necesita reconexión razonable.
WebSocket nativo no se arregla añadiendo Allow-Origin de fetch. Conserva validación de Origin e identidad. Para HTTP ordinario, utiliza el diagnóstico CORS.
En 403, revisa origen permitido, Cookie de login, subprotocolo y gateways. Compara respuestas sin desactivar autenticación.
1006 señala cierre anormal sin trama de cierre normal; no es un código de negocio enviado en una trama del servidor. Consulta CloseEvent. Revisa último mensaje, reinicio/OOM, proxy y CDN; el código solo no identifica firewall ni Nginx.
Confirma Upgrade, ruta, Origin e identidad. Intercambia mensajes en ambos sentidos. Después prueba inactividad prevista e interrupción/restablecimiento de red para reconexión y sesión.
El artículo original realizó seis pruebas aisladas con Nginx 1.19.6 y backend simulado en loopback: handshake/cabeceras, eco de texto, HTTP ordinario, origen rechazado, ruta y versión incorrectas. HTTP dio 200, rechazo 403, ruta 404 y versión 426. Una trama de texto completó ida y vuelta. No se verificaron TLS, CDN, navegador, inactividad prolongada ni sesiones reales.