blog
Infraestrutura web

Por que o WebSocket não conecta no cPanel (e como provar)

Como mapear a porta 3000 no WebSocket Proxy do LiteSpeed em cPanel, preservar HTTPS e IP real nos cabeçalhos encaminhados, e usar o cronômetro e o stderr.log para saber se quem cortou a conexão foi o proxy ou a sua aplicação.

JR · · 8 min de leitura · 2 tabelas · 5 blocos de código

Resposta curta: em servidor cPanel com LiteSpeed, publique a aplicação da porta 3000 criando uma entrada de WebSocket Proxy no virtual host, com a URI pública (ex.: /ws/) e o Address 127.0.0.1:3000. Se o handshake não retorna 101, é proxy; se retorna 101 e cai depois, é timeout ou a aplicação.

Neste artigo
  1. O handshake é HTTP, a conexão depois não é
  2. Prove que a porta 3000 responde 101 antes de culpar o proxy
  3. LiteSpeed em cPanel: o WebSocket Proxy é um mapeamento explícito de URI e porta
  4. Apache: o upgrade precisa sobreviver ao proxy
  5. Por que a aplicação acha que a conexão é HTTP e vem de 127.0.0.1
  6. Cronometrar a queda separa timeout de ociosidade de crash da aplicação
  7. Como testar cada etapa e como desfazer o que você mudou

O handshake é HTTP, a conexão depois não é

Um WebSocket começa como um GET comum com Upgrade: websocket e Connection: Upgrade. Se o servidor da frente aceitar, responde 101 Switching Protocols e, a partir daí, o que trafega são frames binários numa conexão TCP que fica aberta por minutos ou horas.

Os dois modos de falha são, portanto, diferentes e têm diagnósticos diferentes:

A diferença importa porque o primeiro caso se resolve no servidor web e o segundo quase nunca.

Prove que a porta 3000 responde 101 antes de culpar o proxy

Antes de culpar o proxy, prove que a aplicação responde 101 em 127.0.0.1:3000. Pelo próprio servidor, por SSH:

curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  http://127.0.0.1:3000/ws

O que você quer ver na primeira linha é HTTP/1.1 101 Switching Protocols com Upgrade: websocket e Sec-WebSocket-Accept na resposta. Se vier 200 com HTML, a rota está errada. Se vier 400, a aplicação espera outro path ou outro Origin.

Para testar frames de verdade, websocat é mais honesto que curl:

websocat -v ws://127.0.0.1:3000/ws

Se isso funciona e o acesso externo não, o problema está entre o navegador e a porta 3000.

Isolar o ponto de falha do WebSocketcurl local em 127.0.0.1:3000Resposta é 101 Switching Protocols?Não: corrija rota ou aplicação200 com HTML indica path erradoSim: repita pelo domínio em HTTPSMesmos cabeçalhos de upgradeSem 101 externo: proxy ou .htaccessMapeamento de URI ausenteCom 101 e queda depois: cronometreTimeout ou crash da aplicação
Ordem de isolamento: backend primeiro, proxy depois, queda por último.

LiteSpeed em cPanel: o WebSocket Proxy é um mapeamento explícito de URI e porta

Em servidores cPanel com LiteSpeed Web Server, o proxy de WebSocket não é inferido do Apache: ele é uma configuração própria. A documentação oficial do LiteSpeed para cPanel descreve a adição de uma entrada de WebSocket Proxy no contexto do virtual host, com dois campos:

Campo O que recebe Exemplo (fictício)
URI o caminho público que será encaminhado /ws/
Address o endereço e porta do backend 127.0.0.1:3000

A entrada é configurada pelo WebAdmin console do LiteSpeed (acessível pelo WHM, no plugin do LSWS), no virtual host correspondente ao domínio. Depois de salvar, é preciso aplicar a configuração com um restart gracioso do servidor para que o novo contexto passe a valer.

Dois detalhes que derrubam a maioria das tentativas:

Quando o mapeamento existe, o LiteSpeed cuida do upgrade e mantém o túnel. Você não precisa escrever regra de Connection/Upgrade à mão nesse caminho.

