# 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.

> 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.

João Rizzon · 2026-10-15 · Infraestrutura web

---

## 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:

```bash
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`:

```bash
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](https://docs.litespeedtech.com/lsws/cp/cpanel/websocket-proxy/) 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 -v` diz a versão; `httpd -M | grep proxy` lista os módulos. Até o 2.4.46 você depende de `proxy_wstunnel_module` com destino `ws://`; do 2.4.47 em diante, `proxy_http_module` com `upgrade=websocket` basta. 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 o `httpd.conf` diretamente. Confirme o caminho correto na documentação do cPanel da versão instalada, porque ele mudou entre versões.
- Se o `.htaccess` do domínio tem alguma regra de rewrite que intercepta o path do WebSocket antes do proxy. Um `RewriteRule` de front controller que joga tudo para `index.php` captura `/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 `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.
- **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.
- **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:

```js
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:

```js
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:

```bash
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:3000` com `curl`. Sem isso, pare aqui.
- Confirme 101 pelo domínio em HTTPS, com `curl -i -N` e os cabeçalhos de upgrade. Compare as duas respostas linha a linha.
- 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.
- 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.
- Cronometre a queda sem tráfego e com tráfego. Só depois decida entre heartbeat e ajuste de timeout.
- 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](https://docs.litespeedtech.com/lsws/cp/cpanel/websocket-proxy/), consultada em 09/10/2026. Os trechos de código deste artigo são exemplos ilustrativos, não parâmetros recomendados pela documentação.

