upstream în Nginx

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).