Análise de Logs de Erro do Nginx para Solução de Problemas de Conexão Recusada

Analisar os logs de erro do Nginx para solucionar problemas de conexão recusada ajuda você a ir de uma página genérica 502 para uma falha específica no backend. A frase "conexão recusada" geralmente significa que o Nginx tentou se conectar a um endereço upstream, mas nenhum processo aceitou a conexão.

Isso é diferente de um timeout, falha de DNS ou resposta ruim. Depois de reconhecer o padrão do log, você pode restringir a correção rapidamente.

O que "Conexão Recusada" Significa

Nos logs do Nginx, uma mensagem comum se parece com isto:

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

Isso significa que o sistema operacional rejeitou a tentativa de conexão. O Nginx alcançou o host de destino, mas nada estava ouvindo na porta de destino, ou a conexão foi ativamente recusada.

Você pode ver isso quando o Nginx faz proxy para:

proxy_pass http://127.0.0.1:3000;

mas o aplicativo está parado ou ouvindo em uma porta diferente.

Este erro é comum após implantações. Um gerenciador de processos pode falhar ao reiniciar o aplicativo, um contêiner pode travar ou uma nova configuração pode alterar a porta do aplicativo sem atualizar o Nginx.

Não trate todo 502 como conexão recusada. Uma mensagem de timeout aponta em uma direção diferente. Uma mensagem de permissão negada geralmente aponta para sockets ou política de segurança. O texto exato do log é importante.

Encontrando o Log de Erro Correto do Nginx

O caminho padrão do log de erro é frequentemente:

/var/log/nginx/error.log

Mas os blocos de servidor podem definir logs personalizados:

error_log /var/log/nginx/app-error.log warn;

Verifique a configuração relevante do Nginx se o log padrão não mostrar entradas recentes. Em alguns sistemas, as mensagens de nível de serviço também aparecem no diário do sistema.

Comandos úteis incluem:

tail -n 100 /var/log/nginx/error.log

e:

journalctl -u nginx -n 100

Ao testar, dispare uma solicitação no navegador ou com curl, e então verifique imediatamente as linhas de log mais recentes. Isso torna muito mais fácil conectar o erro voltado para o usuário com a falha do backend.

Uma boa revisão de log captura quatro informações:

• O timestamp da solicitação com falha.
• O endereço e a porta upstream.
• O caminho da solicitação.
• O erro exato do sistema, como 111: Connection refused.

Para uma solução de problemas mais ampla do Nginx, veja corrigindo erros 502 Bad Gateway do Nginx.

Mapeando a Entrada de Log para o Upstream

Uma linha de log típica pode incluir um valor upstream como:

upstream: "http://127.0.0.1:3000/api/status"

Isso informa exatamente para onde o Nginx tentou enviar a solicitação. Agora verifique se algo está ouvindo lá:

ss -ltnp

Procure por 127.0.0.1:3000, 0.0.0.0:3000 ou o endereço esperado. Se a porta estiver faltando, o aplicativo não está ouvindo onde o Nginx espera.

Teste o upstream diretamente:

curl -i http://127.0.0.1:3000/api/status

Se isso falhar com conexão recusada, você confirmou o problema sem o Nginx no meio.

Se o aplicativo estiver rodando no Docker, tome cuidado com 127.0.0.1. Do host, significa o host. De dentro de um contêiner Nginx, significa o próprio contêiner Nginx. Em uma configuração Compose, o Nginx geralmente precisa fazer proxy para um nome de serviço como:

proxy_pass http://app:3000;

desde que ambos os contêineres compartilhem a mesma rede Docker.

Para sockets Unix, o log pode apontar para um caminho em vez de uma porta:

upstream: "http://unix:/run/app/app.sock:/"

Nesse caso, verifique se o socket existe e se o usuário do worker do Nginx pode acessá-lo.

Causas Comuns e Correções

A causa mais comum é um serviço de backend parado. Verifique com:

systemctl status your-app

Se falhou, leia os logs do aplicativo antes de reiniciar. Uma reinicialização pode trazer o site de volta, mas os logs explicam por que falhou.

Outra causa comum é uma incompatibilidade de porta. Por exemplo, o aplicativo mudou da porta 3000 para 8080, mas o Nginx ainda faz proxy para 3000. Corrija o destino upstream do Nginx ou restaure a porta esperada do aplicativo.

Uma terceira causa é a vinculação à interface errada. Um aplicativo ouvindo apenas em 127.0.0.1 é acessível a partir do Nginx local no mesmo host. Mas se o Nginx for executado em outro contêiner ou outro servidor, não será acessível através desse endereço de loopback. Nessas configurações, o aplicativo pode precisar ser vinculado a 0.0.0.0 dentro da rede privada.

As regras de firewall também podem recusar ou rejeitar conexões, especialmente entre servidores. Se o Nginx fizer proxy para outro host, confirme se a porta upstream está aberta na máquina Nginx, não apenas no seu laptop.

Finalmente, o tempo de implantação pode causar breves erros de conexão recusada. Se o Nginx enviar tráfego antes que o novo processo do aplicativo esteja pronto, os usuários podem ver 502s intermitentes. Uma verificação de integridade, sonda de prontidão ou estratégia de reinicialização graciosa pode evitar isso.

Um Fluxo Prático de Solução de Problemas

Use esta ordem quando o log disser conexão recusada:

1. Copie o host e a porta upstream do log de erro do Nginx.
2. Execute curl para esse upstream exato a partir do servidor Nginx.
3. Execute ss -ltnp para confirmar se um processo está ouvindo.
4. Verifique o status do serviço de backend e os logs do aplicativo.
5. Compare o valor proxy_pass do Nginx com o endereço de ligação real do aplicativo.
6. Recarregue o Nginx somente após a configuração estar correta e nginx -t passar.

Este fluxo evita um erro comum: editar o Nginx quando o aplicativo está simplesmente inativo. Também evita o erro oposto: reiniciar o aplicativo repetidamente quando o Nginx está apontando para o lugar errado.

Para comandos básicos, veja comandos de monitoramento de log do Nginx.

Quando Chamar um Profissional

Obtenha ajuda quando erros de conexão recusada ocorrerem apenas sob carga, em vários upstreams ou durante implantações contínuas. Esses casos podem envolver supervisão de processos, rede de contêineres, verificações de integridade do balanceador de carga ou limites de capacidade.

Você também deve escalar se o upstream for um serviço de API de produção de pagamento, autenticação ou voltado para o cliente. A recuperação rápida é importante, mas preservar os logs e entender a falha também é importante.

A conexão recusada é um dos erros mais claros do Nginx depois que você o lê com atenção. Encontre o upstream no log, teste esse destino diretamente e corrija o serviço, porta, interface ou caminho de rede que impede o Nginx de se conectar. O log já fornece o ponto de partida.