Risoluzione degli errori 'Connection Refused' di Nginx: Guida pratica alla risoluzione dei problemi

Incontrare un errore 'Connection Refused' quando si tenta di accedere a un servizio eseguito dietro Nginx è un'esperienza comune, ma frustrante. A differenza di un errore 'Timeout', che suggerisce un ritardo di rete o una perdita di pacchetti, un errore 'Connection Refused' è definitivo: il sistema operativo ha immediatamente rifiutato il tentativo di connessione perché nessuna applicazione era in ascolto attivo sulla porta e sull'indirizzo IP specificati.

Questo rifiuto immediato individua il problema in alcune aree critiche: il servizio è inattivo, il firewall blocca il traffico localmente o la configurazione indirizza il traffico verso una porta inesistente. Questa guida fornisce un approccio sistematico in quattro fasi per diagnosticare e risolvere gli errori 'Connection Refused', assicurando di poter ripristinare rapidamente la connettività del servizio.

Fase 1: Verifica dello stato del server Nginx (Il listener principale)

La causa più elementare di un rifiuto di connessione è che il servizio Nginx stesso non è in esecuzione o è configurato in modo errato.

1. Verifica dello stato del servizio Nginx

Utilizza il gestore dei servizi del tuo sistema (di solito systemd) per confermare che Nginx sia attivo e in esecuzione. Un fallimento qui è la causa diretta del rifiuto sulla porta di ascolto principale (di solito 80 o 443).

sudo systemctl status nginx

Output previsto (Successo): Cerca Active: active (running).

Correzione attuabile: Se lo stato mostra inactive o failed, prova ad avviare il servizio e controlla i log per i dettagli dell'errore.

sudo systemctl start nginx
sudo journalctl -xe | grep nginx

2. Conferma delle porte in ascolto attive

Utilizza lo strumento ss (statistiche socket) o netstat per verificare che Nginx si stia effettivamente associando all'indirizzo IP e alla porta previsti (ad esempio, 0.0.0.0:80 o 127.0.0.1:8080).

# Utilizzando ss (preferito sulle moderne distribuzioni Linux)
sudo ss -tuln | grep 80

# Utilizzando netstat
sudo netstat -tuln | grep 80

Se non vedi la porta prevista (ad esempio, :80 o :443) elencata sotto un processo (PID) associato a Nginx, significa che Nginx non è riuscito ad associarsi, probabilmente a causa di un errore di configurazione o di un altro servizio che occupa già quella porta.

Suggerimento: Se un altro servizio occupa la porta, devi fermare quel servizio o modificare la configurazione di Nginx per ascoltare su una porta diversa e disponibile.

Fase 2: Firewall e configurazione di rete

Se Nginx è in esecuzione e in ascolto localmente, il rifiuto di connessione potrebbe verificarsi all'esterno del servizio, tipicamente a causa di regole del firewall che bloccano il traffico in entrata.

1. Controllo dei firewall del server locale

Assicurati che le porte su cui Nginx è in ascolto (ad esempio, 80, 443) siano esplicitamente consentite attraverso il firewall dell'host (UFW, firewalld o iptables).

Esempio UFW (Ubuntu/Debian)

sudo ufw status verbose
# Se chiuso, consenti le porte:
sudo ufw allow 'Nginx Full'
# O specificamente:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Esempio Firewalld (CentOS/RHEL)

sudo firewall-cmd --list-all
# Se chiuso, aggiungi i servizi:
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

2. Verifica dei gruppi di sicurezza del provider cloud

Se il tuo server è ospitato in un ambiente cloud (AWS EC2, Azure VM, GCP Compute Engine), il rifiuto di connessione potrebbe provenire dal livello di sicurezza della rete virtuale.

• Gruppi di sicurezza AWS (SG): Controlla il SG associato e assicurati che le regole in entrata consentano il traffico sulle porte 80 e 443 dagli indirizzi IP di origine (di solito 0.0.0.0/0 per l'accesso pubblico).
• Gruppi di sicurezza di rete Azure (NSG): Verifica le regole delle porte in entrata.

Fase 3: Convalida della configurazione di Nginx

Direttive di configurazione errate possono portare Nginx a tentare di ascoltare su una porta o un IP non disponibile, causando un fallimento all'avvio e un successivo rifiuto di connessione.

1. Revisione delle direttive listen

Ispeziona il tuo file di configurazione principale (spesso /etc/nginx/nginx.conf) e qualsiasi blocco server pertinente (di solito in /etc/nginx/conf.d/ o /etc/nginx/sites-enabled/). Assicurati che le direttive listen siano corrette.

Esempio di un blocco listen configurato correttamente:

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    # ... altre direttive
}