Apache: o upgrade precisa sobreviver ao proxy

Se o servidor web da frente é o Apache do cPanel, o encaminhamento de WebSocket exige que os cabeçalhos de upgrade sejam preservados e que o tráfego vá para um backend ws://. Um ProxyPass para http:// sem upgrade=websocket (ou, em Apache anterior ao 2.4.47, sem mod_proxy_wstunnel e um destino ws://) devolve 200 ou 404 em vez de 101. A partir do 2.4.47, mod_proxy_http trata o upgrade sozinho quando a diretiva traz upgrade=websocket.

O que você precisa verificar antes de escrever qualquer linha:

Na prática, em servidor compartilhado com cPanel você normalmente não tem permissão para carregar módulo nem editar include de virtual host. Vale medir o esforço: se o painel já roda LiteSpeed, o caminho do WebSocket Proxy documentado é o menor. Se não roda, abra um chamado pedindo o mapeamento em vez de gastar horas em .htaccess, porque .htaccess não resolve upgrade de protocolo.

Por que a aplicação acha que a conexão é HTTP e vem de 127.0.0.1

Atrás de um proxy, a aplicação da porta 3000 recebe uma conexão de 127.0.0.1 em texto claro. Se ela decidir qualquer coisa com base nisso, decide errado.

Três consequências concretas:

  1. Cookie Secure some. Se o framework acha que a requisição é HTTP, ele pode recusar enviar cookie marcado como Secure, e a autenticação do socket falha logo após o handshake.
  2. Redirect infinito. Aplicação que força HTTPS vendo esquema http responde 301 para o mesmo endereço. O navegador não segue redirect em handshake de WebSocket, então aparece como falha de conexão.
  3. Rate limit e log por IP viram inúteis. Todo mundo é 127.0.0.1.

O servidor web deve repassar X-Forwarded-For com o IP do cliente e X-Forwarded-Proto com o esquema original, e a aplicação precisa ser configurada para confiar nesses cabeçalhos apenas quando vierem do proxy local. Em Express, isso é app.set('trust proxy', 'loopback'). Em frameworks que usam middleware de proxy reverso, a lista de proxies confiáveis precisa incluir 127.0.0.1. Confiar cegamente em X-Forwarded-For vindo de qualquer origem é falha de segurança: o cliente forja o cabeçalho e contorna seu rate limit.

A página de WebSocket Proxy da documentação LiteSpeed para cPanel descreve apenas os campos URI e Address; ela não especifica quais cabeçalhos de encaminhamento o servidor injeta nesse contexto. Não assuma, meça: antes de ligar qualquer trust proxy, confirme no próprio handshake o que chega ao backend. Um log de uma linha na aplicação, no momento do handshake, elimina a adivinhação:

wss.on('connection', (ws, req) => {
  console.log('conn',
    req.socket.remoteAddress,
    req.headers['x-forwarded-for'],
    req.headers['x-forwarded-proto'],
    req.headers['upgrade']);
});

Se x-forwarded-for e x-forwarded-proto vierem undefined nesse log, o proxy não os injeta nesse caminho e ligar trust proxy não muda nada: o esquema precisa vir de configuração própria (o path só é servido por HTTPS, então fixe https na aplicação) e o IP do cliente não estará disponível para rate limit no socket, só no HTTP normal. Se vierem preenchidos, verifique que req.socket.remoteAddress é 127.0.0.1 antes de confiar no conteúdo deles.

Cronometrar a queda separa timeout de ociosidade de crash da aplicação

Quando a conexão vira 101 e cai depois de um intervalo suspeito e regular, o candidato é timeout de ociosidade. Quando cai em momentos aleatórios, com tráfego ativo, o candidato é a aplicação.

Sintoma observado Hipótese mais provável Onde confirmar
Nunca chega a 101, erro imediato URI não mapeada no proxy ou cabeçalho de upgrade perdido resposta do curl externo, log de acesso do domínio
101 ok, cai sempre perto do mesmo tempo sem tráfego timeout de conexão ociosa no servidor web ou no backend configuração de timeout do servidor web, teste com ping ativo
101 ok, cai sempre perto do mesmo tempo com tráfego timeout absoluto de requisição no proxy mesma configuração, teste enviando dados contínuos
101 ok, queda aleatória, processo reinicia crash ou restart da aplicação stderr.log do Passenger, log do process manager
Queda só para alguns usuários rede do cliente, proxy corporativo, antivírus reproduzir em outra rede

