Proxy reverso nginx: tutorial completo de configuração

Um proxy reverso nginx é um servidor nginx que aceita solicitações de entrada em nome de um ou mais aplicativos de backend, depois encaminha cada solicitação ao backend correto e devolve a resposta ao cliente. Este tutorial oferece a você uma configuração de proxy reverso nginx completa e pronta para copiar: um bloco server completo com proxy_pass e cabeçalhos encaminhados, balanceamento de carga upstream, terminação SSL, suporte a WebSockets, ajuste de buffering e tempos limite, gzip, roteamento baseado em location e correções para os erros 502 e 504 que fazem a maioria das pessoas tropeçar.

No final você terá uma configuração de proxy reverso nginx executável, um modelo mental de como as peças se encaixam e uma visão honesta de onde um proxy reverso nginx deixa de ser a ferramenta certa e um proxy forward ou residencial assume.

A DataImpulse é um provedor de proxy ético que oferece mais de 90 milhões de endereços IP residenciais, móveis e de datacenter em 195 países. Ela usa um modelo de pagamento conforme o uso a partir de 1 dólar por GB com tráfego que não expira, e é usada para web scraping, verificação de anúncios, monitoramento de preços, pesquisa de mercado e gerenciamento de múltiplas contas.

O nginx é um proxy reverso e como um deles funciona?

Sim, o nginx é um dos proxies reversos mais implantados, e o proxy reverso é um recurso de primeira classe em vez de um complemento. Um proxy reverso fica na frente dos seus servidores de backend, aceita conexões de clientes em um nome de host público e roteia cada solicitação para um aplicativo interno que o cliente nunca vê diretamente.

Para manter as partes móveis claras, este guia usa um modelo simples e nomeado. Chame-o de modelo de proxy reverso nginx de 5 camadas, e cada configuração funcional abaixo nada mais é do que essas camadas empilhadas em ordem:

• listen A diretiva listen e server_name decidem quais solicitações este bloco possui (porta 80, porta 443, qual nome de host).
• Roteamento por location. Os blocos location dividem os caminhos de entrada para que /api/, /static/ e / possam ir cada um para um lugar diferente.
• Upstream. O bloco upstream nomeia o conjunto de servidores de backend e o método de balanceamento de carga.
• Cabeçalhos. As linhas proxy_set_header preservam o Host original e o IP do cliente para que o backend veja a solicitação real, e não o nginx.
• TLS. ssl_certificate em listen 443 termina o HTTPS no nginx para que os backends possam falar HTTP puro internamente.

Se você ainda está decidindo entre as duas direções de proxy, nossa explicação sobre proxy reverso versus proxy forward cobre o conceito por completo. Este artigo trata apenas do caso reverso. Para a configuração de saída, do lado do cliente, consulte o guia complementar de proxy forward nginx.

O que você precisa antes de começar?

Você precisa de um servidor Linux com o nginx instalado, pelo menos um aplicativo de backend escutando em uma porta local e, para HTTPS, um certificado TLS. O proxy reverso usa apenas a compilação padrão do nginx, portanto nenhum módulo personalizado ou recompilação é necessário.

Confirme que o nginx está presente e que sua configuração é válida antes de editar qualquer coisa:

nginx -v
sudo nginx -t

O teste nginx -t analisa toda a configuração e relata erros de sintaxe com um arquivo e número de linha. Execute-o após cada alteração neste tutorial, porque o nginx se recusará a recarregar uma configuração quebrada e deixará a antiga em execução. Coloque seus blocos server de proxy reverso em /etc/nginx/conf.d/ ou /etc/nginx/sites-available/ dependendo da sua distribuição, e recarregue com sudo nginx -s reload assim que o teste passar. Tenha também o endereço do backend pronto, por exemplo um aplicativo Node ou Python em 127.0.0.1:3000, já que é para isso que o proxy_pass vai apontar.

Como configurar um proxy reverso nginx passo a passo?

Comece com um único bloco server que escuta na porta 80, encaminha cada solicitação para um backend com proxy_pass e define os cabeçalhos encaminhados. Depois adicione balanceamento de carga, TLS, WebSockets, buffering e gzip. Este primeiro bloco é a configuração mínima funcional de um proxy reverso nginx:

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Essas quatro linhas proxy_set_header não são opcionais. Sem elas o backend vê o nginx como o cliente, registra o IP errado e pode construir URLs de redirecionamento quebradas. Host preserva o nome de host solicitado, X-Real-IP e X-Forwarded-For carregam o endereço real do cliente, e X-Forwarded-Proto informa ao aplicativo se a solicitação original foi HTTP ou HTTPS.