Se Nginx è configurato per ascoltare solo su 127.0.0.1 (localhost) ma stai tentando di accedervi utilizzando l'IP pubblico, la connessione verrà rifiutata.

2. Esecuzione del controllo sintattico della configurazione

Prima di riavviare Nginx, convalida sempre la sintassi della configurazione. Un errore di parsing impedirà l'avvio del servizio, causando il rifiuto.

sudo nginx -t

Se il test fallisce, correggi l'errore identificato, riesegui il test, quindi ricarica o riavvia Nginx.

sudo systemctl reload nginx

Fase 4: Risoluzione dei problemi del proxy inverso (Upstream)

Se Nginx è in esecuzione con successo sulle porte 80/443, ma l'accesso a un percorso specifico (/api/) risulta in 'Connection Refused', il problema si trova tra Nginx e il servizio backend (l'upstream).

In questo scenario, Nginx ha accettato la connessione iniziale, ma quando ha tentato di inoltrare la richiesta, la connessione al backend è stata rifiutata. I log degli errori lo confermeranno.

1. Controllo dei log degli errori di Nginx

Esamina i log degli errori di Nginx (di solito /var/log/nginx/error.log) immediatamente dopo aver tentato la connessione fallita. Cerca messaggi relativi alla direttiva proxy_pass, che menzionano specificamente errori di connessione.

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

Potresti vedere una voce come:

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

2. Verifica dello stato del servizio backend

Questa è la correzione più comune negli scenari proxy: l'applicazione backend (ad esempio, Node.js, Python Gunicorn, Apache) è inattiva o non è in ascolto dove Nginx se lo aspetta.

Passaggi attuabili:

a. Controlla lo stato del servizio backend: Conferma che l'applicazione backend sia in esecuzione.

b. Verifica la porta di ascolto del backend: Usa ss -tuln sul server che ospita il backend per confermare che l'applicazione sia in ascolto sull'IP/Porta specificati nella direttiva proxy_pass di Nginx.

3. Test diretto della connettività del backend

Testa la connessione dal server Nginx al backend utilizzando curl o telnet per isolare il problema da Nginx.

Supponiamo che il tuo proxy_pass sia impostato su http://127.0.0.1:8080:

# Test della connessione dal server Nginx alla porta del backend
curl -v http://127.0.0.1:8080

# O utilizzando telnet
telnet 127.0.0.1 8080

• Se curl o telnet fallisce: Il servizio backend è sicuramente il problema (non è in ascolto o il suo firewall interno blocca l'accesso a 127.0.0.1).
• Se curl o telnet ha successo: Il problema potrebbe essere un errore sottile nella tua direttiva proxy_pass (ad esempio, punto e virgola mancante, risoluzione del nome host errata o una discrepanza nel protocollo—HTTP vs. HTTPS).

Errore comune di proxy_pass

Assicurati che l'indirizzo IP nel tuo proxy_pass corrisponda a dove il backend è effettivamente associato. Se il backend si associa a un IP specifico (ad esempio, 192.168.1.10:8080) ma Nginx utilizza localhost:8080, la connessione fallirà se l'associazione è restrittiva.

Controlli finali dei passaggi chiave per la risoluzione dei problemi

1. Controllo del sistema: Nginx è in esecuzione (systemctl status nginx)?
2. Controllo della porta: Nginx è in ascolto sull'IP/Porta corretti (ss -tuln)?
3. Controllo del firewall: La porta in entrata è aperta sul firewall dell'host (UFW, iptables)?
4. Controllo della configurazione: nginx -t passa e le direttive listen sono corrette?
5. Controllo del proxy (se applicabile): Il servizio upstream è in esecuzione e in ascolto sull'esatto IP/Porta definito in proxy_pass? Testa la connettività direttamente usando curl.

Procedi con i controlli in ordine: listener, porta, firewall, configurazione, poi upstream. Questo percorso ti mantiene concentrato sul punto esatto in cui la connessione viene rifiutata.