Como configurar proxy reverso com Nginx

Tempo estimado: 30 a 40 minutos. Dificuldade: intermediária.

Neste guia, você vai configurar o Nginx como proxy reverso em uma VPS Ubuntu para rotear duas aplicações diferentes usando subdomínios. A ideia é simples: o Nginx escuta nas portas públicas 80 e 443, recebe as requisições HTTP ou HTTPS e encaminha cada uma para a aplicação correta rodando em uma porta local, como 3000 ou 8080. Esse padrão é comum quando você hospeda APIs, painéis administrativos, aplicações Node.js, serviços Python, apps em containers ou sites WordPress atrás de um servidor web.

Para deixar o tutorial executável sem depender de uma aplicação sua, vamos criar dois serviços HTTP simples em Python, apenas para teste. Depois, você pode trocar os destinos por uma API real, um app Node.js com PM2, um container Docker ou outro serviço. Se seu objetivo é hospedar backends, veja também o guia de contexto sobre VPS para API. Se você está montando ambientes para vários projetos, o conteúdo sobre VPS para desenvolvedores ajuda a planejar CPU, RAM e isolamento.

O que você vai aprender

Ao final, você terá um proxy reverso funcional com Nginx, pronto para receber tráfego público e distribuir requisições para múltiplas aplicações locais. Você vai entender o que cada diretiva faz, como testar antes de recarregar o serviço e como investigar falhas comuns sem sair reiniciando tudo às cegas.

Você vai aprender a:

• Instalar o Nginx em uma VPS Ubuntu e confirmar que o serviço está ativo.
• Mapear subdomínios para aplicações em portas locais diferentes.
• Criar blocos de servidor em /etc/nginx/sites-available/ e habilitar com links simbólicos.
• Usar proxy_pass, proxy_set_header, timeouts e suporte básico a WebSocket.
• Validar a sintaxe do Nginx antes de aplicar mudanças em produção.
• Emitir certificados HTTPS com Certbot e testar renovação automática.
• Ler logs de acesso e erro para diagnosticar 502, 404, timeout e falhas de DNS.

O cenário usado será o seguinte: app1.melhorvps.local aponta para uma aplicação local na porta 3000, e app2.melhorvps.local aponta para outra aplicação local na porta 8080. Em produção, substitua esses nomes por domínios reais, por exemplo api.seudominio.com.br e painel.seudominio.com.br. Para HTTPS público com Let’s Encrypt, você precisa usar domínios válidos apontando para o IP da VPS. Nomes .local funcionam apenas para testes locais com o arquivo hosts.

Pré-requisitos

Antes de começar, confirme que você tem acesso SSH a uma VPS com Ubuntu 22.04 ou 24.04. Os comandos também servem como base para Debian, com pequenas diferenças nos pacotes. Em distribuições como AlmaLinux, Rocky Linux ou CentOS, os caminhos de configuração e comandos de firewall mudam, então use este guia como referência conceitual, não como cópia direta.

Você vai precisar de:

• Usuário com permissão sudo.
• Acesso SSH funcionando.
• Portas 80 e 443 liberadas no firewall da VPS e no painel do provedor.
• Dois domínios ou subdomínios apontando para o IP público da VPS, caso queira HTTPS real.
• Conhecimento básico de terminal, edição de arquivos e DNS.

Conecte na VPS:

ssh [email protected]

Saída esperada, ou algo semelhante:

Welcome to Ubuntu 24.04 LTS
Last login: Mon Aug  3 10:15:22 2026 from 198.51.100.25

Troque deploy pelo seu usuário e 203.0.113.10 pelo IP da sua VPS. O IP usado aqui é reservado para documentação, então não tente acessá-lo diretamente.

Antes de alterar configurações críticas, crie um diretório de backup. Este guia não usa comandos destrutivos, mas alterações em Nginx podem causar indisponibilidade se você aplicar um arquivo inválido. O backup permite voltar rápido.

sudo mkdir -p /root/nginx-backup-$(date +%F)
sudo cp -a /etc/nginx /root/nginx-backup-$(date +%F)/ 2>/dev/null || true

Se o Nginx ainda não estiver instalado, o segundo comando pode não copiar nada. Tudo bem. Você vai instalar no próximo passo. Para ambientes WordPress, o mesmo conceito de proxy pode ficar na frente do PHP-FPM ou de containers. Se esse for seu caso, veja também o conteúdo sobre VPS para WordPress para entender requisitos de memória, cache e disco.

