Corrigindo Erros de 'Conexão Recusada' no Nginx: Um Guia Prático de Solução de Problemas

Encontrar um erro de 'Conexão Recusada' ao tentar acessar um serviço rodando por trás do Nginx é uma experiência comum, embora frustrante. Diferente de um erro de 'Timeout', que sugere atraso na rede ou perda de pacotes, um erro de 'Conexão Recusada' é definitivo: o sistema operacional rejeitou imediatamente a tentativa de conexão porque nenhum aplicativo estava ouvindo ativamente na porta e endereço IP especificados.

Essa rejeição imediata aponta o problema para algumas áreas críticas: o serviço está inativo, o firewall está bloqueando o tráfego localmente ou a configuração direciona o tráfego para uma porta inexistente. Este guia fornece uma abordagem sistemática de quatro fases para diagnosticar e resolver erros de 'Conexão Recusada', garantindo que você possa restaurar rapidamente a conectividade do serviço.

Fase 1: Verificando o Status do Servidor Nginx (O Ouvinte Principal)

A causa mais básica de uma recusa de conexão é que o próprio serviço Nginx não está em execução ou está configurado incorretamente.

1. Verifique o Status do Serviço Nginx

Use o gerenciador de serviços do seu sistema (geralmente systemd) para confirmar que o Nginx está ativo e em execução. Uma falha aqui é a causa direta da recusa na porta de escuta principal (geralmente 80 ou 443).

sudo systemctl status nginx

Saída Esperada (Sucesso): Procure por Active: active (running).

Correção Acionável: Se o status mostrar inactive ou failed, tente iniciar o serviço e verifique os logs para detalhes da falha.

sudo systemctl start nginx
sudo journalctl -xe | grep nginx

2. Confirme as Portas de Escuta Ativas

Use a ferramenta ss (estatísticas de socket) ou netstat para verificar se o Nginx está realmente vinculado ao endereço IP e porta esperados (por exemplo, 0.0.0.0:80 ou 127.0.0.1:8080).

# Usando ss (preferido em distribuições Linux modernas)
sudo ss -tuln | grep 80

# Usando netstat
sudo netstat -tuln | grep 80

Se você não vir a porta esperada (por exemplo, :80 ou :443) listada sob um processo (PID) associado ao Nginx, significa que o Nginx falhou ao vincular, provavelmente devido a um erro de configuração ou outro serviço já ocupando essa porta.

Dica: Se outro serviço estiver ocupando a porta, você deve parar esse serviço ou modificar a configuração do Nginx para ouvir em uma porta diferente e disponível.

Fase 2: Firewall e Configuração de Rede

Se o Nginx estiver em execução e ouvindo localmente, a recusa de conexão pode estar ocorrendo externamente ao serviço, tipicamente devido a regras de firewall bloqueando o tráfego de entrada.

1. Verifique os Firewalls do Servidor Local

Certifique-se de que as portas nas quais o Nginx está ouvindo (por exemplo, 80, 443) estão explicitamente permitidas através do firewall do host (UFW, firewalld ou iptables).

Exemplo UFW (Ubuntu/Debian)

sudo ufw status verbose
# Se fechado, permita as portas:
sudo ufw allow 'Nginx Full'
# Ou especificamente:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Exemplo Firewalld (CentOS/RHEL)

sudo firewall-cmd --list-all
# Se fechado, adicione os serviços:
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

2. Verifique os Grupos de Segurança do Provedor de Nuvem

Se o seu servidor estiver hospedado em um ambiente de nuvem (AWS EC2, Azure VM, GCP Compute Engine), a recusa de conexão pode se originar da camada de segurança da rede virtual.

Grupos de Segurança AWS (SG): Verifique o SG associado e certifique-se de que as regras de entrada permitem tráfego nas portas 80 e 443 dos endereços IP de origem (geralmente 0.0.0.0/0 para acesso público).
Grupos de Segurança de Rede Azure (NSG): Verifique as regras de porta de entrada.

Fase 3: Validação da Configuração do Nginx

Diretivas de configuração incorretas podem levar o Nginx a tentar ouvir em uma porta ou IP indisponível, resultando em falha na inicialização e subsequente recusa de conexão.

1. Revise as Diretivas `listen`