O teste que separa idle timeout (queda sem tráfego) de timeout absoluto de requisição (queda mesmo com tráfego) é simples: abra a conexão e não envie nada. Cronometre a queda. Repita enviando um frame a cada poucos segundos. Se com tráfego a conexão sobrevive e sem tráfego não, é idle timeout, e a correção é ping/pong na aplicação, não aumentar timeout no servidor.

Ping/pong é responsabilidade da aplicação

O protocolo tem frames de ping e pong justamente para manter a conexão viva e detectar peer morto. Um heartbeat no servidor, com intervalo menor que o menor timeout do caminho, resolve idle timeout sem tocar na configuração do servidor web:

const interval = setInterval(() => {
  wss.clients.forEach((ws) => {
    if (ws.isAlive === false) return ws.terminate();
    ws.isAlive = false;
    ws.ping();
  });
}, 30000);

wss.on('connection', (ws) => {
  ws.isAlive = true;
  ws.on('pong', () => { ws.isAlive = true; });
});

O valor de 30 segundos acima é exemplo, não parâmetro documentado. Ajuste para abaixo do timeout real que você mediu com o cronômetro.

O stderr.log do Passenger diz se o corte veio de dentro do processo

Aplicações Node, Python ou Ruby publicadas pelo cPanel costumam rodar sob Passenger. Quando o processo morre, o rastro fica no stderr.log dentro do diretório de logs da aplicação. Acompanhe durante o teste:

tail -f ~/logs/stderr.log

Se a queda do WebSocket coincide com uma stack trace ali, o problema é a aplicação e nenhum ajuste de proxy vai esconder isso. Se o stderr.log fica mudo enquanto o cliente desconecta, o corte veio de fora do processo.

Teste que distingue idle de timeout absolutoAbrir conexão e não enviar nadaCronometre até o fechamentoRepetir enviando frames periódicosCronometre de novoComparar os dois temposSobreviveu com tráfego: idle timeoutHeartbeat abaixo do menor timeoutPing/pong na aplicação
Separa timeout de ociosidade de timeout absoluto sem tocar no servidor web.

Como testar cada etapa e como desfazer o que você mudou

Antes de mexer em qualquer configuração compartilhada, anote como desfazer.

  1. Confirme 101 em 127.0.0.1:3000 com curl. Sem isso, pare aqui.
  2. Confirme 101 pelo domínio em HTTPS, com curl -i -N e os cabeçalhos de upgrade. Compare as duas respostas linha a linha.
  3. Verifique se o .htaccess do domínio não captura o path antes do proxy. Renomeie o arquivo por um minuto para testar, e devolva o nome em seguida.
  4. Cheque o que a aplicação enxerga de X-Forwarded-Proto e X-Forwarded-For no handshake, com o log de uma linha mostrado acima.
  5. Cronometre a queda sem tráfego e com tráfego. Só depois decida entre heartbeat e ajuste de timeout.
  6. Mantenha o tail -f no stderr.log durante todo o teste.

Para reverter um mapeamento de WebSocket Proxy no LiteSpeed, remova a entrada do virtual host no WebAdmin e aplique a configuração novamente; o domínio volta a servir aquele path como HTTP comum. Para reverter uma mudança de include no Apache, remova o arquivo adicionado e reconstrua a configuração do Apache pelo utilitário do cPanel, verificando a sintaxe antes de recarregar. Em servidor com sites de terceiros, uma configuração inválida derruba todos eles, não só o seu.

Fonte de configuração citada: WebSocket Proxy, documentação LiteSpeed para cPanel, consultada em 09/10/2026. Os trechos de código deste artigo são exemplos ilustrativos, não parâmetros recomendados pela documentação.

Referências

  1. Documentação oficial (litespeed) — WebSocket Proxy. Consultado em 2026-10-09.
Leia também