SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Configurazione nginx reverse proxy: guida completa

Configura nginx riga per riga su Ubuntu 24.04: proxy_pass, 4 header essenziali, WebSocket, slash finali, upload e verifica con nginx -t.

Cosa fa una configurazione nginx per il reverse proxy

Un reverse proxy nginx riceve le richieste sulle porte 80 e 443 e inoltra ciascuna richiesta a un'applicazione già in ascolto su una porta locale. Quindi restituisce al browser la risposta dell'applicazione. La configurazione è costituita da un unico blocco `server` ed è breve. Quasi tutta la complessità è concentrata in cinque o sei righe che comunicano all'applicazione quale fosse il client reale e quale protocollo abbia usato.

Tutto quanto segue viene configurato da zero su Ubuntu 24.04, usando il pacchetto nginx della distribuzione. Il punto di partenza è un'applicazione che risponde già su `127.0.0.1:3000`. Se non hai ancora scelto un proxy, leggi prima il confronto tra nginx, Caddy e Traefik. Di seguito è mostrata la configurazione nginx, riga per riga.

Esegui queste configurazioni sul tuo server. Verifica ogni modifica con `sudo nginx -t` prima di ricaricare la configurazione e leggi l'output.

Dove nginx conserva la configurazione su Ubuntu

sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/

Il file principale è /etc/nginx/nginx.conf. Imposta le opzioni globali all'interno di un blocco http { } e include quindi due directory: /etc/nginx/conf.d/*.conf e /etc/nginx/sites-enabled/*. Su Ubuntu e Debian si crea un file per ogni sito in /etc/nginx/sites-available/ e lo si abilita creando un link simbolico in /etc/nginx/sites-enabled/. Eliminando il link simbolico si disabilita il sito, ma il file rimane disponibile.

Due direttive utilizzate più avanti funzionano solo nel contesto http, mai all'interno di un blocco server: map e upstream. Inseriscile in un file dedicato sotto /etc/nginx/conf.d/, perché questa directory viene inclusa al livello http.

Il pacchetto installa un sito abilitato chiamato default. È contrassegnato come default_server, quindi risponde a ogni richiesta il cui header Host non corrisponde a nessun server_name presente nella configurazione. Finché rimane abilitato, una richiesta che non corrisponde ai tuoi nomi viene indirizzata a questo sito anziché alla tua applicazione. Rimuovi il link simbolico quando il tuo sito funziona correttamente.

sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Il blocco server minimo per fare da proxy a un'applicazione