Passo 1: Preparar a VPS e identificar as aplicações

Comece atualizando o índice de pacotes e instalando ferramentas que serão usadas nos testes. O curl permite simular requisições HTTP, o lsof ajuda a verificar portas em uso e o python3 será usado para subir aplicações de teste simples. Se você já tem uma API ou aplicação rodando, ainda assim execute as verificações para saber quais portas estão livres.

sudo apt update
sudo apt install -y curl lsof python3 python3-venv ca-certificates gnupg

Você deve ver uma saída parecida com esta:

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
curl is already the newest version
python3 is already the newest version
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

Agora verifique se as portas públicas 80 e 443 já estão em uso. Se outro servidor web estiver ativo, como Apache ou Caddy, você precisa decidir qual serviço ficará na frente. Não pare serviços de produção sem planejar janela de manutenção.

sudo lsof -iTCP -sTCP:LISTEN -P -n | grep -E ':80|:443|:3000|:8080' || true

Antes de instalar o Nginx, uma saída vazia é normal:

Se aparecer algo como apache2 escutando na porta 80, não execute comandos para removê-lo sem avaliar impacto. Em vez disso, pare apenas se for um ambiente de teste ou se você tiver backup e janela autorizada:

sudo systemctl status apache2 --no-pager

Saída possível:

● apache2.service - The Apache HTTP Server
     Loaded: loaded
     Active: active (running)

Neste tutorial, vamos assumir que as portas 80 e 443 podem ser usadas pelo Nginx. Também vamos usar as portas locais 3000 e 8080 para demonstrar o roteamento. Em uma aplicação real, anote o endereço interno de cada serviço, por exemplo 127.0.0.1:3000, 127.0.0.1:5000 ou unix:/run/app.sock.

Passo 2: Instalar e validar o Nginx

Instale o Nginx pelos repositórios oficiais do Ubuntu. Essa é a opção mais simples para a maioria das VPS, porque já integra o serviço ao systemd e usa a estrutura padrão /etc/nginx/sites-available/ e /etc/nginx/sites-enabled/.

sudo apt install -y nginx

Saída esperada:

Reading package lists... Done
Building dependency tree... Done
The following NEW packages will be installed:
  nginx nginx-common
Setting up nginx-common ...
Setting up nginx ...
Processing triggers for man-db ...

Habilite o serviço para iniciar com o sistema e confirme o status. Em muitas instalações, ele já sobe automaticamente após o pacote ser instalado, mas não assuma isso.

sudo systemctl enable nginx
sudo systemctl status nginx --no-pager

Você deve ver active (running):

● nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (/usr/lib/systemd/system/nginx.service; enabled)
     Active: active (running)

Teste o acesso local. Esse comando consulta o Nginx pela própria VPS:

curl -I http://127.0.0.1

Saída esperada:

HTTP/1.1 200 OK
Server: nginx/1.24.0
Content-Type: text/html

Se você usa UFW, libere tráfego HTTP e HTTPS. Primeiro verifique o status para não sobrescrever uma política existente sem entender o cenário:

sudo ufw status verbose

Saída comum em servidores novos:

Status: inactive

Se o UFW estiver ativo, aplique a regra do perfil do Nginx:

sudo ufw allow 'Nginx Full'
sudo ufw status

Saída esperada:

Status: active
To                         Action      From
--                         ------      ----
Nginx Full                 ALLOW       Anywhere
OpenSSH                    ALLOW       Anywhere

Se o firewall estiver inativo, não ative sem garantir que SSH está liberado. Ativar UFW sem regra para SSH pode bloquear seu acesso. Primeiro permita OpenSSH, depois ative apenas se você tiver certeza:

sudo ufw allow OpenSSH

Neste ponto, o Nginx responde na porta 80 e está pronto para receber configurações de proxy reverso.

Passo 3: Subir aplicações de teste em portas locais

Para demonstrar múltiplas aplicações, crie dois diretórios com páginas diferentes e sirva cada um com o servidor HTTP embutido do Python. Em produção, você substituirá isso por serviços reais, como Node.js, Django, FastAPI, Laravel Octane, Grafana ou containers Docker. O objetivo aqui é gerar respostas previsíveis para testar o roteamento.

Crie os diretórios e arquivos:

