Nginx 502 Bad Gateway: como encontrar o erro real no seu servidor
Publicado em 2026-10-26 por frfrand
Guia para diagnosticar 502 entre Nginx, Gunicorn e FastAPI
O navegador mostra 502 e a primeira coisa que alguém propõe é mudar o DNS. Mas se o Nginx está respondendo, provavelmente você já chegou ao proxy. O erro costuma estar entre o Nginx e a aplicação para a qual ele tenta se conectar.
Vamos transformar isso em um procedimento que você pode usar em um VPS real. O objetivo é entender por que funciona, como testar e qual problema aparece se uma parte estiver mal configurada.
O que significa Nginx 502 Bad Gateway e quando você precisa disso
Um 502 indica que o proxy recebeu uma resposta inválida ou não conseguiu se comunicar corretamente com o upstream, entre outras causas. Pode acontecer porque o Gunicorn não iniciou, está escutando em outra porta, foi encerrado por falta de RAM ou o soquete Unix tem permissões incorretas.
Antes de mudar qualquer coisa em produção, anote o estado atual: IP, domínio, porta, serviço afetado e hora do último deploy. Uma modificação isolada é fácil de comprobar; cinco mudanças simultâneas tornam mais difícil reconstruir o que aconteceu.
Configuração ou comandos de exemplo
sudo nginx -t
sudo tail -n 80 /var/log/nginx/error.log
sudo systemctl status miapp
sudo journalctl -u miapp -n 100 --no-pager
sudo ss -ltnp
curl -i http://127.0.0.1:8000/healthOs domínios, IPs, rotas e nomes são ilustrativos. Não copie uma configuração inteira por cima da atual sem comparar primeiro. Nos exemplos que incluem portas ou firewall, certifique-se de manter o acesso administrativo.
Como eu faria passo a passo
- Preparação. Verifique se o 502 é retornado pelo Nginx e se o domínio aponta para o servidor esperado.
- Passo 2. Veja o log de erros do Nginx para encontrar o endereço upstream exato.
- Passo 3. Revise a unidade systemd do Gunicorn/Uvicorn e o primeiro erro de inicialização.
- Passo 4. Teste diretamente a porta local do backend para isolar o proxy.
- Verificação. Corrija o problema concreto e verifique uma operação real por HTTPS.
Quando terminar, verifique a operação real a partir de outra conexão. Por exemplo, para uma API não basta abrir o navegador: execute uma solicitação de leitura, uma gravação em um banco de teste e consulte os logs do processo.
Exemplo de um projeto de verdade
Após um deploy Django, o Gunicorn falha porque o ambiente virtual não existe mais no caminho indicado. O Nginx funciona bem, mas não tem com quem falar. Os logs do systemd mostram a causa em segundos.
A lição é simples: uma configuração de infraestrutura não vive isolada da aplicação. O frontend, o servidor, o banco de dados e os workers se conectam, então medir onde começa a falha é mais útil do que reiniciar tudo.
O erro que evitaria
Não reinicie o PostgreSQL, o Nginx e toda a máquina simultaneamente: você perde evidências. Tampouco atribua um 502 ao certificado sem comprovar que ocorreu após o estabelecimento do TLS.
Quando trabalha com servidores de clientes, guarde um backup ou procedimento de reversão antes de mudanças que afetem dados, rede ou certificados. E se não souber quais permissões uma operação precisa, evite executar como root apenas para parar de mostrar erros.
Como isso se relaciona com o ArduMaker?
Com o ArduMaker você pode relacionar logs de serviços e último deploy no VPS. Se um build foi concluído mas o processo não inicia, o erro está na inicialização e não necessariamente no Git.
Em um caso típico você pode criar um VPS para a aplicação, fazer deploy a partir do Git, associar domínio HTTPS e administrar o backend e os bancos de dados necessários. As ferramentas ajudam a centralizar operações, mas é preciso entender qual porta e processo cumpre cada função.
Perguntas que aparecem quando você testa
Como saber se a falha é de DNS ou do serviço? Consulte primeiro a resolução, depois a conexão na porta e finalmente a resposta da aplicação. Essa ordem evita confundir problemas diferentes.
Posso expor um banco de dados para facilitar a manutenção? Melhor projetar acesso privado ou túneis autenticados quando possível. Expor uma porta não substitui as permissões do mecanismo nem o firewall.
O que deveria documentar? A configuração esperada, como verificar e como voltar ao estado anterior. Esse documento ajuda mais do que uma lista de comandos sem contexto.
Referências
Em resumo: uma boa configuração de rede ou servidor é aquela que você consegue explicar, verificar e recuperar quando algo falha.