server {
    listen 80;
    listen [::]:80;
    server_name app.example.com;

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

Salvare il file con questo contenuto come /etc/nginx/sites-available/app.example.com, quindi abilitarlo e caricarlo.

sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -sI -H 'Host: app.example.com' http://127.0.0.1/

listen 80; associa il blocco a IPv4 e listen [::]:80; lo associa a IPv6. Se si omette la seconda riga, ogni connessione IPv6 al server viene rifiutata. Un browser dual-stack il cui lookup DNS (domain name system) restituisce un record AAAA in genere passa a IPv4 e nasconde il problema, ma un visitatore che usa solo IPv6, oppure un client che prova soltanto il primo indirizzo ricevuto, vede una connessione rifiutata mentre tutti gli utenti IPv4 vedono un sito funzionante. Il bug report ricevuto dice: "da me funziona".

server_name viene confrontato con l'header Host inviato dal browser. È possibile elencare più nomi, separati da spazi. Se nessun blocco corrisponde, nginx usa il blocco default_server, motivo per cui era necessario rimuovere il sito fornito dal pacchetto.

location / esegue una corrispondenza per prefisso sul percorso della richiesta, mentre / corrisponde a ogni percorso. proxy_pass è l'indirizzo a cui nginx apre una connessione. Mantenere l'applicazione in ascolto su 127.0.0.1, in modo che l'unico accesso passi da nginx. Se l'applicazione è eseguita in un container, pubblicarla come 127.0.0.1:3000:3000 e non come 3000:3000, perché Docker scrive regole proprie e pubblica le porte direttamente oltre ufw, quindi una porta pubblicata senza ulteriori restrizioni è raggiungibile da Internet indipendentemente dalla configurazione di ufw. Docker documenta la propria catena DOCKER-USER come punto in cui filtrare questo traffico, ma associare il servizio a 127.0.0.1 è la soluzione più semplice.

La riga curl invia l'header Host corretto dal server stesso, quindi è possibile testare il blocco prima che il DNS punti a una destinazione.

Cosa invia nginx al backend quando non si specifica altro

proxy_pass da solo nasconde quattro informazioni all'applicazione.

Il pacchetto nginx 1.24.0 incluso in Ubuntu 24.04 comunica con il backend tramite HTTP/1.0 per impostazione predefinita e invia Connection: close. Ogni richiesta apre quindi una nuova connessione upstream e non è possibile alcun aggiornamento del protocollo. nginx 1.29.7, rilasciato a marzo 2026, ha modificato queste impostazioni predefinite: da questa versione nginx comunica con l'upstream tramite HTTP/1.1, non invia alcun header Connection e riutilizza le connessioni dal pool invece di aprirne una nuova per ogni richiesta. Anche in questo caso, per un aggiornamento WebSocket sono comunque necessari gli header mostrati più avanti.

L'header Host viene riscritto con il valore di proxy_pass, ovvero 127.0.0.1:3000. Un'applicazione che costruisce link assoluti a partire da Host genera quindi link che nessuno all'esterno del server può aprire.

La connessione che raggiunge l'applicazione proviene da nginx, quindi l'applicazione vede come indirizzo client 127.0.0.1. Ogni riga di log e ogni limite di frequenza applicato dall'applicazione registrano quindi il proxy anziché il visitatore.

L'applicazione non può sapere che il browser ha usato HTTPS, perché la connessione ricevuta è HTTP semplice su un indirizzo di loopback.

Quattro righe risolvono tutti questi problemi.

I quattro header da impostare e le informazioni che rendono disponibili al backend

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

    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Host contiene il nome digitato dal visitatore. $host è il nome della richiesta, senza la porta e con le lettere convertite in minuscolo. Impostarlo consente all'applicazione di generare URL assoluti corretti, ad esempio il redirect dopo l'accesso o il link contenuto in un'email per reimpostare la password. Se lo si omette, l'applicazione considera 127.0.0.1:3000 come il proprio nome. Il valore predefinito di nginx, proxy_redirect, riscrive un header Location o Refresh che punta all'indirizzo proxy_pass. Per questo, un semplice redirect dopo l'accesso in genere continua a portare alla destinazione corretta. Tuttavia, gli URL assoluti che l'applicazione inserisce nelle proprie pagine e nelle email, come il link per reimpostare la password, puntano a 127.0.0.1:3000, un indirizzo che il browser del visitatore non può aprire. Se l'applicazione deve includere anche la porta, perché viene pubblicata sulla porta 8080, usare $http_host, che contiene l'header esattamente come inviato dal client.

X-Real-IP contiene un solo valore: $remote_addr, l'indirizzo da cui nginx ha accettato la connessione. Le applicazioni lo usano nei propri log di accesso e per applicare il proprio rate limiting.

X-Forwarded-For contiene un elenco. $proxy_add_x_forwarded_for aggiunge $remote_addr al valore che il client aveva già inserito in quell'header. Il valore è quindi separato da virgole e l'elemento aggiunto da nginx è l'ultimo. Questo dettaglio determina se l'header può essere considerato attendibile: un client può inviare qualsiasi X-Forwarded-For, quindi un'applicazione che legge il primo elemento può ricevere un indirizzo arbitrario. Quando nginx è il server edge, scrivere invece $remote_addr e scartare il valore inviato dal client. Quando davanti a nginx è presente una CDN o un altro proxy, usare set_real_ip_from e real_ip_header del modulo realip, in modo che $remote_addr diventi l'indirizzo effettivo del client.

X-Forwarded-Proto contiene http o https. I framework lo leggono per decidere se contrassegnare i cookie come Secure e se forzare un redirect verso HTTPS. Se lo si omette su un sito TLS e un'applicazione configurata per forzare HTTPS riceve http, risponde con un redirect all'indirizzo HTTPS, riceve la richiesta successiva tramite nginx, vede ancora http e la reindirizza nuovamente. Il browser interrompe la procedura e mostra ERR_TOO_MANY_REDIRECTS.

Ripetere queste quattro righe in ogni location porta a differenze indesiderate tra le configurazioni. Inserirle in un unico file e includerlo.

# /etc/nginx/snippets/proxy-headers.conf
proxy_set_header Host              $host;
proxy_set_header X-Real-IP         $remote_addr;
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
location / {
    include snippets/proxy-headers.conf;
    proxy_pass http://127.0.0.1:3000;
}

L'ereditarietà in questo caso presenta un problema. Una location eredita le direttive proxy_set_header dal relativo blocco server solo se non ne definisce alcuna. Se si aggiunge un solo proxy_set_header all'interno della location, tutti gli header definiti a livello server vengono rimossi per quella location. Mantenere quindi tutte le direttive allo stesso livello oppure include lo snippet in ogni location che usa proxy.

Perché la mia applicazione WebSocket si connette e poi si disconnette?

Perché le impostazioni predefinite impediscono l'upgrade e il timeout di lettura predefinito chiude un tunnel inattivo dopo 60 secondi. Una connessione WebSocket inizia come una richiesta HTTP che contiene Upgrade: websocket e Connection: Upgrade. Sono header hop-by-hop: il proxy dovrebbe consumarli invece di inoltrarli. Inoltre, in Ubuntu 24.04, nginx 1.24.0 usa per impostazione predefinita il protocollo upstream HTTP/1.0, che non supporta alcun meccanismo di upgrade. Entrambi devono essere ripristinati manualmente.

La direttiva map deve trovarsi nel contesto http, in un file dedicato.

# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Poi si configura il blocco location.

location / {
    include snippets/proxy-headers.conf;
    proxy_pass http://127.0.0.1:3000;

    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

La direttiva map permette a una sola location di gestire entrambi i tipi di traffico. In una richiesta ordinaria $http_upgrade è vuoto, quindi $connection_upgrade diventa close. In una richiesta di upgrade contiene websocket, quindi l'header inviato all'upstream è Connection: upgrade. Impostare direttamente proxy_set_header Connection "upgrade"; invierebbe quell'header anche per ogni richiesta di una normale pagina. Alcuni backend rispondono a questo tipo di richiesta con 400.

proxy_http_version 1.1; è il valore predefinito a partire da nginx 1.29.7. In queste versioni la riga non modifica il comportamento e non causa problemi. Nel pacchetto 1.24.0 è necessaria. Le righe Upgrade e Connection sono necessarie in tutte le versioni, perché nginx non inoltra automaticamente questi due header.

proxy_read_timeout è la causa dei messaggi del tipo «si carica, poi smette di aggiornarsi». Il valore predefinito è 60 secondi e misura l'intervallo tra due letture dal backend, non la durata della connessione. Se una connessione WebSocket rimane inattiva per 60 secondi, nginx la chiude e la console del browser mostra la chiusura del socket con codice 1006. Le applicazioni che inviano autonomamente un heartbeat più spesso di una volta al minuto non riscontrano il problema. Quelle che non lo fanno si interrompono allo scadere del minuto. Il problema emerge prima negli editor collaborativi e nei dashboard; un'istanza n8n self-hosted dietro HTTPS è un esempio comune.

Perché una barra finale in proxy_pass modifica gli URL?

La regola è una sola frase. Se proxy_pass termina con un URI (uniform resource identifier), anche un semplice /, nginx rimuove la parte del percorso della richiesta che corrispondeva al prefisso location e la sostituisce con quell'URI. Se proxy_pass si ferma all'host e alla porta, il percorso della richiesta viene inoltrato senza modifiche.

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

Una richiesta a /app/status arriva al backend come /status.

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

Una richiesta a /app/status arriva al backend come /app/status.

La forma da usare dipende dall'applicazione. Un'applicazione con un'impostazione base-path o sub-folder richiede la seconda forma, configurando l'impostazione con /app. Un'applicazione che non gestisce i prefissi richiede la prima. La prima forma presenta subito uno svantaggio: l'HTML restituito dall'applicazione contiene ancora percorsi assoluti come /static/main.css, il browser li richiede dalla radice del sito, nessuna location corrisponde e la pagina viene visualizzata senza stile. Nella scheda di rete del browser, queste richieste per le risorse restituiscono 404. La soluzione consiste nell'impostare il base-path dell'applicazione oppure nell'aggiungere una seconda location /static/ che punti allo stesso backend.

Una location basata su espressione regolare non può contenere un URI in proxy_pass. sudo nginx -t rifiuta la configurazione e indica il motivo: "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block.

Questa intera classe di problemi scompare quando ogni applicazione riceve un nome proprio, app.example.com, e viene inoltrata da location /. I sottopercorsi sono utili solo quando non è possibile aggiungere record DNS.

Come metto più backend dietro un unico nome?

Con un blocco upstream. Appartiene al contesto http, quindi scrivilo sopra il blocco server nello stesso file oppure in /etc/nginx/conf.d/.

upstream app_backend {
    least_conn;
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:3001 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

La direttiva location lo indica quindi con: proxy_pass http://app_backend;.

Il metodo predefinito è round robin. least_conn invia ogni richiesta al backend con il minor numero di connessioni attive, una scelta adatta quando le richieste hanno durata variabile. ip_hash associa l'indirizzo di un client a un singolo backend. Ti serve ip_hash quando l'applicazione conserva le sessioni nella propria memoria, perché il round robin su due backend di questo tipo disconnette gli utenti in modo casuale quando le richieste arrivano all'istanza che non li ha mai visti. Spostare le sessioni in uno storage condiviso è la soluzione migliore.

max_fails=3 fail_timeout=30s significa che tre tentativi non riusciti nell'arco di 30 secondi escludono quel server per 30 secondi. Quando tutti i server del blocco si trovano in questo stato, i client ricevono 502 e il log degli errori contiene no live upstreams while connecting to upstream.

keepalive 32 mantiene aperte fino a 32 connessioni inattive verso i backend per ogni processo worker, eliminando l'handshake TCP dalla maggior parte delle richieste. In Ubuntu 24.04, con la versione 1.24.0, questa direttiva abilita la cache. A partire da nginx 1.29.7, la cache è abilitata per impostazione predefinita, ma il valore documentato è keepalive 32 local; e il parametro local impedisce di condividere le connessioni memorizzate nella cache tra location diverse. Nelle versioni 1.29.7 e successive, quindi, un keepalive 32; senza parametri non si limita a ribadire il valore predefinito: omettendo local, consente a qualsiasi location che inoltra le richieste allo stesso server upstream di riutilizzare una connessione del pool, modificando il comportamento predefinito. In queste versioni, ometti la direttiva oppure scrivi keepalive 32 local; per mantenere il valore predefinito; usala senza parametri solo se vuoi abilitare questa condivisione. Il parametro local è stato introdotto in 1.29.7, quindi il pacchetto 1.24.0 non lo accetta. Per i backend HTTP, la configurazione consigliata da nginx per il pool consiste nell'impostare proxy_http_version su 1.1 (oppure su 2, in nginx 1.29.4 e versioni successive) e nel cancellare l'header Connection prima di inviarlo al backend. nginx documenta anche le connessioni persistenti HTTP/1.0, ottenute inviando Connection: Keep-Alive a un backend che le supporta, ma indica che questo metodo non è consigliato. A partire dalla versione 1.29.7, entrambe le parti della configurazione consigliata sono predefinite. In 1.24.0, aggiungi manualmente proxy_http_version 1.1; e proxy_set_header Connection ""; alla location; in caso contrario nginx continua a inviare HTTP/1.0 con Connection: close e il pool non viene mai riutilizzato. Se la stessa location usa anche la mappa WebSocket, modifica il caso vuoto da close a una stringa vuota, in modo che le richieste ordinarie non inviino alcun header Connection e la connessione del pool venga riutilizzata.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      '';
}

I nomi all'interno di un blocco upstream vengono risolti all'avvio di nginx. Se il backend è un container che riceve un nuovo indirizzo quando viene riavviato, nginx continua a usare il vecchio indirizzo finché non lo ricarichi. nginx 1.27.3 e versioni successive possono seguire questi cambiamenti senza un reload, tramite un resolver, un zone nel blocco upstream e il parametro resolve su ogni riga server, ma il pacchetto 1.24.0 è precedente a questa funzionalità. All'interno di una rete Docker puoi spostare la risoluzione al momento della richiesta usando il resolver integrato.

resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;

Quando i container vengono creati e rimossi abbastanza spesso da costringerti a modificare continuamente nginx, è preferibile usare un proxy che legga le label dei container. Traefik davanti a diverse applicazioni Docker Compose crea le route direttamente dai container.

Perché i caricamenti falliscono con 413 Request Entity Too Large?

client_max_body_size è impostato su 1 megabyte per impostazione predefinita. nginx rifiuta un corpo della richiesta più grande con un errore 413 e registra client intended to send too large body nel log degli errori. Aumentare il valore nel blocco server oppure nella location in cui vengono eseguiti i caricamenti.

client_max_body_size 512m;

Il valore 0 disabilita completamente il controllo. Con 512m, nginx continua a rifiutare i corpi delle richieste che superano il limite, quindi un errore 413 che persiste dopo questa modifica non indica che la causa sia il backend. Controllare il valore effettivo di client_max_body_size nella location che gestisce il caricamento e il log degli errori di nginx prima di verificare il limite di caricamento dell'applicazione.

Per impostazione predefinita, nginx legge l'intero corpo della richiesta prima di aprire la connessione upstream e scrive prima su disco, in un file temporaneo, i dati di grandi dimensioni. In questo modo l'applicazione è protetta dai client lenti, perché il backend riceve il caricamento alla massima velocità locale. Per i caricamenti molto grandi è possibile usare lo streaming.

proxy_request_buffering off;

Per i caricamenti con codifica chunked su HTTP/1.1 nel pacchetto 1.24.0, impostare anche proxy_http_version 1.1; in quella location; in caso contrario nginx continua a usare il buffering del corpo. Il backend riceve quindi il corpo man mano che arriva e deve essere in grado di gestirlo. Quando nginx inizia a inviare il corpo all'upstream, non può riprovare la richiesta su un altro upstream.

client_body_timeout, impostato su 60 secondi per impostazione predefinita, si applica all'intervallo tra due letture successive del corpo, non all'intero caricamento. Un caricamento lento ma costante può completarsi entro questo limite. Un caricamento in stallo viene interrotto.

Buffering delle risposte e impostazione che interrompe l'output in tempo reale

proxy_buffering è abilitato per impostazione predefinita ed è generalmente ciò che serve. nginx legge la risposta dall'applicazione alla velocità con cui l'applicazione la produce, la memorizza e la invia a un client lento seguendo il ritmo del client. Il worker dell'applicazione termina prima, invece di rimanere occupato per l'intera durata del download lento.

Questo interrompe le risposte in streaming. Gli eventi Server-Sent Events e l'output dei log in tempo reale non mostrano nulla al lettore finché il buffer non si riempie. Disabilita il buffering solo in quella location.

proxy_buffering off;

Se controlli l'applicazione, la soluzione migliore consiste nell'inviare l'header X-Accel-Buffering: no soltanto nelle risposte in streaming. nginx legge quell'header per ogni risposta e disabilita il buffering solo per quella risposta, mantenendo il vantaggio per le pagine ordinarie.

Quando il log degli errori contiene upstream sent too big header while reading response header from upstream, gli header della risposta non entravano in un singolo buffer. proxy_buffer_size è impostato per impostazione predefinita su una singola pagina di memoria, di dimensioni pari a 4 o 8 kilobyte a seconda della piattaforma. Cookie lunghi o header di autenticazione di grandi dimensioni possono superare questo limite. Aumenta entrambi i valori.

proxy_buffer_size 16k;
proxy_buffers 8 16k;

Dove va inserito TLS in questa configurazione?

In nginx, davanti a tutto ciò che è riportato sopra. TLS (transport layer security) termina sul proxy e la connessione da nginx all'applicazione resta in HTTP non cifrato sull'indirizzo di loopback, dove nessun altro host della rete può leggerla. L'applicazione rileva che il visitatore ha usato HTTPS tramite X-Forwarded-Proto, il quarto dei quattro header.

Non inserire manualmente i percorsi dei certificati. Punta il record DNS al server, apri il firewall e lascia che Certbot modifichi questo stesso server block: aggiunge la riga listen 443 ssl con i percorsi ssl_certificate e un redirect dalla porta 80. Emettere un certificato Let's Encrypt per nginx con Certbot descrive l'emissione e il timer per il rinnovo.

sudo ufw allow 'Nginx Full'
sudo ufw status

Nginx Full è un profilo applicativo installato dal pacchetto nginx e apre contemporaneamente la porta 80 e la porta 443. La porta 80 deve restare aperta per la challenge HTTP-01 del rinnovo, anche dopo che tutti i visitatori vengono reindirizzati a HTTPS.

Testare la configurazione, quindi ricaricarla

sudo nginx -t
sudo systemctl reload nginx

nginx -t analizza ogni file incluso e indica se il test è riuscito oppure stampa il file e la riga in cui si è arrestato. Leggere questo output prima di ricaricare la configurazione. Un ricaricamento con una configurazione non valida non viene applicato: nginx continua a usare la configurazione precedente, quindi il sito resta attivo mentre la modifica non produce alcun effetto senza segnalarlo. systemctl restart si comporta in modo diverso e peggiore, perché un riavvio arresta prima il server in esecuzione. Se la configurazione contiene errori, nginx resta quindi completamente arrestato. Usare il ricaricamento per impostazione predefinita e riservare il riavvio alle rare modifiche che lo richiedono.

sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'

La riga ss mostra quale processo detiene ciascuna porta. In questo modo è possibile verificare che l'applicazione sia effettivamente in ascolto dove indica proxy_pass.

Gli errori che incontrerai realmente

502 Bad Gateway, con connect() failed (111: Connection refused) while connecting to upstream nel log degli errori. All'indirizzo indicato in proxy_pass non è in ascolto alcun processo. L'applicazione è arrestata, è associata a un'altra porta oppure è associata a un indirizzo interno del container che l'host non può raggiungere.

502 con no live upstreams while connecting to upstream. Tutti i server nel blocco upstream sono attualmente contrassegnati come non disponibili da max_fails. Ripristina i backend. nginx riproverà a utilizzarli alla scadenza di fail_timeout.

504 Gateway Time-out, con upstream timed out (110: Connection timed out) while reading response header from upstream. Il backend ha accettato la connessione, ma non ha inviato dati per proxy_read_timeout secondi. Aumentare il timeout è corretto per un report realmente lento, ma non per un'applicazione bloccata.

Ogni percorso restituisce 404 dall'applicazione. La regola per la slash finale ha riscritto il percorso. Confronta il percorso registrato nei log dell'applicazione con quello richiesto.

Risponde un sito diverso. server_name non corrisponde all'header Host, quindi la richiesta è ricaduta nel blocco default_server.

La pagina viene caricata, poi l'interfaccia si blocca dopo circa un minuto. Questo è il caso WebSocket: manca la gestione di Upgrade oppure proxy_read_timeout è ancora impostato su 60 secondi.

FAQ

Perché nginx restituisce 502 Bad Gateway dopo l'aggiunta di proxy_pass?

nginx non è riuscito ad aprire una connessione all'indirizzo indicato in proxy_pass. Il log degli errori in /var/log/nginx/error.log indica la causa: connect() failed (111: Connection refused) while connecting to upstream significa che non c'è alcun processo in ascolto, mentre no live upstreams significa che ogni server in un blocco upstream è stato contrassegnato come non disponibile. Esegui sudo ss -lntp | grep 3000 per verificare quale processo occupa la porta e a quale indirizzo è associato. Se un'applicazione è associata a un indirizzo interno del container o a una porta diversa da quella specificata, questo errore si verifica sempre.

Perché l'applicazione si disconnette dopo circa un minuto dietro nginx?

La connessione è un WebSocket e proxy_read_timeout mantiene ancora il valore predefinito di 60 secondi, che misura l'intervallo tra due letture dal backend. nginx chiude il socket inattivo e la console del browser segnala il codice di chiusura 1006. Imposta proxy_http_version 1.1 (il valore predefinito da nginx 1.29.7, ma non nel pacchetto 1.24.0 distribuito con Ubuntu 24.04), inoltra Upgrade e Connection tramite un map su $http_upgrade e aumenta proxy_read_timeout a un valore come 3600s. Senza l'header Upgrade l'upgrade non avviene mai, quindi l'applicazione ricorre al polling oppure non mostra aggiornamenti in tempo reale.

La barra finale in proxy_pass è importante?

Sì, perché modifica il percorso ricevuto dal backend. Con location /app/ e proxy_pass http://127.0.0.1:3000/, una richiesta per /app/status arriva al backend come /status, perché qualsiasi URI successivo a host e porta sostituisce il prefisso della location corrispondente. Se rimuovi la barra finale, la stessa richiesta arriva come /app/status. Rimuovere il prefisso spesso interrompe i collegamenti agli asset dell'applicazione, che restano assoluti e restituiscono quindi 404 alla radice del sito. Per un'applicazione con un'impostazione base-path è quindi preferibile la forma che inoltra il percorso completo.

Perché il log dell'applicazione riporta 127.0.0.1 come indirizzo IP di ogni visitatore?

Perché la connessione ricevuta dall'applicazione proviene effettivamente da nginx sull'indirizzo di loopback. L'indirizzo del visitatore arriva all'applicazione solo tramite un header che imposti: proxy_set_header X-Real-IP $remote_addr; per un singolo valore e proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; per la catena concatenata. Devi quindi configurare l'applicazione affinché consideri attendibili questi header. Tieni presente che un client può inviare un proprio X-Forwarded-For; quando nginx è il server edge, sovrascrivilo con $remote_addr anziché concatenarlo.

Devo usare TLS sulla connessione tra nginx e l'applicazione?

Non se l'applicazione viene eseguita sullo stesso server ed è associata a 127.0.0.1, perché questo traffico non lascia mai la macchina. Termina TLS su nginx, mantieni proxy_pass su HTTP non cifrato tramite loopback e invia X-Forwarded-Proto $scheme, così l'applicazione sa che il visitatore ha usato HTTPS. Se il backend si trova su un host diverso, attraverso una rete che non controlli, quel collegamento richiede una protezione propria: puoi usare HTTPS verso il backend oppure un tunnel privato tra le due macchine.

Questo articolo ti è stato utile?