mkdir -p ~/apps/app1 ~/apps/app2
printf 'App 1 respondendo na porta 3000\n' > ~/apps/app1/index.html
printf 'App 2 respondendo na porta 8080\n' > ~/apps/app2/index.html

Confira o conteúdo:

cat ~/apps/app1/index.html
cat ~/apps/app2/index.html

Saída esperada:

App 1 respondendo na porta 3000
App 2 respondendo na porta 8080

Agora suba os dois serviços em segundo plano. Estes comandos usam nohup para manter os processos ativos após você fechar o terminal, mas isso é apenas para laboratório. Para produção, use systemd, PM2, Supervisor ou containers com política de restart.

cd ~/apps/app1
nohup python3 -m http.server 3000 --bind 127.0.0.1 > ~/apps/app1/app1.log 2>&1 &
cd ~/apps/app2
nohup python3 -m http.server 8080 --bind 127.0.0.1 > ~/apps/app2/app2.log 2>&1 &

Verifique se as portas estão escutando apenas no loopback. Isso reduz exposição direta, porque o público acessa o Nginx, não as portas internas.

sudo lsof -iTCP -sTCP:LISTEN -P -n | grep -E ':3000|:8080'

Saída esperada:

python3  2145 deploy  3u  IPv4  41231  0t0  TCP 127.0.0.1:3000 (LISTEN)
python3  2148 deploy  3u  IPv4  41244  0t0  TCP 127.0.0.1:8080 (LISTEN)

Teste cada aplicação sem passar pelo Nginx:

curl http://127.0.0.1:3000
curl http://127.0.0.1:8080

Saída esperada:

App 1 respondendo na porta 3000
App 2 respondendo na porta 8080

Se esses testes falharem, resolva antes de configurar o proxy. O Nginx não conserta aplicação parada. Ele apenas encaminha a requisição e devolve a resposta recebida do upstream.

Passo 4: Criar os blocos de servidor do proxy reverso

Agora você vai criar dois blocos de servidor, um para cada subdomínio. Para teste local sem DNS real, usaremos app1.melhorvps.local e app2.melhorvps.local. Em produção, use subdomínios válidos. A lógica é a mesma: cada server_name recebe um nome e cada location / encaminha para a porta correta via proxy_pass.

Crie o arquivo do primeiro app:

sudo nano /etc/nginx/sites-available/app1.conf

Cole este conteúdo:

server {
    listen 80;
    listen [::]:80;
    server_name app1.melhorvps.local;

    access_log /var/log/nginx/app1.access.log;
    error_log /var/log/nginx/app1.error.log;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        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;
    }
}

Crie o segundo arquivo:

sudo nano /etc/nginx/sites-available/app2.conf

Cole:

server {
    listen 80;
    listen [::]:80;
    server_name app2.melhorvps.local;

    access_log /var/log/nginx/app2.access.log;
    error_log /var/log/nginx/app2.error.log;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        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;
    }
}

Habilite os sites com links simbólicos:

sudo ln -s /etc/nginx/sites-available/app1.conf /etc/nginx/sites-enabled/app1.conf
sudo ln -s /etc/nginx/sites-available/app2.conf /etc/nginx/sites-enabled/app2.conf

Teste a sintaxe antes de recarregar. Esse passo evita derrubar o Nginx por erro de digitação:

sudo nginx -t

Saída esperada:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Aplique a configuração sem encerrar conexões ativas:

sudo systemctl reload nginx

Para testar nomes .local a partir da própria VPS, use o header Host no curl:

curl -H 'Host: app1.melhorvps.local' http://127.0.0.1
curl -H 'Host: app2.melhorvps.local' http://127.0.0.1

Saída esperada:

App 1 respondendo na porta 3000
App 2 respondendo na porta 8080

Se você estiver usando domínios reais, configure registros DNS tipo A apontando para o IP público da VPS e teste de fora com curl http://api.seudominio.com.br.

Passo 5: Ajustar headers, WebSocket e timeouts

Muitas aplicações modernas precisam de headers corretos para registrar IP real, detectar HTTPS e montar URLs absolutas. Além disso, apps com WebSocket, Server Sent Events ou respostas longas podem falhar se o proxy usar timeouts muito curtos. Vamos melhorar a configuração criando um arquivo compartilhado de parâmetros de proxy. Isso evita repetição e facilita manter vários serviços.

Crie o arquivo:

sudo nano /etc/nginx/snippets/proxy-common.conf

Cole o conteúdo:

