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

Imbattersi in un errore 'Connection Refused' quando si tenta di accedere a un servizio in esecuzione dietro Nginx è un'esperienza comune, ma frustrante. A differenza di un errore 'Timeout', che suggerisce ritardi di rete o perdita di pacchetti, un errore 'Connection Refused' è definitivo: il sistema operativo ha rifiutato immediatamente 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 sta bloccando 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', garantendo di ripristinare rapidamente la connettività del servizio.

Fase 1: Verifica dello stato del server Nginx (l'ascoltatore primario)

La causa più basilare 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

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

sudo systemctl status nginx

Output atteso (successo): Cercare Active: active (running).

Correzione attuabile: Se lo stato mostra inactive o failed, tentare di avviare il servizio e controllare i log per i dettagli del fallimento.

sudo systemctl start nginx
sudo journalctl -xe | grep nginx

2. Conferma delle porte di ascolto attive

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

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

# Utilizzo di netstat
sudo netstat -tuln | grep 80

Se non si vede la porta prevista (ad esempio, :80 o :443) elencata sotto un processo (PID) associato a Nginx, significa che Nginx non è riuscito a collegarsi, probabilmente a causa di un errore di configurazione o perché un altro servizio sta già occupando quella porta.

Suggerimento: Se un altro servizio sta occupando la porta, è necessario arrestare tale servizio o modificare la configurazione di Nginx per ascoltare su una porta diversa e disponibile.

Fase 2: Configurazione firewall e di rete

Se Nginx è in esecuzione e in ascolto localmente, il rifiuto della connessione potrebbe avvenire esternamente al servizio, tipicamente a causa di regole del firewall che bloccano il traffico in ingresso.

1. Verifica dei firewall locali del server

Assicurarsi 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, consentire 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, aggiungere 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 server è ospitato in un ambiente cloud (AWS EC2, Azure VM, GCP Compute Engine), il rifiuto della connessione potrebbe provenire dal livello di sicurezza della rete virtuale.

Gruppi di sicurezza AWS (SG): Controllare il SG associato e assicurarsi che le regole in ingresso consentano il traffico sulle porte 80 e 443 dagli indirizzi IP di origine (solitamente 0.0.0.0/0 per l'accesso pubblico).
Gruppi di sicurezza di rete Azure (NSG): Verificare le regole delle porte in ingresso.

Fase 3: Validazione della configurazione di Nginx

Direttive di configurazione errate possono portare Nginx a tentare di ascoltare su una porta o IP non disponibili, causando un errore di avvio e un conseguente rifiuto della connessione.

1. Revisione delle direttive `listen`

Ispezionare il file di configurazione principale (spesso /etc/nginx/nginx.conf) e i blocchi server pertinenti (solitamente in /etc/nginx/conf.d/ o /etc/nginx/sites-enabled/). Assicurarsi 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 si sta tentando di accedervi utilizzando l'IP pubblico, la connessione verrà rifiutata.

2. Esecuzione del controllo della sintassi della configurazione

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

sudo nginx -t

Se il test fallisce, correggere l'errore identificato, rieseguire il test e quindi ricaricare o riavviare Nginx.

sudo systemctl reload nginx

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

Se Nginx è in esecuzione correttamente sulle porte 80/443, ma l'accesso a un percorso specifico (/api/) genera 'Connection Refused', il problema si trova tra Nginx e il servizio di 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 confermeranno questo.

1. Verifica dei log di errore di Nginx

Esaminare i log di errore di Nginx (solitamente /var/log/nginx/error.log) immediatamente dopo aver tentato la connessione fallita. Cercare messaggi relativi alla direttiva proxy_pass, in particolare quelli che menzionano errori di connessione.

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

Si potrebbe vedere una voce come:

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

2. Verifica dello stato del servizio di backend

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

Passaggi attuabili:

a. Verifica dello stato del servizio di backend: Confermare che l'applicazione di backend sia in esecuzione.

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

3. Test diretto della connettività del backend

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

Supponendo che proxy_pass sia impostato su http://127.0.0.1:8080:

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

# Oppure usando telnet
telnet 127.0.0.1 8080

Se curl o telnet falliscono: Il servizio di backend è sicuramente il problema (non è in ascolto o il suo firewall interno sta bloccando l'accesso a 127.0.0.1).
Se curl o telnet hanno successo: Il problema potrebbe essere un errore sottile nella direttiva proxy_pass (ad esempio, punto e virgola mancante, risoluzione errata del nome host o un mismatch nel protocollo: HTTP vs HTTPS).

Errore comune `proxy_pass`

Assicurarsi che l'indirizzo IP in proxy_pass corrisponda a dove è effettivamente collegata la backend. Se la backend si collega a un IP specifico (ad esempio, 192.168.1.10:8080) ma Nginx utilizza localhost:8080, la connessione fallirà se il collegamento è restrittivo.

Riepilogo dei passaggi chiave per la risoluzione dei problemi

Controllo del sistema: Nginx è in esecuzione (systemctl status nginx)?
Controllo della porta: Nginx è in ascolto sull'IP/porta corretti (ss -tuln)?
Controllo del firewall: La porta in ingresso è aperta sul firewall host (UFW, iptables)?
Controllo della configurazione: Il comando nginx -t ha successo e le direttive listen sono corrette?
Controllo del proxy (se applicabile): Il servizio upstream è in esecuzione e in ascolto sull'IP/porta esatta definita in proxy_pass? Testare la connettività direttamente con curl.

Seguendo questo processo metodico, è possibile identificare rapidamente se l'errore 'Connection Refused' è dovuto a un servizio inattivo, un firewall restrittivo o una configurazione proxy errata, riducendo al minimo i tempi di inattività e ripristinando l'accesso in modo efficiente.