# Fazer o domínio abrir a aplicação da porta 3000

A regra de proxy reverso no Apache e no LiteSpeed, com terminação TLS na borda, IP real no log da aplicação, WebSocket e como medir o custo da camada extra com curl -w.

> faça a aplicação escutar em 127.0.0.1:3000 e aponte a borda para ela: ProxyPass no VirtualHost do Apache, ou External App mais rewrite [P] no LiteSpeed. Repasse X-Forwarded-Proto, ative trust proxy na aplicação e leia o status certo: 503 é backend fora do ar, 502 é resposta malformada.

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

---

## Quem termina o TLS e quem fala HTTP puro em loopback

A aplicação em `localhost:3000` (Node, Python/uvicorn, Go, PHP com servidor embutido) não precisa saber nada de certificado. Quem termina o TLS é o servidor web da borda, Apache ou LiteSpeed, que já tem o certificado do domínio instalado pelo painel. Da borda para a aplicação o tráfego volta a ser HTTP simples em loopback.

Isso tem três consequências que aparecem depois, em produção, e que valem configurar agora:

- A aplicação passa a ver `127.0.0.1` como IP do cliente em todo log e em todo rate limit, porque é esse o IP de origem da conexão que chega nela.
- A aplicação passa a ver o esquema `http`, não `https`. Qualquer redirecionamento absoluto que ela gere sai como `http://`, e isso vira loop de redirect quando a borda força HTTPS.
- WebSocket não passa sozinho. Precisa de regra específica para o `Upgrade`.

O bind da aplicação deve ser em loopback, não em `0.0.0.0`. Se a porta 3000 estiver escutando em todas as interfaces, o mundo acessa a aplicação sem passar pela borda, sem TLS e sem as regras de cabeçalho. Verifique com:

```bash
ss -ltnp | grep ':3000'
```

O esperado é `127.0.0.1:3000`. Se aparecer `0.0.0.0:3000` ou `*:3000`, ajuste o host de bind na aplicação (`app.listen(3000, '127.0.0.1')` no Express, `--host 127.0.0.1` no uvicorn).

## No Apache o ProxyPass vai no VirtualHost, nunca no .htaccess

Os módulos necessários são `mod_proxy` e `mod_proxy_http`. Para WebSocket, `mod_proxy_wstunnel` e `mod_rewrite`. Em painel com Apache, o lugar certo de escrever isso é o include de VirtualHost do domínio, não o `.htaccess`: `ProxyPass` é válido em server config, virtual host e em `<Directory>`/`<Location>`, mas não em `.htaccess`, que é justamente o arquivo que o painel costuma deixar na mão do usuário.

```apache
<VirtualHost *:443>
    ServerName app.exemplo.com.br

    ProxyPreserveHost On
    ProxyRequests Off

    # Só a requisição que pede upgrade vai para ws://
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) ws://127.0.0.1:3000/$1 [P,L]

    ProxyPass        / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/

    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-Port  "443"
</VirtualHost>
```

O `X-Forwarded-For` o `mod_proxy_http` já adiciona por conta própria, acrescentando o IP do cliente à lista. O `X-Forwarded-Proto` você precisa setar, porque a borda sabe que a conexão externa era TLS e a aplicação não tem como saber.

`ProxyPreserveHost On` faz o `Host:` original chegar na aplicação. Sem ele, a aplicação recebe `127.0.0.1:3000` no `Host`, o que quebra roteamento por domínio e geração de URL absoluta.

Por que condicionar ao header em vez de mapear o prefixo inteiro: o socket.io (e qualquer cliente que faça fallback) começa a sessão em long-polling, com requisições HTTP comuns em `GET /socket.io/?transport=polling`, e só depois tenta o upgrade. Um `ProxyPass /socket.io/ ws://127.0.0.1:3000/socket.io/` manda essas requisições sem `Upgrade:` para o `mod_proxy_wstunnel`, que não sabe o que fazer com elas: a sessão nunca chega à fase de upgrade. Com o `RewriteCond %{HTTP:Upgrade} =websocket`, só o handshake sai por `ws://`; o polling continua caindo no `ProxyPass /` em `http://127.0.0.1:3000/`.

A ordem continua importando, só que em outro eixo: as regras de `mod_rewrite` em contexto de VirtualHost são avaliadas antes do `ProxyPass`, e o `[P,L]` encerra o processamento na linha do upgrade. Se você preferir não depender dessa precedência, use um caminho dedicado só para o upgrade (por exemplo `/ws/`) e aí o par `ProxyPass`/`ProxyPassReverse` com `ws://` volta a ser seguro, porque nada de polling passa por ele.