proxy_http_version 1.1;
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;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
proxy_connect_timeout 10s;

A diretiva Connection $connection_upgrade precisa de um map definido no contexto http, não dentro do server. Faça backup do arquivo principal antes de editar:

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%F-%H%M)
sudo nano /etc/nginx/nginx.conf

Dentro do bloco http {, adicione este trecho antes dos includes de sites:

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

Agora simplifique os dois sites. Edite o app1:

sudo nano /etc/nginx/sites-available/app1.conf

Substitua o bloco location / por:

location / {
    proxy_pass http://127.0.0.1:3000;
    include snippets/proxy-common.conf;
}

Faça o mesmo no app2, apontando para a porta 8080:

sudo nano /etc/nginx/sites-available/app2.conf

Use:

location / {
    proxy_pass http://127.0.0.1:8080;
    include snippets/proxy-common.conf;
}

Teste e recarregue:

sudo nginx -t
sudo systemctl reload nginx

Saída esperada:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Valide os headers enviados ao upstream com um teste simples de acesso. Como nosso servidor Python não imprime headers, verifique ao menos se o roteamento não quebrou:

curl -H 'Host: app1.melhorvps.local' http://127.0.0.1

Saída esperada:

App 1 respondendo na porta 3000

Esses ajustes são especialmente úteis em APIs com autenticação, aplicações atrás de HTTPS e painéis que usam WebSocket para atualizações em tempo real.

Passo 6: Habilitar HTTPS com Certbot

HTTPS público exige domínio real apontando para a VPS. Nomes .local não recebem certificado da Let’s Encrypt. Se você ainda está só testando localmente, pule este passo e volte quando tiver DNS configurado. Para produção, substitua api.seudominio.com.br e painel.seudominio.com.br pelos seus subdomínios reais nos arquivos server_name antes de rodar o Certbot.

Primeiro, confira se o DNS já aponta para sua VPS. Execute a partir da própria VPS ou da sua máquina local:

getent hosts api.seudominio.com.br
getent hosts painel.seudominio.com.br

Saída esperada, com o IP da sua VPS:

203.0.113.10 api.seudominio.com.br
203.0.113.10 painel.seudominio.com.br

Instale o Certbot e o plugin do Nginx:

sudo apt install -y certbot python3-certbot-nginx

Saída esperada:

The following NEW packages will be installed:
  certbot python3-certbot-nginx
Setting up certbot ...
Setting up python3-certbot-nginx ...

Antes de emitir, teste a configuração do Nginx novamente:

sudo nginx -t

Saída esperada:

nginx: configuration file /etc/nginx/nginx.conf test is successful

Emita certificados para os dois subdomínios. O Certbot vai editar os blocos do Nginx e adicionar redirects para HTTPS se você escolher essa opção durante o assistente.

sudo certbot --nginx -d api.seudominio.com.br -d painel.seudominio.com.br

Saída típica:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/api.seudominio.com.br/fullchain.pem
Deploying certificate
Successfully deployed certificate for api.seudominio.com.br to /etc/nginx/sites-enabled/app1.conf
Successfully deployed certificate for painel.seudominio.com.br to /etc/nginx/sites-enabled/app2.conf

Teste a renovação automática sem alterar certificados reais:

sudo certbot renew --dry-run

Saída esperada:

Congratulations, all simulated renewals succeeded

Se o Certbot falhar com erro de autorização, quase sempre é DNS incorreto, porta 80 bloqueada ou server_name diferente do domínio solicitado. Corrija isso antes de tentar várias vezes, pois a Let’s Encrypt aplica limites de emissão.

Verificação e testes

Depois de configurar o proxy, faça testes em camadas. Primeiro, confirme que as aplicações continuam respondendo diretamente nas portas locais. Isso separa problema de app de problema de Nginx.

curl http://127.0.0.1:3000
curl http://127.0.0.1:8080

Saída esperada:

App 1 respondendo na porta 3000
App 2 respondendo na porta 8080

Agora teste via Nginx com header Host:

curl -i -H 'Host: app1.melhorvps.local' http://127.0.0.1
curl -i -H 'Host: app2.melhorvps.local' http://127.0.0.1

Você deve receber HTTP 200 e o conteúdo correto:

HTTP/1.1 200 OK
Server: nginx/1.24.0
App 1 respondendo na porta 3000

Verifique os logs separados:

sudo tail -n 20 /var/log/nginx/app1.access.log
sudo tail -n 20 /var/log/nginx/app2.access.log

Saída esperada:

127.0.0.1 - - [03/Aug/2026:11:20:10 +0000] "GET / HTTP/1.1" 200 31 "-" "curl/8.5.0"

Se você configurou HTTPS com domínios reais, teste os certificados:

curl -I https://api.seudominio.com.br
curl -I https://painel.seudominio.com.br

Saída esperada:

HTTP/2 200
server: nginx
strict-transport-security: max-age=31536000

Nem toda instalação adiciona HSTS automaticamente. Se você decidir adicionar, faça com cuidado, porque HSTS força navegadores a usarem HTTPS por longo período. Use primeiro um max-age baixo em homologação.

Por fim, valide quais portas estão expostas:

sudo ss -tulpn | grep -E ':80|:443|:3000|:8080'

O ideal é ver 80 e 443 no Nginx e as portas 3000 e 8080 presas em 127.0.0.1:

tcp LISTEN 0 511 0.0.0.0:80    0.0.0.0:* users:(("nginx"))
tcp LISTEN 0 511 0.0.0.0:443   0.0.0.0:* users:(("nginx"))
tcp LISTEN 0 5   127.0.0.1:3000 0.0.0.0:* users:(("python3"))

Troubleshooting

Se você receber 502 Bad Gateway, o Nginx conseguiu receber a requisição, mas não conseguiu falar com o upstream. Verifique se a aplicação está ativa e se a porta no proxy_pass está correta:

curl http://127.0.0.1:3000
sudo tail -n 50 /var/log/nginx/app1.error.log

Erro comum:

connect() failed (111: Connection refused) while connecting to upstream

Nesse caso, inicie a aplicação, corrija a porta ou ajuste o bind para 127.0.0.1. Se ela estiver em Docker, confirme a porta publicada no host.

Se você receber a aplicação errada, o problema costuma estar no server_name ou no DNS. Teste explicitamente com header Host:

curl -H 'Host: app2.melhorvps.local' http://127.0.0.1
sudo nginx -T | grep -A20 'server_name app2'

Saída útil:

server_name app2.melhorvps.local;
proxy_pass http://127.0.0.1:8080;

Se o domínio público aponta para outro IP, corrija o registro A no DNS e aguarde propagação.

Se o Certbot falhar, verifique porta 80 e nome do servidor:

curl -I http://api.seudominio.com.br
sudo ufw status
sudo nginx -t

Mensagens como unauthorized indicam que a Let’s Encrypt não conseguiu acessar o desafio HTTP. Libere a porta 80, confira o DNS e remova redirects manuais quebrados antes de tentar de novo.

Se houver timeout, aumente proxy_read_timeout no snippet e investigue a aplicação. Timeout alto mascara lentidão, então use logs do app também:

sudo tail -f /var/log/nginx/app1.error.log

Se o Nginx não recarregar, não force restart antes de ler o erro. Rode:

sudo nginx -t

Ele indicará arquivo e linha, por exemplo:

nginx: [emerg] unknown directive "proxy_set_heder" in /etc/nginx/snippets/proxy-common.conf:3

Corrija a digitação, teste novamente e só então recarregue.

Próximos passos

Com o proxy reverso funcionando, substitua os servidores Python por suas aplicações reais. Para Node.js, rode o app com PM2 e aponte proxy_pass para http://127.0.0.1:3000. Para Docker, publique a porta apenas em 127.0.0.1, por exemplo 127.0.0.1:3000:3000, e deixe o Nginx como única entrada pública.

Também vale configurar logs rotacionados, monitoramento e métricas. Verifique consumo de memória, quantidade de workers e tempo médio de resposta. Em ambientes com várias aplicações, padronize nomes de arquivos, como /etc/nginx/sites-available/api.conf, /etc/nginx/sites-available/admin.conf e /etc/nginx/sites-available/site.conf.

Se você hospeda WordPress, APIs e painéis na mesma VPS, planeje isolamento. Um proxy reverso ajuda no roteamento, mas não substitui boas práticas de deploy, backup, firewall e atualização. Revise seus snapshots, mantenha certificados renovando automaticamente e documente qual subdomínio aponta para qual serviço. Quando adicionar um novo app, siga sempre o mesmo fluxo: teste local, crie bloco Nginx, rode nginx -t, recarregue, teste HTTP, emita HTTPS e monitore logs.