Analisi dei Log di Errore di Nginx per la Risoluzione dei Problemi di Connessione Rifiutata

Analizzare i log di errore di Nginx per la risoluzione dei problemi di connessione rifiutata ti aiuta a passare da una generica pagina 502 a un guasto specifico del backend. La frase "connessione rifiutata" di solito significa che Nginx ha tentato di connettersi a un indirizzo upstream, ma nessun processo ha accettato la connessione.

Questo è diverso da un timeout, un errore DNS o una risposta errata. Una volta riconosciuto il pattern del log, puoi restringere rapidamente la soluzione.

Cosa Significa "Connessione Rifiutata"

Nei log di Nginx, un messaggio comune appare così:

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

Ciò significa che il sistema operativo ha rifiutato il tentativo di connessione. Nginx ha raggiunto l'host di destinazione, ma nulla era in ascolto sulla porta di destinazione, oppure la connessione è stata attivamente rifiutata.

Potresti vederlo quando Nginx fa da proxy a:

proxy_pass http://127.0.0.1:3000;

ma l'applicazione è ferma o in ascolto su una porta diversa.

Questo errore è comune dopo i deployment. Un gestore di processi potrebbe non riuscire a riavviare l'app, un container potrebbe crashare, o una nuova configurazione potrebbe cambiare la porta dell'app senza aggiornare Nginx.

Non trattare ogni 502 come connessione rifiutata. Un messaggio di timeout indica una direzione diversa. Un messaggio di permesso negato spesso punta a socket o policy di sicurezza. Il testo esatto del log è importante.

Trovare il Log di Errore Giusto di Nginx

Il percorso predefinito del log di errore è spesso:

/var/log/nginx/error.log

Ma i blocchi server possono definire log personalizzati:

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

Controlla la configurazione pertinente di Nginx se il log predefinito non mostra voci recenti. Su alcuni sistemi, i messaggi a livello di servizio appaiono anche nel journal di sistema.

Comandi utili includono:

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

e:

journalctl -u nginx -n 100

Durante i test, attiva una richiesta nel browser o con curl, poi controlla immediatamente le righe più recenti del log. Questo rende molto più facile collegare l'errore visibile all'utente con il guasto del backend.

Una buona revisione del log cattura quattro informazioni:

• Il timestamp della richiesta fallita.
• L'indirizzo e la porta upstream.
• Il percorso della richiesta.
• L'errore esatto del sistema, come 111: Connection refused.

Per una risoluzione dei problemi più ampia di Nginx, consulta risoluzione degli errori 502 Bad Gateway di Nginx.

Mappare la Voce del Log all'Upstream

Una riga di log tipica può includere un valore upstream come:

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

Questo ti dice esattamente dove Nginx ha tentato di inviare la richiesta. Ora verifica se qualcosa è in ascolto lì:

ss -ltnp

Cerca 127.0.0.1:3000, 0.0.0.0:3000, o l'indirizzo previsto. Se la porta manca, l'app non è in ascolto dove Nginx se l'aspetta.

Testa l'upstream direttamente:

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

Se fallisce con connessione rifiutata, hai confermato il problema senza Nginx in mezzo.

Se l'app è in esecuzione in Docker, fai attenzione con 127.0.0.1. Dall'host, significa l'host. Dall'interno di un container Nginx, significa il container Nginx stesso. In una configurazione Compose, Nginx di solito deve fare da proxy a un nome di servizio come:

proxy_pass http://app:3000;

purché entrambi i container condividano la stessa rete Docker.

Per i socket Unix, il log può puntare a un percorso invece che a una porta:

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

In tal caso, controlla se il socket esiste e se l'utente worker di Nginx può accedervi.

Cause Comuni e Soluzioni

La causa più comune è un servizio backend fermo. Controllalo con:

systemctl status your-app

Se è fallito, leggi i log dell'app prima di riavviare. Un riavvio potrebbe riportare il sito online, ma i log spiegano perché è fallito.

Un'altra causa comune è una discrepanza di porta. Ad esempio, l'app è passata dalla porta 3000 alla 8080, ma Nginx fa ancora da proxy alla 3000. Correggi il target upstream di Nginx o ripristina la porta prevista dell'app.

Una terza causa è il binding all'interfaccia sbagliata. Un'app in ascolto solo su 127.0.0.1 è raggiungibile da Nginx locale sullo stesso host. Ma se Nginx è in esecuzione in un altro container o un altro server, non sarà raggiungibile attraverso quell'indirizzo di loopback. In queste configurazioni, l'app potrebbe dover fare binding su 0.0.0.0 all'interno della rete privata.

Le regole del firewall possono anche rifiutare o respingere le connessioni, specialmente tra server. Se Nginx fa da proxy a un altro host, conferma che la porta upstream è aperta dalla macchina Nginx, non solo dal tuo laptop.

Infine, i tempi di deployment possono causare brevi errori di connessione rifiutata. Se Nginx invia traffico prima che il nuovo processo dell'app sia pronto, gli utenti potrebbero vedere 502 intermittenti. Un health check, un readiness probe o una strategia di riavvio graduale possono prevenirlo.

Un Flusso Pratico di Risoluzione dei Problemi

Usa questo ordine quando il log dice connessione rifiutata:

1. Copia l'host e la porta upstream dal log di errore di Nginx.
2. Esegui curl verso quell'upstream esatto dal server Nginx.
3. Esegui ss -ltnp per confermare che un processo sia in ascolto.
4. Controlla lo stato del servizio backend e i log dell'applicazione.
5. Confronta il valore proxy_pass di Nginx con l'indirizzo di bind effettivo dell'app.
6. Ricarica Nginx solo dopo che la configurazione è corretta e nginx -t passa.

Questo flusso previene un errore comune: modificare Nginx quando l'app è semplicemente giù. Previene anche l'errore opposto: riavviare l'app ripetutamente quando Nginx punta al posto sbagliato.

Per i comandi di base, consulta comandi di monitoraggio dei log di Nginx.

Quando Chiamare un Professionista

Chiedi aiuto quando gli errori di connessione rifiutata si verificano solo sotto carico, attraverso più upstream, o durante deployment rolling. Questi casi possono coinvolgere la supervisione dei processi, il networking dei container, i health check del load balancer o i limiti di capacità.

Dovresti anche escalare se l'upstream è un servizio di produzione per pagamenti, autenticazione o API rivolte ai clienti. Un recupero rapido è importante, ma preservare i log e capire il fallimento è altrettanto importante.

La connessione rifiutata è uno degli errori di Nginx più chiari una volta che lo leggi attentamente. Trova l'upstream nel log, testa quel target direttamente e correggi il servizio, la porta, l'interfaccia o il percorso di rete che impedisce a Nginx di connettersi. Il log ti dà già il punto di partenza.