Blocchi Location di Nginx Spiegati: Routing del Traffico Web

I blocchi location di Nginx decidono cosa succede dopo che una richiesta arriva nel blocco server corretto. Sono il motivo per cui /static/app.css può essere servito dal disco, /api/users può essere inoltrato a un'applicazione e /.git/config può essere negato prima che perda qualcosa di sensibile.

La maggior parte degli errori con i blocchi location non sono errori di sintassi. Sono errori di priorità. Una regex intercetta una richiesta che ti aspettavi fosse gestita da un blocco prefisso. Un percorso root aggiunge più URI di quanto pensassi. Un proxy_pass con una barra finale riscrive l'URI upstream in modo diverso rispetto alla stessa direttiva senza di essa. Gli esempi seguenti si concentrano su questi punti critici reali.

Il Ruolo e l'Anatomia di un Blocco Location

Un blocco location definisce come Nginx dovrebbe rispondere alle richieste in base all'URI della richiesta. Questi blocchi sono sempre annidati all'interno di un blocco server.

Quando un client effettua una richiesta (es., GET /images/logo.png), Nginx controlla l'URI della richiesta rispetto a tutti i blocchi location definiti all'interno del blocco server in ascolto per determinare la gestione appropriata, come servire un file, reindirizzare il client o inoltrare la richiesta a un server applicativo.

Sintassi di Base

La sintassi richiede un modificatore (o la sua assenza) seguito da un pattern (URI):

location [modifier] [pattern] {
    # Direttive di configurazione (es., root, index, proxy_pass)
}

Comprendere i Tipi di Corrispondenza Location (I Modificatori)

Nginx offre un piccolo insieme di stili di corrispondenza location. La scelta influisce sia sulla precisione del routing che sul lavoro che Nginx deve fare prima di scegliere un gestore.

1. Corrispondenza per Prefisso (Nessun Modificatore)

Questo è il tipo di corrispondenza predefinito. Nginx cerca la stringa iniziale più lunga che corrisponde all'URI della richiesta.

Modificatore	Esempio	Comportamento	Caso d'Uso Migliore
(nessuno)	location /blog/	Corrisponde a URI che iniziano con /blog/ (es., /blog/post/1).	Scopo generale, definizione di grandi sezioni di un sito.

Esempio:

location /docs/ {
    root /var/www/html/public;
    # Se l'URI è /docs/manual.pdf, Nginx cerca /var/www/html/public/docs/manual.pdf
}

2. Corrispondenza Esatta (=)

Questo modificatore forza una corrispondenza esatta tra l'URI e il pattern. Se corrisponde, Nginx interrompe immediatamente la ricerca di altre location. Questo è il tipo di corrispondenza più veloce.

Modificatore	Esempio	Comportamento	Caso d'Uso Migliore
=	location = /favicon.ico	Corrisponde solo all'URI /favicon.ico esattamente.	Gestione di file specifici richiesti di frequente o pagine predefinite.

3. Prefisso Più Lungo, Non-Regex (^~)

Questo è un tipo specializzato di corrispondenza per prefisso. Se Nginx trova la corrispondenza per prefisso più lunga usando ^~, interrompe immediatamente il controllo di qualsiasi blocco location con espressione regolare (regex), sovrascrivendoli di fatto.

Modificatore	Esempio	Comportamento	Caso d'Uso Migliore
^~	location ^~ /assets/	Corrisponde a URI che iniziano con /assets/ e impedisce il controllo di corrispondenze regex più lente.	Servire asset statici rapidamente e garantire che le directory degli asset siano gestite in modo prevedibile.

4. Espressione Regolare Case-Sensitive (~)

Utilizza le Espressioni Regolari Compatibili con Perl (PCRE) per la corrispondenza. È potente ma più lento delle corrispondenze per prefisso. Vince il primo blocco regex corrispondente.

Modificatore	Esempio	Comportamento	Caso d'Uso Migliore
~	location ~ \.php$	Corrisponde a qualsiasi URI che termina in .php.	Elaborazione di tipi di file specifici (es., passaggio di script PHP a PHP-FPM).

5. Espressione Regolare Case-Insensitive (~*)

Identico a ~, ma la corrispondenza ignora le maiuscole/minuscole dell'URI.

Modificatore	Esempio	Comportamento	Caso d'Uso Migliore
~*	`location ~* .(jpg	gif	png)$`

---

L'Ordine Critico di Elaborazione delle Location

Comprendere l'ordine in cui Nginx elabora i blocchi location è fondamentale per evitare comportamenti imprevisti. Nginx non legge semplicemente i file di configurazione dall'alto verso il basso. Utilizza una gerarchia rigorosa:

1. Corrispondenza Esatta (=): Nginx controlla prima tutti i blocchi di corrispondenza esatta. Se viene trovata una corrispondenza, l'elaborazione si interrompe immediatamente e la richiesta viene gestita da quel blocco.
2. Candidato Prefisso Più Lungo: Nginx trova la location con il prefisso corrispondente più lungo, incluse le location con prefisso semplice e quelle con ^~.
3. Salto Regex per ^~: Se la migliore corrispondenza per prefisso utilizza ^~, Nginx la usa e salta i controlli regex.
4. Espressioni Regolari (~ e ~*): Se il miglior prefisso non era ^~, Nginx controlla le location regex nell'ordine in cui appaiono nel file di configurazione. Vince il primo blocco regex corrispondente.
5. Corrispondenza per Prefisso Standard Più Lunga: Se nessuna regex vince, Nginx utilizza il candidato con il prefisso più lungo già trovato. In molte configurazioni, location / è il fallback finale.

