NGINX Toate comenzile și directivele Nginx

`upstream` în Nginx

Reverse proxy și load balancing Toate versiunile Nginx

Definește un grup de servere backend între care Nginx distribuie traficul (load balancing) și gestionează conexiunile keepalive.

Sintaxă

upstream nume { server adresă [parametri]; ... }

Ce face `upstream`

Blocul upstream definește un grup numit de servere backend în contextul http. Numele grupului poate fi folosit apoi în proxy_pass http://nume; sau fastcgi_pass nume;, iar Nginx distribuie automat cererile între serverele din grup.

Algoritmul implicit este round-robin (pe rând, proporțional cu ponderea weight). Alte strategii disponibile în ediția open-source sunt least_conn (trimite cererea la serverul cu cele mai puține conexiuni active — ideal când cererile au durate diferite), ip_hash (același IP de client ajunge la același server) și hash pe o cheie aleasă de tine.

Dacă un server din grup nu răspunde de max_fails ori în intervalul fail_timeout, Nginx îl marchează temporar ca indisponibil și trimite traficul doar către celelalte. Chiar și cu un singur server backend, un bloc upstream cu directiva keepalive merită folosit: păstrează conexiuni TCP deschise către backend și reduce latența.

Opțiuni și argumente

Opțiune / Parametru	Descriere
`Context: http`	Blocul `upstream` se scrie în `http`, în afara blocurilor `server`.
`server adresă`	IP:port, nume:port sau `unix:/cale/socket`.
`weight=N`	Ponderea serverului în distribuție (implicit `1`; un server cu `weight=3` primește de 3 ori mai multe cereri).
`max_fails=N / fail_timeout=T`	După `N` încercări eșuate în `T` secunde (implicit 1 în 10s), serverul este ocolit timp de `T` secunde.
`backup`	Serverul este folosit doar când toate serverele principale sunt indisponibile.
`down`	Marchează permanent serverul ca oprit (util când îl scoți temporar pentru mentenanță).
`least_conn / ip_hash`	Schimbă algoritmul de distribuție din round-robin în „cele mai puține conexiuni” sau „hash după IP-ul clientului”.
`keepalive N`	Păstrează în cache până la `N` conexiuni inactive către backend pentru fiecare worker.

Exemple

Exemplul 1: Load balancing între trei instanțe ale aplicației

Distribuție după numărul de conexiuni active, cu un server de rezervă:

upstream app_cluster {
    least_conn;

    server 10.0.1.11:3000 weight=2 max_fails=3 fail_timeout=15s;
    server 10.0.1.12:3000 weight=2 max_fails=3 fail_timeout=15s;
    server 10.0.1.13:3000 backup;

    keepalive 32;
}

server {
    listen 80;
    server_name example.com;

    location / {
        include proxy_params;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_pass http://app_cluster;
    }
}

Exemplul 2: Upstream pentru PHP-FPM

Numele grupului este folosit în fastcgi_pass:

upstream php_workers {
    server unix:/run/php/php8.3-fpm.sock;
}

# În blocul server:
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass php_workers;
}

Greșeli frecvente

Declararea keepalive 32; în upstream fără proxy_http_version 1.1; și proxy_set_header Connection ""; în location: în mod implicit, Nginx vorbește cu backend-ul pe HTTP/1.0 și trimite Connection: close, deci conexiunile nu sunt refolosite.
Scrierea upstream în interiorul unui bloc server: este permis doar în contextul http.

Comenzi înrudite

proxy_pass: Trimite cererea către un server backend (Node.js, Python, Go, Docker) și returnează răspunsul clientului.
proxy_set_header: Setează sau modifică antetele HTTP trimise către backend (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto).
Proxy pentru WebSocket: Configurează antetele Upgrade și Connection pe HTTP/1.1 pentru ca conexiunile WebSocket să treacă prin Nginx.
fastcgi_pass: Trimite scripturile .php către PHP-FPM prin protocolul FastCGI (socket Unix sau port TCP).

Ce face upstream