A sua nova aplicação roda bem no servidor, em 127.0.0.1:3000, e o Apache já responde nas portas 80 e 443 pelo site da empresa. Você quer que app.example.com chegue à aplicação, com o certificado que o Apache já gerencia. Você adiciona uma linha ProxyPass, abre a página, clica em "Entrar" e o navegador pula para http://127.0.0.1:3000/login, um endereço que só funciona dentro do próprio servidor. Esse estado meio funcional é o primeiro resultado mais comum de um proxy reverso no Apache.
Este guia monta a configuração em ordem: módulos, um VirtualHost mínimo, redirecionamentos e nomes de host, cabeçalhos repassados, HTTPS, WebSocket, timeouts, balanceamento de carga, testes e as mensagens de erro que você vai encontrar. As diretivas vêm da documentação do Apache HTTP Server 2.4; o comportamento do backend foi testado com uma aplicação Node de dez linhas em 127.0.0.1.
O que faz um proxy reverso no Apache?
Um proxy reverso (reverse proxy) no Apache recebe as requisições do seu site, repassa essas requisições a um servidor de aplicação que fica atrás dele e devolve a resposta desse servidor como se o próprio Apache a tivesse gerado. O visitante só fala com o Apache; a aplicação em 127.0.0.1 ou em uma rede privada fica fora do alcance externo. A diferença em relação ao proxy que um cliente configura para si mesmo está explicada em Forward proxy e reverse proxy: qual é a diferença?.
Veja o que acontece com uma requisição:
- O Apache escolhe o VirtualHost cujo
ServerNamecorresponde ao cabeçalhoHostenviado pelo navegador. - Ele verifica as regras
ProxyPassem ordem; vence o primeiro caminho que corresponder. - O
mod_proxy_httpabre uma conexão com o backend e encaminha a requisição, acrescentandoX-Forwarded-For,X-Forwarded-HosteX-Forwarded-Server. - O backend responde. Se a resposta for um redirecionamento, o
ProxyPassReversetroca o endereço do backend no cabeçalhoLocationpelo endereço público. - O Apache envia a resposta ao visitante, com o próprio certificado TLS se o VirtualHost usar HTTPS.
De quais módulos do Apache você precisa?
Você precisa do mod_proxy, que fornece a mecânica do proxy, e de um módulo de protocolo para o tipo de backend com que o Apache conversa. A documentação do mod_proxy lista todos; os que uma configuração típica usa estão abaixo.
| Módulo | O que faz | Você precisa para |
|---|---|---|
mod_proxy | Funções básicas de proxy | Qualquer configuração |
mod_proxy_http | Fala HTTP com o backend | Aplicações em Node, Python, Java ou Go |
mod_headers | Diretiva RequestHeader | X-Forwarded-Proto |
mod_ssl | TLS para o site | HTTPS |
mod_proxy_balancer | Grupos de backends | Balanceamento de carga |
mod_lbmethod_byrequests | Um método de distribuição | Balanceamento de carga |
mod_proxy_wstunnel | Túnel WebSocket | Apache anterior ao 2.4.47 |
mod_proxy_fcgi | Backends FastCGI | PHP-FPM |
Debian e Ubuntu guardam os módulos em /etc/apache2/mods-available e os ativam com a2enmod, que cria links em mods-enabled. O guia do Ubuntu Server sobre módulos do Apache usa os mesmos comandos:
sudo a2enmod proxy proxy_http headers ssl
sudo systemctl restart apache2Sistemas da família RHEL carregam os módulos com linhas LoadModule em /etc/httpd/conf.modules.d/. No pacote do CentOS Stream 9, o 00-proxy.conf já carrega mod_proxy, mod_proxy_http, mod_proxy_balancer, os métodos de distribuição e mod_proxy_wstunnel, enquanto o mod_ssl é um pacote separado (sudo dnf install mod_ssl). Se faltar um módulo, a linha fica assim:
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.soConfira o que está carregado com apachectl -M | grep -i proxy. No Windows, as mesmas linhas LoadModule ficam em conf\httpd.conf.
Como escrever uma configuração mínima de ProxyPass?
Coloque uma linha ProxyPass e uma linha ProxyPassReverse correspondente dentro do VirtualHost que responde pelo nome público. Esta é a menor configuração útil para a aplicação da introdução:
<VirtualHost *:80>
ServerName app.example.com
ProxyRequests Off
ProxyPreserveHost On
# servido pelo próprio Apache, não pela aplicação
ProxyPass "/.well-known/acme-challenge/" "!"
ProxyPass "/" "http://127.0.0.1:3000/"
ProxyPassReverse "/" "http://127.0.0.1:3000/"
ErrorLog ${APACHE_LOG_DIR}/app-error.log
CustomLog ${APACHE_LOG_DIR}/app-access.log combined
</VirtualHost>${APACHE_LOG_DIR} é definido no Debian e no Ubuntu; em sistemas da família RHEL, escreva logs/app-error.log no lugar. Salve o arquivo como /etc/apache2/sites-available/app.conf e ative com sudo a2ensite app, ou coloque em /etc/httpd/conf.d/app.conf.
Três regras decidem se as linhas funcionam como esperado:
- As barras precisam combinar. Se o primeiro argumento termina em
/, o segundo também precisa terminar, e vice-versa. Uma diferença gera URLs do backend com uma barra a menos ou duplicada, o que costuma aparecer como um 404 da aplicação. - A ordem importa. O Apache verifica as regras
ProxyPassna ordem em que aparecem e usa a primeira correspondência, então coloque os caminhos mais longos primeiro:/api/antes de/. - Exclusões vêm primeiro. Uma regra
!deixa um caminho fora do proxy, aqui a pasta usada na validação do certificado, e só funciona acima da regra geral.
Em um subcaminho, ProxyPass "/app/" "http://127.0.0.1:3000/" envia /app/orders ao backend como /orders; a aplicação então precisa gerar links que comecem com /app/, normalmente por uma configuração do tipo "base path".
O que ProxyPassReverse e ProxyPreserveHost mudam?
O ProxyPassReverse corrige redirecionamentos, e o ProxyPreserveHost decide qual nome de host o backend enxerga. Os dois importam porque as aplicações montam URLs absolutas a partir do cabeçalho Host da requisição que recebem.
A nossa aplicação de teste em 127.0.0.1:3901 fez exatamente isso. Ao receber um pedido de /admin com o próprio endereço no cabeçalho Host, ela respondeu 302 com Location: http://127.0.0.1:3901/login; com a mesma requisição e Host: www.example.com, respondeu Location: http://www.example.com/login. Por padrão o Apache envia o host do destino do ProxyPass, que é o primeiro caso: o link de login quebrado da introdução.
O ProxyPassReverse resolve isso reescrevendo os cabeçalhos Location, Content-Location e URI dos redirecionamentos: um valor que começa com a URL do backend volta a ser o seu endereço público. Links dentro do HTML ou do JavaScript não são alterados. Para cookies, ProxyPassReverseCookieDomain e ProxyPassReverseCookiePath reescrevem o domínio e o caminho em Set-Cookie.
O ProxyPreserveHost On repassa ao backend o cabeçalho Host original do visitante, e assim a aplicação já monta as URLs corretas desde o início. A documentação do Apache diz que, em geral, essa opção deve ficar desligada, porque um backend que só conhece o próprio nome interno pode recusar o nome público. Ligue a opção quando a aplicação verificar o nome de host, gerar links absolutos ou atender vários domínios.
Como o backend descobre o IP e o protocolo do visitante?
Por cabeçalhos de requisição que o Apache acrescenta na entrada. No modo de proxy reverso, o mod_proxy_http adiciona três deles sozinho, controlados por ProxyAddHeaders, que vem ligado por padrão:
X-Forwarded-For: o endereço IP do visitante.X-Forwarded-Host: o cabeçalhoHostque o visitante enviou.X-Forwarded-Server: o nome de host do próprio proxy.
O X-Forwarded-Proto, que informa à aplicação se o visitante usou HTTPS, não é adicionado automaticamente. Defina esse cabeçalho com mod_headers no VirtualHost de HTTPS: RequestHeader set X-Forwarded-Proto "https". A ação set substitui qualquer valor que o cliente tenha enviado.
Trate esses cabeçalhos como pistas, não como prova. Se uma requisição já traz X-Forwarded-For, o Apache acrescenta o seu valor ao final, e o backend recebe uma lista separada por vírgulas. A nossa aplicação de teste recebeu 198.51.100.9, 203.0.113.7 exatamente como digitamos no curl e não tinha como saber qual entrada um proxy havia adicionado. Vincule a aplicação a 127.0.0.1 para que só o Apache consiga alcançá-la, e configure o framework para confiar nos cabeçalhos repassados apenas por esse proxy.
Como adicionar HTTPS a um proxy reverso no Apache?
Termine o TLS no Apache: um VirtualHost na porta 443 guarda o certificado, descriptografa a requisição e repassa HTTP simples à aplicação na máquina local. A porta 80 então só redireciona:
<VirtualHost *:80>
ServerName app.example.com
Redirect permanent "/" "https://app.example.com/"
</VirtualHost>
<VirtualHost *:443>
ServerName app.example.com
SSLEngine on
SSLCertificateFile /etc/ssl/app.example.com/fullchain.pem
SSLCertificateKeyFile /etc/ssl/app.example.com/privkey.pem
ProxyRequests Off
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
ProxyPass "/" "http://127.0.0.1:3000/"
ProxyPassReverse "/" "http://127.0.0.1:3000/"
</VirtualHost>Os caminhos dos certificados são exemplos; use os arquivos que a sua ferramenta de certificados grava. Desde o Apache 2.4.8, o SSLCertificateFile pode conter os certificados intermediários depois do certificado do servidor, o que substitui o antigo SSLCertificateChainFile. Se a sua ferramenta de certificados valida o domínio por HTTP simples, confira se isso ainda funciona depois de adicionar o redirecionamento; muitas ferramentas acrescentam uma regra própria para a porta 80.
Se o próprio backend fala HTTPS, escreva https:// no ProxyPass e adicione SSLProxyEngine on. O Apache então verifica por padrão o nome no certificado do backend (SSLProxyCheckPeerName), e uma divergência termina em 502. Como o mod_proxy_http precisa ler o caminho, o Apache sempre descriptografa a requisição; ele não repassa intacto o fluxo criptografado do visitante.
Como passar conexões WebSocket pelo proxy?
A partir do Apache 2.4.47, adicione upgrade=websocket à linha ProxyPass que atende o caminho do WebSocket. O mod_proxy_http então encaminha a requisição Upgrade do navegador e transforma a conexão em túnel apenas se o backend responder 101 Switching Protocols:
ProxyPass "/socket/" "http://127.0.0.1:3000/socket/" upgrade=websocket
ProxyPassReverse "/socket/" "http://127.0.0.1:3000/socket/"
ProxyPass "/" "http://127.0.0.1:3000/"
ProxyPassReverse "/" "http://127.0.0.1:3000/"Confira a sua versão com apachectl -v. Na 2.4.46 e anteriores, carregue mod_proxy_wstunnel e aponte o caminho do WebSocket para uma URL ws://: ProxyPass "/socket/" "ws://127.0.0.1:3000/socket/". Nos dois casos, a regra do WebSocket fica acima da regra geral /. O navegador pode continuar usando wss:// enquanto o Apache fala ws simples com a aplicação local, porque o TLS termina no Apache; é isso que as pessoas querem dizer com "WebSocket sobre SSL" no Apache.
Como configurar timeouts em um proxy reverso?
O Apache espera até ProxyTimeout para o backend enviar dados, e o ProxyTimeout assume por padrão o Timeout geral do servidor, que é de 60 segundos. Por isso, uma página de relatório cujo backend trabalha dois minutos antes de enviar o primeiro byte falha ao completar um minuto, a menos que você aumente um dos dois valores:
ProxyTimeout 180
ProxyPass "/reports/" "http://127.0.0.1:3000/reports/" timeout=300 connectiontimeout=5
ProxyPass "/" "http://127.0.0.1:3000/"O ProxyTimeout vale para o VirtualHost inteiro. O parâmetro timeout= substitui esse valor para um único destino, e connectiontimeout= limita a espera pela própria conexão, de modo que um backend fora do ar falha em segundos. O retry= define por quanto tempo um backend que falhou fica fora de uso (60 segundos por padrão). Aumente os timeouts só onde for preciso, porque cada requisição em espera ocupa um worker do Apache.
Como fazer balanceamento de carga com mod_proxy_balancer?
Defina um grupo balancer:// com um BalancerMember por backend e aponte o ProxyPass para o grupo. Além de mod_proxy e mod_proxy_http, isso exige mod_proxy_balancer e pelo menos um módulo de método, como mod_lbmethod_byrequests:
<Proxy "balancer://appcluster">
BalancerMember "http://10.0.0.11:3000" route=a
BalancerMember "http://10.0.0.12:3000" route=b
BalancerMember "http://10.0.0.13:3000" status=+H
ProxySet lbmethod=byrequests stickysession=ROUTEID
</Proxy>
Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
ProxyPass "/" "balancer://appcluster/"
ProxyPassReverse "/" "balancer://appcluster/"byrequests divide as requisições por igual, bytraffic equilibra pelo volume de bytes e bybusyness escolhe o membro menos ocupado. status=+H transforma o terceiro servidor em reserva ativa (hot standby), que só recebe tráfego quando os outros falham. Os valores route e o cookie ROUTEID (definido com mod_headers) mantêm cada visitante no mesmo membro, o que importa quando a aplicação guarda as sessões na memória.
O guia de proxy reverso do Apache também cobre verificações de integridade (health checks) com mod_proxy_hcheck e a página de status balancer-manager, que precisa ficar restrita a endereços confiáveis, por exemplo com Require host localhost.
A comparação entre os métodos está em O que é balanceamento de carga? Algoritmos e tipos.
Por que ProxyRequests precisa ficar em Off?
Porque ProxyRequests On transforma o Apache em um forward proxy que busca qualquer URL para quem pedir, e o ProxyPass funciona sem essa opção; além disso, Off já é o padrão. Um forward proxy aberto em um servidor público acaba encontrado e usado por estranhos para spam e ataques. Essas requisições saem pelo endereço IP do seu servidor, que então vai parar em listas de bloqueio e em denúncias de abuso enviadas ao seu provedor de hospedagem. Escreva ProxyRequests Off de forma explícita, para que uma linha copiada de um tutorial antigo não ligue a opção sem você perceber; um forward proxy para as suas próprias máquinas precisa de um bloco <Proxy "*"> com Require ip.
Como testar a configuração?
Teste em três etapas: a sintaxe, o backend sozinho e o caminho pelo Apache. Execute isto no servidor:
sudo apachectl configtest # checa a sintaxe; aponta arquivo e linha do erro
sudo apachectl -S # qual VirtualHost responde por qual nome e porta
curl -I http://127.0.0.1:3000/ # só o backend
sudo systemctl reload apache2 # família RHEL: sudo systemctl reload httpd
curl -I https://app.example.com/ # o caminho completo pelo ApacheO curl -I mostra só a linha de status e os cabeçalhos. Se o backend responde diretamente mas não pelo Apache, o problema está nas linhas do proxy; se nenhum dos dois responde, inicie a aplicação primeiro. Em um redirecionamento, o cabeçalho Location precisa mostrar o nome público, nunca 127.0.0.1. Quando algo falhar, leia o log de erros: /var/log/apache2/error.log no Debian e no Ubuntu, /var/log/httpd/error_log em sistemas da família RHEL, ou o arquivo que o VirtualHost indicar.
É o mesmo tipo de proxy que os serviços de proxy vendem?
Não. Um proxy reverso fica na frente do seu servidor e fala por ele; os proxies que um provedor vende ficam na frente do seu cliente. Os Proxies HTTPS são forward proxies: o seu navegador, script ou servidor envia a eles as requisições de saída, e o site de destino vê o endereço IP do proxy.
Os dois podem se encontrar no mesmo sistema, por exemplo quando a aplicação atrás do seu Apache chama a API de um parceiro que aceita um único endereço na lista de permissões. Os Proxies de datacenter dão a esse tráfego de saída um endereço IPv4 dedicado e fixo; os produtos por IP vêm por padrão com uma restrição de sites de destino, então confira se o host do parceiro está acessível pelos seus IPs.
Onde os proxies reversos do Apache aparecem
O caso clássico é um servidor de aplicação que não deve ficar exposto diretamente à internet: uma aplicação Node, Python ou Go em uma porta local, ou uma aplicação Java no Tomcat na porta 8080, com o Apache cuidando dos certificados e dos logs. Servidores que já rodam o Apache para outros sites ganham uma linha ProxyPass em vez de um segundo servidor web. As equipes também usam esse recurso para reunir várias aplicações sob um único domínio, para rodar PHP via PHP-FPM com mod_proxy_fcgi e para manter no ar uma aplicação legada atrás de configurações TLS atuais.
Erros comuns de proxy reverso no Apache
A maioria dos problemas deixa uma linha clara no log de erros:
Invalid command 'ProxyPass', perhaps misspelled or defined by a module not included in the server configuration: omod_proxynão está carregado. Ative o módulo e rode oconfigtestde novo.- 503 Service Unavailable com
AH00957: … attempt to connect to 127.0.0.1:3000 … failedeAH01114: HTTP: failed to make connection to backend: não há nada escutando no endereço do backend. Inicie a aplicação ou corrija a porta. Em seguida, o Apache deixa esse backend fora de uso durante o período deretry=(60 segundos por padrão) e registraAH00940 … disabled connection, então o 503 pode continuar por até um minuto depois da correção. - 502 Bad Gateway com
Error reading from remote server: o backend aceitou a conexão, mas a fechou ou ficou em silêncio além do timeout. Confira o log da própria aplicação e depois as configurações de timeout. Todas as causas desse status estão reunidas em Erro 502 Bad Gateway: o que significa e como resolver. - 502 depois de mudar o backend para
https://: faltaSSLProxyEngine, ou o certificado do backend não corresponde ao nome dele. - Redirecionamentos para
127.0.0.1ou para o host interno: faltaProxyPassReverse, a URL dele difere do destino doProxyPass, ou a aplicação precisa deProxyPreserveHost On. - O navegador acusa redirecionamentos demais: a aplicação recebe HTTP simples do Apache e redireciona para HTTPS sem parar. Envie
X-Forwarded-Proto "https"e configure o framework para confiar nesse cabeçalho. - 404 inesperados da aplicação: a barra final não combina entre os dois argumentos do
ProxyPass, ou existe um subcaminho que a aplicação não conhece. - A conexão WebSocket falha ou fecha na hora: falta
upgrade=websocket, a regra do WebSocket está abaixo da regra/, ou o servidor roda uma versão anterior à 2.4.47 semmod_proxy_wstunnel.
Guia de decisão
| Necessidade | Recomendação |
|---|---|
| Publicar uma aplicação em um domínio | ProxyPass + ProxyPassReverse no VirtualHost dela |
| A aplicação gera links absolutos | ProxyPreserveHost On |
| A aplicação precisa saber do HTTPS | RequestHeader set X-Forwarded-Proto "https" |
| HTTPS para os visitantes | VirtualHost na porta 443 com SSLEngine on |
| O backend fala HTTPS | Destino https:// + SSLProxyEngine on |
| WebSocket no Apache 2.4.47 ou mais novo | upgrade=websocket |
| WebSocket em um Apache mais antigo | mod_proxy_wstunnel + ws:// |
| Páginas lentas estouram o timeout | timeout= nesse caminho, ou ProxyTimeout |
| Vários servidores de aplicação | balancer:// com mod_proxy_balancer |
| Manter um caminho no próprio Apache | ProxyPass "/path/" "!" acima da regra principal |
Perguntas frequentes
Qual é a diferença entre ProxyPass e ProxyPassReverse?
O ProxyPass envia ao backend as requisições de um caminho; o ProxyPassReverse reescreve o endereço do backend nos cabeçalhos de redirecionamento na volta. Use os dois com os mesmos argumentos, ou os redirecionamentos da aplicação vão mandar os visitantes para um endereço que eles não conseguem acessar.
Preciso de ProxyRequests On para um proxy reverso?
Não. O ProxyRequests só controla o modo de forward proxy, e o ProxyPass funciona com ele desligado, que é o padrão. Ligar essa opção sem regras de acesso rígidas cria um proxy aberto que qualquer pessoa pode usar.
Como colocar vários domínios ou aplicações atrás de um proxy reverso no Apache?
Dê a cada domínio o próprio VirtualHost, com o próprio ServerName e as próprias linhas ProxyPass, ou divida um domínio por caminho com várias regras ProxyPass, o caminho mais longo primeiro. O apachectl -S mostra qual VirtualHost responde por qual nome.
Como passar WebSocket sobre SSL pelo Apache?
Termine o TLS no VirtualHost da porta 443 como de costume e adicione upgrade=websocket à linha ProxyPass do caminho do socket. O navegador se conecta com wss://, e o Apache fala WebSocket simples com o backend local.
Como aumentar o timeout do proxy reverso no Apache?
Defina ProxyTimeout no VirtualHost, ou adicione timeout= a uma única linha ProxyPass para mudar só aquele caminho. Os dois valores são em segundos e, sem eles, o Apache usa o Timeout do servidor, de 60 segundos.
Dá para rodar um proxy reverso no Apache no Windows?
Sim. As diretivas são as mesmas; você ativa mod_proxy e mod_proxy_http removendo o # das linhas LoadModule correspondentes em conf\httpd.conf. O projeto Apache publica só o código-fonte, então a versão para Windows vem de uma distribuição de terceiros.
Em resumo
Um proxy reverso no Apache precisa de mod_proxy com mod_proxy_http e de um VirtualHost com linhas ProxyPass e ProxyPassReverse que combinem; ProxyPreserveHost e X-Forwarded-Proto permitem que a aplicação monte URLs corretas. Termine o HTTPS na porta 443, adicione upgrade=websocket para os sockets, aumente timeout= só onde as páginas forem lentas e use balancer:// para vários backends. Mantenha ProxyRequests Off, rode apachectl configtest antes de cada recarga e leia o log de erros antes de mudar qualquer outra coisa.




