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.

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
- O handshake é HTTP, a conexão depois não é
- Prove que a porta 3000 responde 101 antes de culpar o proxy
- LiteSpeed em cPanel: o WebSocket Proxy é um mapeamento explícito de URI e porta
- Apache: o upgrade precisa sobreviver ao proxy
- Por que a aplicação acha que a conexão é HTTP e vem de 127.0.0.1
- Cronometrar a queda separa timeout de ociosidade de crash da aplicação
- 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:
- O handshake nunca vira 101. O cliente recebe 200, 400, 404, 500 ou um redirect. O navegador reporta um erro de conexão e o código de fechamento costuma ser 1006 (fechamento anormal, sem frame de close). Isso é quase sempre configuração de proxy: os cabeçalhos de upgrade não chegaram ao backend, ou o contexto da URI não está mapeado.
- O handshake vira 101 e a conexão cai depois. Também aparece como 1006 no console do navegador, o que confunde. Aqui a causa é timeout de conexão ociosa no servidor web, no backend, ou a própria aplicação fechando.
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.
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:
- A URI é um prefixo. Se a aplicação escuta em
/socket.io/, o mapeamento precisa cobrir/socket.io/, não a raiz do domínio. Mapear/costuma quebrar o site HTTP inteiro. - O backend precisa estar de pé antes do teste. Com o processo da porta 3000 parado, o erro que chega ao navegador é indistinguível de erro de configuração.
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:
- Qual a versão do Apache e quais módulos de proxy estão carregados.
httpd -vdiz a versão;httpd -M | grep proxylista os módulos. Até o 2.4.46 você depende deproxy_wstunnel_modulecom destinows://; do 2.4.47 em diante,proxy_http_modulecomupgrade=websocketbasta. Sem nenhum dos dois, não existe encaminhamento de protocolo após o 101. - Se a inclusão de configuração do virtual host está em um arquivo que o cPanel não sobrescreve ao reconstruir o
httpd.conf. Em cPanel isso é feito pelos diretórios de includes do Apache, não editando ohttpd.confdiretamente. Confirme o caminho correto na documentação do cPanel da versão instalada, porque ele mudou entre versões. - Se o
.htaccessdo domínio tem alguma regra de rewrite que intercepta o path do WebSocket antes do proxy. UmRewriteRulede front controller que joga tudo paraindex.phpcaptura/ws/também.
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:
- Cookie
Securesome. Se o framework acha que a requisição é HTTP, ele pode recusar enviar cookie marcado comoSecure, e a autenticação do socket falha logo após o handshake. - Redirect infinito. Aplicação que força HTTPS vendo esquema
httpresponde 301 para o mesmo endereço. O navegador não segue redirect em handshake de WebSocket, então aparece como falha de conexão. - 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.
Como testar cada etapa e como desfazer o que você mudou
Antes de mexer em qualquer configuração compartilhada, anote como desfazer.
- Confirme 101 em
127.0.0.1:3000comcurl. Sem isso, pare aqui. - Confirme 101 pelo domínio em HTTPS, com
curl -i -Ne os cabeçalhos de upgrade. Compare as duas respostas linha a linha. - Verifique se o
.htaccessdo domínio não captura o path antes do proxy. Renomeie o arquivo por um minuto para testar, e devolva o nome em seguida. - Cheque o que a aplicação enxerga de
X-Forwarded-ProtoeX-Forwarded-Forno handshake, com o log de uma linha mostrado acima. - Cronometre a queda sem tráfego e com tráfego. Só depois decida entre heartbeat e ajuste de timeout.
- Mantenha o
tail -fnostderr.logdurante 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
- Documentação oficial (litespeed) — WebSocket Proxy. Consultado em 2026-10-09.