Risoluzione degli errori 502 Bad Gateway di Nginx: Guida passo-passo

La risoluzione degli errori 502 Bad Gateway di Nginx inizia con la comprensione che Nginx è solitamente il messaggero, non la fonte originale del problema. Un 502 significa che Nginx ha tentato di comunicare con un servizio upstream e non ha ricevuto una risposta valida.

Quel servizio upstream potrebbe essere un'app Node.js, PHP-FPM, Gunicorn, Puma, un contenitore o un altro server HTTP. Il tuo compito è trovare dove il passaggio fallisce.

Cosa significa un 502 Bad Gateway in Nginx

Nginx si trova comunemente davanti a un server applicativo. Accetta traffico pubblico, gestisce TLS, serve file statici e inoltra richieste dinamiche upstream.

Un 502 appare quando quella connessione upstream fallisce o restituisce qualcosa che Nginx non può utilizzare. Le cause comuni includono:

• Il processo dell'applicazione è fermo.
• Nginx punta alla porta o al socket sbagliato.
• Un socket Unix ha permessi errati.
• Il servizio upstream si blocca durante la richiesta.
• Un firewall o la rete del contenitore blocca la connessione.
• L'upstream invia una risposta HTTP non valida.

Inizia con il percorso esatto della richiesta che fallisce. Se solo /api restituisce 502 ma le pagine statiche si caricano, il tuo servizio di file statici funziona e il proxy o il backend dell'app è probabilmente il problema. Se ogni pagina fallisce, il problema potrebbe essere più ampio, come Nginx, DNS o disponibilità dell'upstream.

Passo 1: Controlla lo stato e la configurazione di Nginx

Prima conferma che Nginx sia in esecuzione:

systemctl status nginx

Poi testa la configurazione:

nginx -t

Se il test di configurazione fallisce, risolvi quello prima di inseguire l'applicazione. Nginx potrebbe ancora funzionare con una configurazione precedente, o potrebbe fallire al ricaricamento.

Dopo un test di configurazione riuscito, ricarica Nginx:

systemctl reload nginx

Non riavviare ciecamente su un server occupato a meno che tu non capisca l'impatto. Ricaricare è solitamente sufficiente dopo una modifica della configurazione ed è meno disruptivo.

Successivamente, ispeziona il blocco server attivo. Cerca proxy_pass, fastcgi_pass o uwsgi_pass. Un tipico reverse proxy potrebbe includere:

location / {
    proxy_pass http://127.0.0.1:3000;
}

Ciò significa che Nginx si aspetta un'applicazione sulla porta locale 3000. Se l'app ascolta effettivamente su 3001, o solo all'interno di una rete Docker, Nginx fallirà.

Per controlli più focalizzati sui comandi, vedi Comandi di test della configurazione di Nginx.

Passo 2: Verifica il servizio upstream

Ora testa l'upstream direttamente dall'host Nginx. Se Nginx fa da proxy a 127.0.0.1:3000, esegui:

curl -i http://127.0.0.1:3000/

Se questo fallisce, il problema non è il browser o il DNS pubblico. Nginx non può raggiungere il backend perché il backend è giù, ascolta da qualche altra parte o rifiuta la richiesta.

Controlla il processo dell'applicazione:

ss -ltnp

Cerca la porta prevista. Se il servizio utilizza un socket Unix, controlla il percorso del socket:

ls -l /run/app/app.sock

L'utente worker di Nginx deve poter accedere a quel socket. Su molti sistemi Linux, Nginx funziona come www-data, nginx o un utente specifico del servizio. Se il socket è di proprietà di un utente diverso e non è leggibile o scrivibile dal gruppo come necessario, Nginx potrebbe registrare un errore di permesso e restituire 502.

Per una configurazione PHP-FPM, conferma che il pool sia in esecuzione:

systemctl status php-fpm

Il nome del servizio potrebbe includere una versione, come php8.2-fpm, a seconda della distribuzione.

Passo 3: Leggi il log degli errori di Nginx

Il log degli errori di Nginx di solito ti dice quale modalità di fallimento stai affrontando. I messaggi di log comuni includono:

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

Ciò significa che Nginx ha raggiunto l'host ma nessuno ha accettato la connessione su quella porta.

upstream timed out while reading response header from upstream

Ciò significa che Nginx si è connesso, ma il backend non ha risposto in tempo.

permission denied while connecting to upstream

Questo spesso indica permessi del socket Unix o controlli di sicurezza come SELinux.

Controlla gli errori recenti con:

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

Su sistemi basati su systemd, puoi anche controllare:

journalctl -u nginx -n 100

Abbina il timestamp nel log con il momento della tua richiesta dal browser. Questo ti impedisce di inseguire vecchi errori che non sono più rilevanti.

Per un flusso di lavoro più approfondito sui log, vedi analisi dei log degli errori di Nginx.

Passo 4: Risolvi le cause principali più comuni

Una volta che conosci la modalità di fallimento, applica la correzione più piccola che corrisponde.

Se l'app non è in esecuzione, avvia o riavvia il servizio dell'applicazione:

systemctl restart your-app

Poi testa l'upstream con curl prima di testare attraverso Nginx.

Se Nginx punta alla porta sbagliata, aggiorna il target proxy_pass e ricarica Nginx. Assicurati anche che la tua app e Nginx concordino su IPv4 rispetto a IPv6. Un'app che ascolta su 127.0.0.1 non è la stessa di una che ascolta solo su ::1.

Se Docker è coinvolto, controlla se Nginx funziona sull'host o all'interno di un contenitore. 127.0.0.1 all'interno di un contenitore punta a quel contenitore, non all'host. Potresti aver bisogno di un nome del servizio Docker, una rete bridge o una porta pubblicata.

Se l'upstream va in timeout, controlla i log dell'applicazione. Il backend potrebbe essere bloccato su query del database, chiamate API esterne o lavoro di avvio. Aumentare i timeout di Nginx può nascondere i sintomi, ma non risolverà un'app rotta o sovraccarica.

Quando chiamare un professionista

Coinvolgi un ingegnere senior o il provider di hosting quando gli errori 502 influenzano la produzione e la causa non è ovvia dopo aver controllato log, stato dell'upstream e deploy recenti. Chiedi anche aiuto se il problema tocca bilanciatori di carico, orchestrazione di contenitori, policy SELinux o ottimizzazione dei timeout per alto traffico.

Per i sistemi di produzione, evita riavvii casuali ripetuti. Possono cancellare le prove e rendere più difficile capire l'interruzione.

Un errore 502 Bad Gateway è risolvibile quando tracci il percorso della richiesta in ordine. Conferma che Nginx sia valido, testa l'upstream direttamente, leggi la riga esatta del log degli errori e applica la correzione che corrisponde al fallimento. Questo approccio è più veloce e più sicuro che modificare i timeout o riavviare i servizi ciecamente.