Directiva proxy_set_header în Nginx: sintaxă și exemple de configurare

Ce face `proxy_set_header`

Când Nginx trimite o cerere mai departe prin proxy_pass, el construiește o cerere nouă către backend, în care, în mod implicit, două lucruri se schimbă față de cererea originală a clientului: antetul Host devine numele din proxy_pass (de exemplu 127.0.0.1:3000), iar adresa IP a conexiunii văzută de aplicație devine 127.0.0.1 (adresa lui Nginx).

Directiva proxy_set_header rezolvă această problemă: îi transmitem aplicației din spate numele real al domeniului (Host $host), adresa IP reală a vizitatorului (X-Real-IP și X-Forwarded-For) și protocolul cu care a venit clientul la Nginx (X-Forwarded-Proto $scheme, esențial când Nginx termină HTTPS, dar vorbește cu aplicația prin HTTP).

Pe Debian/Ubuntu există deja fișierul /etc/nginx/proxy_params cu cele patru antete standard, astfel încât poți scrie simplu include proxy_params; în blocul location.

Opțiuni și argumente

Opțiune / Parametru	Descriere
`Context: http, server, location`	Moștenirea funcționează pe principiul „totul sau nimic”: un singur `proxy_set_header` în `location` anulează toate `proxy_set_header` din `server`.
`Host $host`	Trimite numele de domeniu cerut de client (de exemplu `example.com`).
`X-Real-IP $remote_addr`	Adresa IP a conexiunii directe cu Nginx.
`X-Forwarded-For $proxy_add_x_forwarded_for`	Lista IP-urilor prin care a trecut cererea (adaugă `$remote_addr` la antetul existent).
`X-Forwarded-Proto $scheme`	Protocolul original: `http` sau `https`.
`valoare '' (șir vid)`	Dacă valoarea este șirul vid, antetul nu mai este trimis deloc către backend.

Exemple

Exemplul 1: Antetele standard din /etc/nginx/proxy_params

Acestea sunt cele patru linii incluse de include proxy_params; pe Debian/Ubuntu:

proxy_set_header Host              $http_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;

Exemplul 2: Restaurarea IP-ului real când în fața Nginx este Cloudflare sau alt load balancer

Cu modulul realip, Nginx înlocuiește $remote_addr cu IP-ul vizitatorului doar dacă cererea vine dintr-o rețea de încredere:

# În blocul http sau server:
set_real_ip_from 10.0.0.0/8;
set_real_ip_from 172.16.0.0/12;
real_ip_header   X-Forwarded-For;
real_ip_recursive on;

Exemplul 3: Eliminarea unui antet înainte de trimiterea la backend

O valoare vidă suprimă complet antetul respectiv:

location /api/ {
    include proxy_params;
    proxy_set_header X-Internal-Token "";
    proxy_pass http://127.0.0.1:8080;
}

Greșeli frecvente

Capcana moștenirii: dacă pui cele patru proxy_set_header în server, iar într-un location adaugi un singur proxy_set_header X-Custom 1;, cele patru din server nu se mai moștenesc în acel location. Repetă include proxy_params; în acel bloc.
Aplicația generează link-uri cu http:// deși site-ul este pe https://: de obicei lipsește proxy_set_header X-Forwarded-Proto $scheme; (sau aplicația nu este configurată să aibă încredere în proxy).
Antetele primite de la client cu caracterul de subliniere în nume (X_API_KEY) sunt ignorate implicit de Nginx; dacă ai nevoie de ele, activează underscores_in_headers on; în http sau server.

Comenzi înrudite

proxy_pass: Trimite cererea către un server backend (Node.js, Python, Go, Docker) și returnează răspunsul clientului.
Proxy pentru WebSocket: Configurează antetele Upgrade și Connection pe HTTP/1.1 pentru ca conexiunile WebSocket să treacă prin Nginx.
upstream: Definește un grup de servere backend între care Nginx distribuie traficul (load balancing) și gestionează conexiunile keepalive.
add_header: Adaugă antete HTTP în răspunsul trimis clientului (antete de securitate HSTS, CSP, X-Frame-Options sau CORS).

Ce face proxy_set_header