Adicione balanceamento de carga upstream. Para ficar na frente de várias instâncias de backend, defina um bloco upstream e aponte o proxy_pass para o nome dele. O método least_conn envia cada solicitação para a instância com o menor número de conexões ativas:

upstream app_backend {
    least_conn;
    server 10.0.0.11:3000;
    server 10.0.0.12:3000;
    server 10.0.0.13:3000 backup;
}

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

O servidor backup só recebe tráfego quando os servidores primários estão fora do ar. Troque least_conn por ip_hash se você precisar fixar o mesmo cliente ao mesmo backend para sessões persistentes.

Termine o SSL na porta 443. Proxies reversos de produção devem servir HTTPS e redirecionar o HTTP puro. O nginx cuida do TLS para que seus backends possam permanecer em HTTP puro internamente:

server {
    listen 443 ssl;
    server_name app.example.com;

    ssl_certificate     /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name app.example.com;
    return 301 https://$host$request_uri;
}

Dê suporte a WebSockets. As conexões WebSocket começam como HTTP e depois fazem upgrade, então o nginx precisa passar os cabeçalhos Upgrade e Connection e usar HTTP/1.1. Dê aos caminhos em tempo real sua própria location:

location /ws/ {
    proxy_pass http://app_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host       $host;
    proxy_read_timeout 3600s;
}

O longo proxy_read_timeout impede que sockets ociosos sejam fechados no meio da sessão, uma causa comum de conexões ao vivo interrompidas.

Ajuste buffering e tempos limite. Os padrões são conservadores; backends lentos se beneficiam de valores explícitos para que o nginx não feche uma conexão antes que o aplicativo responda:

location / {
    proxy_pass http://app_backend;
    proxy_connect_timeout 5s;
    proxy_send_timeout    60s;
    proxy_read_timeout    60s;
    proxy_buffering       on;
    proxy_buffers         16 16k;
    proxy_buffer_size     32k;
}

Habilite o gzip. Comprimir as respostas encaminhadas reduz a largura de banda para recursos de texto. Coloque isto no bloco http para que se aplique a todo o site:

gzip on;
gzip_types text/plain text/css application/json application/javascript;
gzip_min_length 1024;
gzip_comp_level 5;

Roteie por caminho. Um único proxy reverso pode servir vários serviços fazendo prefixos de location diferentes corresponderem a upstreams diferentes, servindo arquivos estáticos diretamente do disco sem tocar em um backend:

server {
    listen 80;
    server_name example.com;

    location /api/ {
        proxy_pass http://api_backend;
        proxy_set_header Host $host;
    }

    location /static/ {
        root /var/www/assets;
    }

    location / {
        proxy_pass http://web_backend;
        proxy_set_header Host $host;
    }
}

Como verificar se o proxy reverso nginx funciona?

Recarregue o nginx, depois envie uma solicitação para o nome de host público e confirme que a resposta vem do seu backend e não de uma página padrão do nginx. Teste a configuração primeiro para que um erro de digitação não derrube o site:

sudo nginx -t && sudo nginx -s reload
curl -I http://app.example.com

Um 200 ou um redirecionamento esperado nos cabeçalhos de resposta significa que o roteamento funciona. Para provar que o backend está recebendo os cabeçalhos encaminhados, verifique seu log de acesso ou um endpoint de eco e confirme que ele vê o IP real do cliente a partir de X-Forwarded-For, e não 127.0.0.1. Você também pode ignorar o DNS e mirar diretamente no proxy enquanto falsifica o nome de host:

curl -H "Host: app.example.com" http://127.0.0.1

Para HTTPS, execute curl -I https://app.example.com e verifique se o certificado é aceito e se a solicitação não é rebaixada. Se o backend renderizar links ou redirecionamentos com o esquema errado, isso é quase sempre um cabeçalho X-Forwarded-Proto ausente e não uma falha de TLS.

Como solucionar os erros 502 e 504?

Um 502 Bad Gateway significa que o nginx alcançou o upstream mas recebeu uma resposta inválida ou recusada, enquanto um 504 Gateway Timeout significa que o upstream aceitou a conexão mas não respondeu a tempo. Ambos são problemas do upstream, não bugs do nginx, e o log de erros nomeia a causa exata. Observe-o ao vivo enquanto você reproduz a solicitação:

sudo tail -f /var/log/nginx/error.log
# [error] connect() failed (111: Connection refused) while connecting to upstream

Percorra as causas habituais em ordem:

• 502, conexão recusada. O backend não está em execução ou está escutando em um endereço ou porta diferente do que o proxy_pass mira. Confirme com curl http://127.0.0.1:3000 no próprio servidor.
• 502, SELinux ou firewall. Em sistemas da família RHEL, o SELinux impede que o nginx abra conexões de saída até que você execute setsebool -P httpd_can_network_connect 1.
• 504, backend lento. O aplicativo demora mais que o proxy_read_timeout para responder. Aumente o tempo limite para aquela location, ou corrija a consulta lenta, em vez de mascará-la globalmente.
• 502, cabeçalhos grandes. Um backend que envia cabeçalhos de resposta grandes pode transbordar os buffers do proxy. Aumente proxy_buffer_size e proxy_buffers.
• Upstream errado escolhido. Se um servidor em um conjunto upstream estiver fora do ar, o nginx o marca como não saudável e tenta o próximo, então 502s intermitentes muitas vezes apontam para um único backend não saudável.

Qual proxy reverso se encaixa e quando você precisa de um proxy diferente?

Use um proxy reverso nginx quando você está terminando TLS, balanceando carga ou roteando caminhos na frente dos seus próprios servidores; recorra a um proxy forward ou residencial quando o trabalho é enviar solicitações de saída a partir de muitos IPs. O nginx é excelente no trabalho de entrada e não foi projetado para o de saída. Aqui está a matriz de decisão:

• Use um proxy reverso nginx quando você hospeda o backend, quer um único endpoint HTTPS público sobre vários serviços internos, precisa de balanceamento de carga entre instâncias ou quer cache e gzip na borda.
• Evite o nginx como seu proxy quando o objetivo são solicitações de saída que devem parecer vir de muitos IPs ou países diferentes, porque um proxy reverso sai a partir do IP do seu único servidor e não pode rotacionar endereços.

Entre os proxies reversos especificamente, nginx, Caddy e HAProxy fazem diferentes compromissos:

Para automação de saída pesada, nosso guia de melhores práticas de web scraping cobre a rotação e o controle de taxa, e os proxies de datacenter ou proxies móveis se adequam a trabalhos onde o custo ou os IPs de operadora importam mais que a fidelidade residencial.

Quais são as limitações e os riscos de um proxy reverso nginx?

Um proxy reverso nginx é poderoso para o tráfego de entrada mas tem limites reais: ele não pode rotacionar IPs de saída, cabeçalhos mal configurados vazam ou escondem o cliente, e ele adiciona um componente operacional que você deve corrigir e monitorar. Conhecer isso mantém as expectativas honestas.

• IP de saída único. Cada solicitação de saída do proxy sai através do próprio IP do servidor, então um proxy reverso não pode ajudar com tarefas que precisam de muitos endereços de origem.
• Erros de cabeçalho são silenciosos. Esquecer X-Forwarded-For esconde o IP real do cliente do seu aplicativo e da sua limitação de taxa; esquecer X-Forwarded-Proto quebra os redirecionamentos HTTPS. O nginx não vai avisar você.
• Manutenção de TLS e certificados. Os certificados expiram, então a renovação e as recargas são suas, geralmente por meio do certbot e de um cron job ou de um timer do systemd.
• Um novo ponto de falha. O proxy agora está no caminho crítico; se ele cair, todos os backends por trás dele ficam inacessíveis, e é por isso que verificações de saúde e monitoramento importam.
• Não é uma ferramenta de anonimato de saída. Um proxy reverso não foi construído para disfarçar de onde as solicitações vêm. Esse é o trabalho de um proxy forward.

O nginx não é um produto da DataImpulse, e a DataImpulse não vende uma API de scraping gerenciada nem um proxy web gratuito. Execute o nginx você mesmo onde ele se encaixa; onde você precisa de escala de saída, a DataImpulse obtém seus IPs como proxies éticos de usuários que optam por participar e são compensados. Última atualização: 2026-07-22.

Perguntas frequentes

Guias relacionados

• Proxy forward NGINX
• Proxy reverso Cloudflare
• Proxy reverso Docker

Precisa de IPs de saída que o nginx não pode rotacionar?

Um proxy reverso lida com o tráfego de entrada, mas quando seu trabalho precisa de solicitações de saída a partir de muitos IPs reais, a DataImpulse adiciona mais de 90 milhões de IPs residenciais, móveis e de datacenter rotativos em 195 países, com pagamento conforme o uso a partir de um dólar por GB e tráfego que não expira. Crie uma conta para obter credenciais de gateway e rotear seu cliente para dentro do conjunto.