Inspecione seu arquivo de configuração principal (geralmente /etc/nginx/nginx.conf) e quaisquer blocos de servidor relevantes (geralmente em /etc/nginx/conf.d/ ou /etc/nginx/sites-enabled/). Certifique-se de que as diretivas listen estão corretas.

Exemplo de um bloco de escuta configurado corretamente:

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    # ... outras diretivas
}

Se o Nginx estiver configurado para ouvir apenas em 127.0.0.1 (localhost), mas você estiver tentando acessá-lo usando o IP público, a conexão será recusada.

2. Execute a Verificação de Sintaxe da Configuração

Antes de reiniciar o Nginx, sempre valide a sintaxe da configuração. Um erro de análise impedirá o serviço de iniciar, causando a recusa.

sudo nginx -t

Se o teste falhar, corrija o erro identificado, execute o teste novamente e, em seguida, recarregue ou reinicie o Nginx.

sudo systemctl reload nginx

Fase 4: Solucionando Problemas de Proxy Reverso (Upstream)

Se o Nginx estiver em execução com sucesso nas portas 80/443, mas acessar um caminho específico (/api/) resultar em 'Conexão Recusada', o problema está entre o Nginx e o serviço de backend (o upstream).

Neste cenário, o Nginx aceitou a conexão inicial, mas quando tentou fazer o proxy da solicitação, a conexão com o backend foi recusada. Os logs de erro confirmarão isso.

1. Verifique os Logs de Erro do Nginx

Examine os logs de erro do Nginx (geralmente /var/log/nginx/error.log) imediatamente após tentar a conexão com falha. Procure por mensagens relacionadas à diretiva proxy_pass, mencionando especificamente erros de conexão.

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

Você pode ver uma entrada como:

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

2. Verifique o Status do Serviço de Backend

Esta é a correção mais comum em cenários de proxy: o aplicativo de backend (por exemplo, Node.js, Python Gunicorn, Apache) está inativo ou não está ouvindo onde o Nginx espera.

Passos Acionáveis:

a. Verifique o Status do Serviço de Backend: Confirme se o aplicativo de backend está em execução.

b. Verifique a Porta de Escuta do Backend: Use ss -tuln no servidor que hospeda o backend para confirmar se o aplicativo está ouvindo no IP/Porta especificado na diretiva proxy_pass do Nginx.

3. Teste a Conectividade do Backend Diretamente

Teste a conexão do servidor Nginx para o backend usando curl ou telnet para isolar o problema do Nginx.

Suponha que seu proxy_pass esteja definido como http://127.0.0.1:8080:

# Teste a conexão do servidor Nginx para a porta do backend
curl -v http://127.0.0.1:8080

# Ou usando telnet
telnet 127.0.0.1 8080

Se curl ou telnet falhar: O serviço de backend é definitivamente o problema (não está ouvindo ou seu firewall interno está bloqueando o acesso a 127.0.0.1).
Se curl ou telnet for bem-sucedido: O problema pode ser um erro sutil em sua diretiva proxy_pass (por exemplo, ponto e vírgula ausente, resolução de nome de host incorreta ou incompatibilidade no protocolo—HTTP vs. HTTPS).

Erro Comum no `proxy_pass`

Certifique-se de que o endereço IP em seu proxy_pass corresponda aonde o backend está realmente vinculado. Se o backend vincular a um IP específico (por exemplo, 192.168.1.10:8080), mas o Nginx usar localhost:8080, a conexão falhará se o vínculo for restritivo.

Verificações Finais das Etapas Principais de Solução de Problemas

Verificação do Sistema: O Nginx está em execução (systemctl status nginx)?
Verificação da Porta: O Nginx está ouvindo no IP/Porta correto (ss -tuln)?
Verificação do Firewall: A porta de entrada está aberta no firewall do host (UFW, iptables)?
Verificação da Configuração: O nginx -t passa e as diretivas listen estão corretas?
Verificação do Proxy (Se Aplicável): O serviço upstream está em execução e ouvindo no IP/Porta exato definido em proxy_pass? Teste a conectividade diretamente usando curl.

Trabalhe através das verificações em ordem: ouvinte, porta, firewall, configuração e depois upstream. Esse caminho mantém você focado no local exato onde a conexão está sendo recusada.