### Testar a sintaxe e recarregar sem derrubar conexão

```bash
apachectl configtest && apachectl graceful
```

`graceful` recarrega sem derrubar conexão em andamento. Se o `configtest` reclamar de `ProxyPass` desconhecido, falta carregar o módulo.

## No LiteSpeed o proxy é um External App mais rewrite [P]

No LiteSpeed a lógica é diferente e isso confunde quem vem do Apache. Não existe diretiva `ProxyPass`. O caminho documentado é criar um External Application do tipo **Web Server**, apontando para o endereço da aplicação, e depois reescrever para esse app com uma regra de rewrite. A [documentação oficial do LiteSpeed para cPanel](https://docs.litespeedtech.com/lsws/cp/cpanel/rewrite-proxy/) descreve exatamente esse par: External App mais regra de rewrite com o alvo `http://nome-do-ext-app/`.

O fluxo é:

- Criar o External App do tipo Web Server, com endereço `127.0.0.1:3000` e um nome, por exemplo `appnode`.
- Escrever a regra de rewrite que joga o tráfego para esse nome.

A regra, no contexto de rewrite do domínio:

```apache
RewriteEngine On
RewriteRule ^(.*)$ http://appnode/$1 [P]
```

Esse é o par que a documentação descreve. O `E=Proxy-Host:%{HTTP_HOST}` que circula em exemplos de fórum é acréscimo que não consta da fonte acima: ele define a variável de ambiente usada para montar o `Host:` repassado ao External App, e só faz diferença quando a aplicação roteia por domínio e você vê o `Host` chegar errado. Comece sem ele; se a aplicação gerar URL absoluta com host trocado, acrescente `[P,E=Proxy-Host:%{HTTP_HOST}]` e teste de novo.

O `[P]` é o flag de proxy. O `appnode` do destino não é um hostname de DNS, é o nome do External App. Em cPanel com LiteSpeed, a documentação indica colocar a regra no lugar onde o painel permite rewrite por domínio, para que a configuração sobreviva a uma reconstrução do arquivo de configuração do servidor.

No OpenLiteSpeed a interface muda de nome mas a estrutura é a mesma: External App do tipo Web Server no Virtual Host, depois Rewrite Rule com `[P]`. WebSocket não vem junto: ele exige mapeamento declarado à parte, na seção **Web Socket Proxy** do Virtual Host, com URI e endereço do backend. A documentação citada acima trata só do par External App mais rewrite e não descreve comportamento de upgrade automático, então trate o WebSocket como configuração separada e confirme com um teste de handshake (resposta 101) antes de dar por resolvido.

## Como tirar o 127.0.0.1 do log da aplicação com trust proxy

Mandar o cabeçalho não basta. A aplicação precisa ser instruída a confiar nele, senão continua usando o IP da conexão. Confiar sem critério também é errado: se a aplicação aceita `X-Forwarded-For` de qualquer origem, qualquer cliente forja o próprio IP e passa por cima de rate limit e de bloqueio por país.

A regra prática: confie no cabeçalho apenas quando a conexão vem de loopback.

| Stack | Configuração | Efeito |
|---|---|---||
| Express / Node | `app.set('trust proxy', 'loopback')` | `req.ip` e `req.protocol` passam a refletir o cliente real |
| Flask / Werkzeug | `ProxyFix(app.wsgi_app, x_for=1, x_proto=1)` | reescreve `REMOTE_ADDR` e esquema a partir do último hop |
| Django | `SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')` | `request.is_secure()` passa a retornar verdadeiro |
| Go net/http | ler `r.Header.Get("X-Forwarded-For")` e validar `r.RemoteAddr` como loopback | sem biblioteca, decisão explícita no código |

`'loopback'` no Express e `x_for=1` no ProxyFix não são a mesma regra. O Express com `'loopback'` confia na cadeia enquanto os endereços remotos forem de loopback, quantos hops forem, e toma como cliente o primeiro endereço não confiável da lista. O ProxyFix com `x_for=1` conta hops: ele pega exatamente o último elemento de `X-Forwarded-For`, pressupondo um único proxy na frente. Se houver CDN na frente do servidor, são dois hops e o `x_for` precisa virar 2, enquanto no Express a conta muda para `app.set('trust proxy', N)` ou para a lista de faixas da CDN. Conte os proxies antes de escolher o valor.

Verificação rápida depois de aplicar, com um endpoint temporário que ecoe `req.ip`, ou simplesmente olhando o log de acesso da aplicação depois de um acesso externo. Se continuar `127.0.0.1`, o cabeçalho não está chegando ou o trust não está ativo. Separe os dois casos logando o valor bruto de `X-Forwarded-For`.

## 502 e 503 no Apache não querem dizer a mesma coisa

Essa distinção decide qual log você abre primeiro, e é onde mais se perde tempo.

| Status | O que aconteceu no mod_proxy | Onde olhar |
|---|---|---||
| 503 Service Unavailable | A conexão TCP com `127.0.0.1:3000` foi recusada ou o backend está marcado em erro | A aplicação não está no ar, ou está em outra porta, ou escutando em outra interface |
| 502 Bad Gateway | A conexão abriu, mas a resposta do upstream veio malformada ou foi cortada no meio | Log da aplicação, stack trace, processo morto no meio da resposta |
| 504 Gateway Timeout | O backend aceitou e não respondeu dentro do timeout do proxy | Consulta lenta, loop na aplicação, `ProxyTimeout` curto demais |

Traduzindo: **503 é problema de estar no ar, 502 é problema de o que foi respondido**. Em 503, `ss -ltnp` e o supervisor do processo resolvem. Em 502, o log da aplicação é a primeira parada, porque o Apache cumpriu a parte dele e recebeu lixo.

No `error_log` do Apache a linha costuma trazer o motivo em texto, do tipo conexão recusada para 503. Leia a linha inteira antes de mexer em configuração.

## Medir o custo da camada de proxy com curl -w

Você já pode comparar o tempo com e sem a borda no próprio servidor. Crie o formato uma vez:

```bash
cat > /tmp/fmt.txt <<'EOF'
dns:        %{time_namelookup}
connect:    %{time_connect}
tls:        %{time_appconnect}
ttfb:       %{time_starttransfer}
total:      %{time_total}
http_code:  %{http_code}
EOF
```

Direto na porta interna, de dentro do servidor:

```bash
curl -o /dev/null -s -w "@/tmp/fmt.txt" http://127.0.0.1:3000/
```

Pelo domínio, com TLS:

```bash
curl -o /dev/null -s -w "@/tmp/fmt.txt" https://app.exemplo.com.br/
```

O que cada campo significa na medição do curl: `time_appconnect` só é preenchido quando houve handshake TLS, então ele fica zerado no teste em loopback; `time_starttransfer` é o tempo acumulado desde o início da operação (inclui resolução DNS, connect TCP e handshake TLS) até o primeiro byte da resposta chegar. Todos os campos de tempo do curl são cumulativos a partir do mesmo marco zero, então subtração entre eles é válida: na chamada HTTPS, `time_starttransfer` menos `time_appconnect` isola o tempo de envio da requisição mais processamento na aplicação mais travessia do proxy, já sem o custo de DNS, TCP e handshake.

Rode cada comando ao menos dez vezes e compare a mediana, não uma amostra única. O primeiro acesso carrega cache frio da aplicação e distorce tudo:

```bash
for i in $(seq 1 10); do
  curl -o /dev/null -s -w "%{time_starttransfer}\n" http://127.0.0.1:3000/
done | sort -n
```

Para separar o custo do TLS do custo do proxy, acrescente uma terceira medição em HTTP puro pelo domínio, se o domínio ainda aceitar porta 80 sem redirect. Com as três séries, a conta fica direta: loopback é a aplicação sozinha, HTTP pelo domínio soma a borda, HTTPS soma o handshake.

Não publicamos aqui número de referência para essa comparação, porque o valor depende da aplicação, do número de workers, do que a rota faz e da máquina. O procedimento acima é para você obter o seu, no seu servidor, e comparar com ele mesmo antes e depois de uma mudança de configuração.

## Checklist de seis itens antes de considerar fechado

- `ss -ltnp` mostra a aplicação em `127.0.0.1:3000`, não em `0.0.0.0`.
- `curl -I https://dominio/` devolve 200, e o `Location` de qualquer redirect sai com `https://`.
- O log da aplicação mostra IP público de cliente, não `127.0.0.1`.
- WebSocket conecta: no DevTools, a requisição de upgrade termina em 101, não em 200 nem em 404.
- Um `systemctl restart` da aplicação faz o domínio devolver 503 por alguns segundos, e não 502. Se devolver 502 com a aplicação parada, a regra de proxy está apontando para outro lugar.
- Reinício do servidor web com `configtest` antes, sempre.

Para reverter no Apache, comente o bloco `ProxyPass`/`ProxyPassReverse` e rode `apachectl configtest && apachectl graceful`. No LiteSpeed, desative a regra de rewrite e faça o graceful restart pelo painel de administração; o External App pode ficar criado, ele não tem efeito sem a regra que aponta para ele.

