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

Ce face `proxy_pass`

Directiva proxy_pass transformă Nginx într-un reverse proxy: clientul comunică doar cu Nginx (pe porturile 80/443), iar Nginx deschide în spate o conexiune HTTP sau HTTPS către aplicația reală (de exemplu un proces Node.js pe 127.0.0.1:3000, Gunicorn pe un socket Unix sau un grup upstream) și îi retransmite răspunsul.

Detaliul cel mai important din proxy_pass este prezența sau absența unui URI (inclusiv a unui simplu /) după adresă și port: dacă scrii doar protocolul, gazda și portul (proxy_pass http://127.0.0.1:3000;), Nginx trimite la backend URI-ul original neschimbat; dacă adaugi orice cale — chiar și un singur slash (proxy_pass http://127.0.0.1:3000/;) — Nginx înlocuiește prefixul din location cu acea cale.

De exemplu, pentru o cerere la /api/users în location /api/: cu proxy_pass http://127.0.0.1:3000; backend-ul primește /api/users; cu proxy_pass http://127.0.0.1:3000/; backend-ul primește /users; cu proxy_pass http://127.0.0.1:3000/v1/; primește /v1/users.

Opțiuni și argumente

Opțiune / Parametru	Descriere
`Context: location, if în location, limit_except`	Se scrie în interiorul unui bloc `location`.
`http://gazdă:port`	Trimite la backend URI-ul cererii exact așa cum a venit de la client.
`http://gazdă:port/cale/`	Înlocuiește partea din URI care a potrivit `location` cu `/cale/`.
`http://unix:/cale/socket:`	Conectare printr-un socket Unix local (notă: două puncte după calea socket-ului).
`https://...`	Nginx se conectează la backend prin HTTPS.
`proxy_read_timeout timp`	Cât așteaptă răspunsul de la backend (implicit `60s`; crește-l pentru rapoarte lente).

Exemple

Exemplul 1: Efectul slash-ului final în proxy_pass

Cum arată calea primită de backend pentru cererea GET /api/produse?id=5:

# Cazul 1: FĂRĂ slash după port -> backend-ul primește /api/produse?id=5
location /api/ {
    proxy_pass http://127.0.0.1:3000;
}

# Cazul 2: CU slash după port -> backend-ul primește /produse?id=5
location /api/ {
    proxy_pass http://127.0.0.1:3000/;
}

# Cazul 3: Cu altă cale -> backend-ul primește /v2/produse?id=5
location /api/ {
    proxy_pass http://127.0.0.1:3000/v2/;
}

Exemplul 2: Reverse proxy complet pentru o aplicație Node.js / Python

Configurație uzuală în producție, cu antetele necesare și timeout mărit:

server {
    listen 80;
    server_name app.example.com;

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

        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;

        proxy_connect_timeout 5s;
        proxy_send_timeout    60s;
        proxy_read_timeout    60s;
    }
}

Exemplul 3: Proxy către un socket Unix (Gunicorn / Puma)

Când aplicația rulează pe aceeași mașină, socket-ul Unix evită stiva TCP:

location / {
    include proxy_params;
    proxy_pass http://unix:/run/gunicorn/app.sock:;
}

Greșeli frecvente

Folosirea unui nume de domeniu cu variabilă în proxy_pass fără directiva resolver: Nginx rezolvă numele la pornire doar pentru adrese fixe; pentru nume dinamice trebuie definit resolver 1.1.1.1;, altfel apare eroarea no resolver defined to resolve ....
Eroarea 502 Bad Gateway înseamnă că Nginx a funcționat, dar nu s-a putut conecta la backend (aplicația din spate este oprită sau ascultă pe alt port); eroarea 504 Gateway Time-out înseamnă că aplicația nu a răspuns în proxy_read_timeout.
Folosirea unui URI în proxy_pass în interiorul unui location cu expresie regulată (location ~): în blocurile regex, proxy_pass nu are voie să conțină cale (doar dacă folosești variabile).

Comenzi înrudite

proxy_set_header: Setează sau modifică antetele HTTP trimise către backend (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto).
upstream: Definește un grup de servere backend între care Nginx distribuie traficul (load balancing) și gestionează conexiunile keepalive.
Proxy pentru WebSocket: Configurează antetele Upgrade și Connection pe HTTP/1.1 pentru ca conexiunile WebSocket să treacă prin Nginx.
location: Potrivește calea URI a cererii (exact, cu prefix sau cu expresie regulată) și aplică regulile corespunzătoare.

Ce face proxy_pass