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.

Resposta curta: 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.
Neste artigo
- Quem termina o TLS e quem fala HTTP puro em loopback
- No Apache o ProxyPass vai no VirtualHost, nunca no .htaccess
- No LiteSpeed o proxy é um External App mais rewrite [P]
- Como tirar o 127.0.0.1 do log da aplicação com trust proxy
- 502 e 503 no Apache não querem dizer a mesma coisa
- Medir o custo da camada de proxy com curl -w
- Checklist de seis itens antes de considerar fechado
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.1como 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ãohttps. Qualquer redirecionamento absoluto que ela gere sai comohttp://, 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:
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.
<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
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 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:3000e um nome, por exemploappnode. - Escrever a regra de rewrite que joga o tráfego para esse nome.
A regra, no contexto de rewrite do domínio:
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:
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:
curl -o /dev/null -s -w "@/tmp/fmt.txt" http://127.0.0.1:3000/
Pelo domínio, com TLS:
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:
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 -ltnpmostra a aplicação em127.0.0.1:3000, não em0.0.0.0.curl -I https://dominio/devolve 200, e oLocationde qualquer redirect sai comhttps://.- 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 restartda 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
configtestantes, 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.
Referências
- Documentação oficial (litespeed) — Rewrite to Proxy no LiteSpeed com cPanel | LiteSpeed. Consultado em 2026-10-05.