Solução de Erros 'Connection Refused' (Conexão Recusada) no Nginx: Um Guia Prático de Solução de Problemas

Encontrar um erro de 'Connection Refused' ao tentar acessar um serviço em execução atrás do Nginx é uma experiência comum, embora frustrante. Diferentemente de um erro de 'Timeout' (Tempo Esgotado), que sugere atraso na rede ou perda de pacotes, um erro de 'Connection Refused' é definitivo: o sistema operacional rejeitou imediatamente a tentativa de conexão porque nenhuma aplicação estava ouvindo ativamente no IP e porta 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 oferece uma abordagem sistemática de quatro fases para diagnosticar e resolver erros de 'Connection Refused', garantindo que você possa restaurar rapidamente a conectividade do serviço.

Fase 1: Verificação do Status do Servidor Nginx (O Ouvinte Primário)

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. Verificar 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 primária (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. Confirmar Portas de Escuta Ativas

Use a ferramenta ss (socket statistics) ou netstat para verificar se o Nginx está realmente se vinculando ao endereço IP e porta esperados (ex: 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 (ex: :80 ou :443) listada sob um processo (PID) associado ao Nginx, isso significa que o Nginx falhou ao se 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 escutar em uma porta diferente e disponível.

Fase 2: Configuração de Firewall e Rede

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

1. Verificar Firewalls Locais do Servidor

Certifique-se de que as portas nas quais o Nginx está escutando (ex: 80, 443) estejam 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. Verificar 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 da conexão pode se originar da camada de segurança da rede virtual.

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

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

Diretivas de configuração incorretas podem fazer com que o Nginx tente escutar em uma porta ou IP indisponível, resultando em falha na inicialização e recusa de conexão subsequente.

1. Revisar Diretivas `listen`

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

Exemplo de um bloco listen configurado corretamente:

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

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

2. Executar 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á que o serviço inicie, 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: Solução de 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 'Connection Refused', 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. Verificar 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 malsucedida. Procure por mensagens relacionadas à diretiva proxy_pass, especificamente mencionando erros de conexão.

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

You might see an entry like:

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

2. Verificar Status do Serviço de Backend

Esta é a correção mais comum em cenários de proxy: a aplicação de backend (ex: Node.js, Python Gunicorn, Apache) está inativa ou não está escutando onde o Nginx espera.

Etapas Acionáveis:
a. Verificar Status do Serviço de Backend: Confirme se a aplicação de backend está em execução.
b. Verificar Porta de Escuta do Backend: Use ss -tuln no servidor que hospeda o backend para confirmar se a aplicação está escutando no IP/Porta especificado na diretiva proxy_pass do Nginx.

3. Testar Conectividade do Backend Diretamente

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

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

# Testar 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 (ele não está escutando ou seu firewall interno está bloqueando o acesso 127.0.0.1).
Se curl ou telnet for bem-sucedido: O problema pode ser um erro sutil na sua diretiva proxy_pass (ex: ponto e vírgula ausente, resolução de nome de host incorreta ou uma incompatibilidade de protocolo - HTTP vs. HTTPS).

Erro Comum de `proxy_pass`

Certifique-se de que o endereço IP em seu proxy_pass corresponda ao local onde o backend está realmente vinculado. Se o backend se vincular a um IP específico (ex: 192.168.1.10:8080), mas o Nginx usar localhost:8080, a conexão falhará se a vinculação for restritiva.

Resumo das Principais Etapas 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á escutando no IP/Porta corretos (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 escutando no IP/Porta exato definido em proxy_pass? Teste a conectividade diretamente usando curl.

Seguindo este processo metódico, você pode identificar rapidamente se o erro 'Connection Refused' se deve a um serviço inativo, um firewall restritivo ou uma configuração de proxy incorreta, minimizando o tempo de inatividade e restaurando o acesso com eficiência.