Risoluzione degli errori comuni di Nginx: una guida pratica

La risoluzione degli errori comuni di Nginx diventa molto più semplice quando smetti di trattare il codice di stato come l'unico problema. Un 502 potrebbe essere un'app crashata, un percorso socket sbagliato o un backend che ha restituito header errati. Un 403 potrebbe essere dovuto a permessi dei file, un file indice mancante o una regola di rifiuto che ha corrisposto più del previsto.

Inizia con le prove: il log degli errori, il log degli accessi, nginx -t e i log del backend se Nginx sta facendo da proxy a un'app. Indovinare solo dalla pagina del browser è una perdita di tempo.

Inizia con i controlli rapidi

Esegui questi comandi prima di modificare la configurazione:

sudo nginx -t
sudo systemctl status nginx --no-pager
sudo tail -n 80 /var/log/nginx/error.log
sudo tail -n 80 /var/log/nginx/access.log

nginx -t ti dice se la configurazione può essere analizzata. Lo stato del servizio ti dice se Nginx è in esecuzione. I log ti dicono cosa Nginx ha visto durante la gestione della richiesta.

Se il problema è legato a un singolo URL, riproducilo con curl in modo da vedere chiaramente header e stato:

curl -I https://example.com/problem/path
curl -v https://example.com/problem/path

Se il problema si verifica solo per un nome host specifico, includilo:

curl -I -H 'Host: app.example.com' http://127.0.0.1/

Questo separa il routing di Nginx dal comportamento di DNS, CDN e bilanciatore di carico.

Nginx non si avvia o non si ricarica

Un fallimento all'avvio è solitamente un errore di sintassi, una direttiva duplicata nel contesto sbagliato, un file include mancante o un problema con il percorso del certificato.

Usa:

sudo nginx -t
sudo journalctl -u nginx -n 100 --no-pager

I messaggi comuni sono diretti:

• unknown directive significa un errore di battitura, un modulo non supportato o una direttiva posizionata nella build sbagliata di Nginx.
• directive is not allowed here significa che la direttiva è nel contesto sbagliato, ad esempio mettere una direttiva solo http all'interno di server.
• cannot load certificate significa che il percorso è sbagliato, il file è mancante o i permessi impediscono a Nginx di leggerlo.
• bind() to 0.0.0.0:80 failed spesso significa che un altro processo sta già usando la porta.

Controlla le porte con:

sudo ss -tulnp | grep ':80\|:443'

Non ricaricare finché nginx -t non passa. Un ricaricamento fallito di solito mantiene in esecuzione il vecchio processo worker, ma un riavvio fallito può far cadere il sito.

(13: Permission denied) e 403 Forbidden

Permission denied appare nel log degli errori quando l'utente worker di Nginx non può leggere un file o attraversare una directory. Un browser potrebbe vedere 403 Forbidden.

Prima trova l'utente worker:

grep -R '^user ' /etc/nginx/nginx.conf

Su Debian e Ubuntu è spesso www-data. Su sistemi compatibili con RHEL è spesso nginx.

Per una root statica come /var/www/html, Nginx ha bisogno del permesso di esecuzione su ogni directory padre e del permesso di lettura sul file:

sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

Evita di eseguire automaticamente chown -R www-data:www-data sulle directory dell'applicazione. Potrebbe far scomparire l'errore mentre dai al server web un permesso di scrittura di cui non ha bisogno. Un pattern più sicuro è mantenere separata la proprietà del deploy e concedere a Nginx solo l'accesso in lettura.

Se i permessi sembrano a posto, controlla se la richiesta è per una directory senza file indice:

location / {
    root /var/www/html;
    index index.html index.htm;
}

Se /docs/ non ha index.html e autoindex è disattivato, Nginx restituisce 403. Questo è un comportamento corretto.

SELinux può anche causare errori di tipo permesso sui sistemi della famiglia RHEL. Se i permessi dei file sono corretti ma Nginx non riesce ancora a leggere o fare da proxy, controlla i log di audit prima di disabilitare SELinux:

sudo ausearch -m avc -ts recent

(111: Connection refused) e 502 Bad Gateway

Connection refused significa che Nginx ha tentato di connettersi a un upstream e il target lo ha rifiutato attivamente. L'app potrebbe essere giù, in ascolto su un indirizzo diverso o utilizzare un percorso socket che non esiste.

Per questo proxy:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

controlla:

sudo ss -tulnp | grep 3000
curl -I http://127.0.0.1:3000
sudo systemctl status your-app --no-pager

Se Nginx usa un socket Unix, controlla il file socket:

ls -l /run/gunicorn/app.sock

L'utente worker deve essere in grado di leggere e scrivere il socket.

Un 502 Bad Gateway è più ampio. Nginx ha raggiunto qualcosa a monte, ma la risposta era invalida, incompleta, chiusa troppo presto o non come Nginx si aspettava. Controlla i log dell'app allo stesso timestamp dell'errore di Nginx. La corrispondenza del timestamp è importante; altrimenti finisci per inseguire un'eccezione del giorno prima.

Per PHP-FPM, verifica che fastcgi_pass corrisponda al socket o alla porta del pool configurato. Ad esempio:

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Poi controlla:

sudo systemctl status php8.3-fpm --no-pager
ls -l /run/php/php8.3-fpm.sock

504 Gateway Timeout

Un 504 significa che Nginx ha aspettato l'upstream e non ha ricevuto una risposta tempestiva. Aumentare i timeout può essere valido per report, importazioni o operazioni di amministrazione lente, ma non dovrebbe essere l'unica soluzione per un endpoint pubblico che è lento su ogni richiesta.

location /api/reports/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 10s;
    proxy_send_timeout 60s;
    proxy_read_timeout 180s;
}

Poi guarda i tempi del backend. Aggiungi i tempi dell'upstream ai log degli accessi se non li hai già:

log_format proxy_timing '$remote_addr "$request" $status '
                        'request_time=$request_time '
                        'upstream_time=$upstream_response_time';

Se $upstream_response_time è alto, probabilmente l'app o il database sono il punto su cui concentrarsi. Se Nginx mostra timeout ma i log dell'app dicono che ha risposto rapidamente, controlla i salti di rete, il networking dei container, la risoluzione DNS all'interno dell'host o un bilanciatore di carico tra Nginx e l'app.

413 Request Entity Too Large

413 è solitamente semplice: il corpo della richiesta è più grande di quanto Nginx permetta. Upload, payload JSON grandi e invii di moduli possono innescarlo.

Imposta client_max_body_size nel posto più ristretto utile:

server {
    server_name example.com;

    location /upload/ {
        client_max_body_size 100M;
        proxy_pass http://127.0.0.1:3000;
    }
}

Impostare un limite globale enorme è raramente una buona idea. La maggior parte delle rotte non ne ha bisogno, e corpi più grandi consentiti aumentano la quantità di lavoro che un client malintenzionato può imporre al tuo stack.

Errori SSL e dei certificati

I fallimenti TLS spesso appaiono diversi a seconda di dove li noti. Nginx potrebbe non riuscire a ricaricare, i browser potrebbero avvisare sul certificato o i client potrebbero fallire un handshake.

Controlla le date del certificato:

openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates -subject -issuer

Controlla cosa presenta il servizio pubblico:

openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject -issuer

Se questi due comandi mostrano certificati diversi, un bilanciatore di carico, CDN o host diverso potrebbe servire il traffico.

400 Bad Request e problemi di header

400 di solito significa che Nginx non ha accettato la sintassi della richiesta. Con browser reali è meno comune, ma bot, client vecchi, proxy insoliti o header sovradimensionati possono causarlo.

Cerca messaggi come client sent too large request header. Se un cookie SSO o di applicazione legittimo è troppo grande, potresti dover regolare le impostazioni del buffer degli header. Tratta questo come una correzione mirata, non come prima risposta. I cookie sovradimensionati sono spesso meglio risolti nell'applicazione.

Un ordine pratico delle operazioni

Quando un problema di Nginx è in corso, usa un ordine ripetibile:

1. Conferma l'URL esatto, l'host, il codice di stato e l'ora.
2. Controlla nginx -t e lo stato del servizio.
3. Abbina la richiesta nel log degli accessi.
4. Abbina lo stesso timestamp nel log degli errori.
5. Se stai facendo da proxy, controlla lo stato e i log del servizio upstream.
6. Testa l'upstream direttamente dall'host Nginx.
7. Apporta la modifica di configurazione più piccola che si adatti alle prove.
8. Esegui nginx -t, ricarica e osserva i log mentre ripeti il test.

La maggior parte dei problemi di Nginx diventano ordinari una volta che sai dove si è verificato il fallimento: prima di Nginx, all'interno di Nginx, tra Nginx e l'upstream o all'interno del servizio upstream.