blog
Infraestrutura web

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.

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

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
  1. Quem termina o TLS e quem fala HTTP puro em loopback
  2. No Apache o ProxyPass vai no VirtualHost, nunca no .htaccess
  3. No LiteSpeed o proxy é um External App mais rewrite [P]
  4. Como tirar o 127.0.0.1 do log da aplicação com trust proxy
  5. 502 e 503 no Apache não querem dizer a mesma coisa
  6. Medir o custo da camada de proxy com curl -w
  7. 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:

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

Caminho da requisição até a porta 3000ClienteHTTPS no domínio públicoBorda Apache ou LiteSpeedTermina TLS, injeta X-Forwarded-ProtoLoopbackHTTP puro em 127.0.0.1:3000AplicaçãoConfia no proxy só em loopback
O certificado vive na borda. A aplicação só precisa escutar em loopback e confiar nos cabeçalhos encaminhados.

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

  1. Criar o External App do tipo Web Server, com endereço 127.0.0.1:3000 e um nome, por exemplo appnode.
  2. 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.

Qual log abrir conforme o status do proxy503 recebidoConexão TCP recusada na portaChecar ss -ltnpProcesso no ar e porta certa502 recebidoResposta malformada ou cortadaAbrir log da aplicaçãoStack trace, processo morto504 recebidoBackend aceitou e não respondeuRever ProxyTimeout e consulta lentaLoop ou query lenta na rota
Qual log abrir primeiro conforme o status devolvido pelo mod_proxy.

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

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

  1. Documentação oficial (litespeed) — Rewrite to Proxy no LiteSpeed com cPanel | LiteSpeed. Consultado em 2026-10-05.
Leia também