Questo è il motivo per cui ^~ /static/ è comune. Senza ^~, una regex successiva come location ~* \.(css|js)$ può ancora vincere per /static/app.css. A volte va bene. Altre volte bypassa le intestazioni della cache, il percorso root o le regole di accesso che ti aspettavi per l'intera directory /static/.

Scenari di Configurazione Pratica

1. Dare Priorità agli Asset Statici per le Prestazioni

Per garantire che Nginx serva i file statici direttamente e rapidamente, prevenendo controlli regex più lenti ed elaborazione non necessaria da parte del server applicativo, utilizza il modificatore ^~.

server {
    listen 80;
    server_name myapp.com;

    # 1. Corrispondenza esatta per la pagina principale (priorità più alta)
    location = / {
        proxy_pass http://backend_app_server;
    }

    # 2. Gestione rapida per asset statici, bypassando i controlli regex
    location ^~ /static/ {
        root /var/www/site;
        expires 30d;
    }

    # 3. Espressione regolare per file multimediali comuni
    location ~* \.(gif|ico|css|js)$ {
        root /var/www/site;
        expires 7d;
    }

    # 4. Fallback per tutte le altre richieste dinamiche
    location / {
        proxy_pass http://backend_app_server;
    }
}

2. Routing e Proxy del Traffico API

Quando si utilizza Nginx come proxy inverso, i blocchi location indirizzano il traffico al server applicativo upstream corretto.

location /api/v1/ {
    # Assicura che Nginx rispetti le impostazioni di connessione del client
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    # Instrada tutto il traffico che inizia con /api/v1/ al servizio backend
    proxy_pass http://api_backend_service/v1/;

    # Con un URI in proxy_pass, Nginx sostituisce il prefisso corrispondente.
    # /api/v1/users diventa /v1/users upstream.
}

Vale la pena testare quel comportamento della barra finale. Questi due esempi sono diversi:

location /api/ {
    proxy_pass http://api_backend;
}

location /api/ {
    proxy_pass http://api_backend/;
}

La prima forma passa l'URI originale, incluso /api/..., all'upstream. La seconda forma sostituisce il prefisso /api/ corrispondente con /. Se il tuo upstream inizia improvvisamente a restituire 404 dopo una piccola modifica alla configurazione, controlla questo prima di incolpare l'app.

3. Proteggere Directory Sensibili

I blocchi location possono essere utilizzati per negare l'accesso esterno a directory interne sensibili, come file di configurazione o directory nascoste come .git.

# Nega l'accesso ai file che iniziano con un punto (file nascosti)
location ~ /\.(ht|svn|git) {
    deny all;
    return 404; # Restituisce 404 invece di 403 per evitare di rivelare la loro esistenza
}

# Nega l'accesso a directory di configurazione specifiche
location /app/config/ {
    deny all;
}

Per i file nascosti, molti team utilizzano una regola di negazione più ampia:

location ~ /\.(?!well-known/) {
    deny all;
    return 404;
}

L'eccezione mantiene /.well-known/ disponibile per cose come le sfide del certificato ACME HTTP-01, bloccando comunque la maggior parte dei file con punto iniziale. Testalo attentamente se il tuo sito serve altri percorsi legittimi con prefisso punto.

Avviso di Sicurezza: Utilizzo di alias vs. root

Quando si configurano i percorsi dei file all'interno di un blocco location, presta attenzione alla differenza tra root e alias.

• root: Aggiunge l'URI completo della richiesta al percorso definito. (es., location /images/ + root /data/ porta a /data/images/filename.jpg)
• alias: Sostituisce la parte corrispondente dell'URI con il percorso definito. Questo è spesso necessario quando il blocco location utilizza una regex o ha bisogno di rimuovere parte del percorso prima di servire il file. (es., location /static/ + alias /opt/app/files/ porta a /opt/app/files/filename.jpg)

4. Gestire Barre Finali e Reindirizzamenti

Spesso è desiderabile imporre una struttura URL coerente, come garantire che le directory terminino sempre con una barra finale (/).

# Forza una barra finale per i percorsi delle directory se mancante
location ~* /[a-z0-9\-_]+$ {
    # Se l'URI corrisponde a un file, Nginx proverà a servirlo. Altrimenti, lo tratta come una directory.
    # Controlla se l'URI richiesto corrisponde a una directory sul disco:
    if (-d $request_filename) {
        return 301 $uri/;
    }
}

Un Buon Metodo per Debugare il Routing delle Location

Quando una richiesta arriva nel posto sbagliato, riduci il problema a un singolo URL e un blocco server. Esegui nginx -T per vedere la configurazione completa renderizzata, inclusi i file inclusi, poi cerca ogni location che potrebbe corrispondere a quell'URI. Presta particolare attenzione ai blocchi regex perché il loro ordine nel file è importante.

Per i file statici, conferma il percorso del filesystem che Nginx costruirà da root o alias. Per le richieste inoltrate, conferma se proxy_pass include una parte URI dopo il nome dell'upstream. Quindi ricarica solo dopo che nginx -t ha avuto successo.

I blocchi location sono prevedibili una volta che interiorizzi le regole di priorità, ma sono spietati quando una configurazione cresce tramite copia e incolla. Usa corrispondenze esatte per piccoli percorsi critici, ^~ per directory che dovrebbero bypassare la gestione regex, regex solo dove la corrispondenza di pattern è realmente necessaria e un semplice location / come fallback chiaro.