NGINX

Învață Nginx: directive, reverse proxy și SSL explicate cu exemple

49 de directive 12 categorii

Nginx (pronunțat „engine-x”) este serverul web open-source de înaltă performanță, reverse proxy-ul și load balancer-ul care alimentează peste o treime dintre cele mai vizitate site-uri de pe internet. Creat inițial în 2004 de inginerul rus Igor Sysoev pentru a rezolva celebra problemă C10K (gestionarea a peste 10.000 de conexiuni TCP concurente pe un singur server fizic), Nginx a transformat radical arhitectura web eliminând modelul tradițional concurent bazat pe procese/fire dedicate per conexiune (specific serverelor vechi precum Apache prefork) în favoarea unei arhitecturi asincrone, non-blocante și conduse de evenimente (Event-Driven Architecture).

În infrastructurile moderne de producție, Nginx servește ca prim punct de contact (Edge Ingress) pentru traficul web: realizează terminarea criptografică SSL/TLS (HTTPS, HTTP/2 și HTTP/3 QUIC), filtrează atacurile malițioase prin Rate Limiting și antete de securitate (HSTS, CSP), distribuie încărcarea către backend-uri prin Load Balancing inteligent și accelerează timpii de răspuns prin microcaching agresiv și compresie modernă (Gzip, Brotli).

Arhitectura Internă Asincronă Nginx: Master Process, Workers și epoll
# Nginx nu creează un fir de execuție separat pentru fiecare vizitator!
# În schimb, utilizează un model modular cu procese asimetrice specializate:

# 1. PROCESUL MASTER (Master Process - rulează ca root):
#    - Citește și validează fișierele de configurare (nginx.conf, sites-available).
#    - Deschide și leagă porturile privilegiate de rețea (80, 443).
#    - Gestionează ciclul de viață al proceselor lucrătoare (Worker Processes):
#      la 'nginx -s reload', pornește un nou set de workers cu noua configurație
#      și îi oprește treptat pe cei vechi fără a întrerupe nicio cerere pe fir (Zero Downtime)!

# 2. PROCESELE WORKER (Worker Processes - rulează neprivilegiat ca 'www-data' sau 'nginx'):
#    - Configurat de regulă cu: worker_processes auto; (1 worker per nucleu CPU fizic).
#    - Fiecare worker rulează o buclă continuă de evenimente non-blocantă (Single-Threaded Event Loop).
#    - Folosește mecanismul nativ de notificare de mare viteză al nucleului Linux: 'epoll'
#      (sau 'kqueue' pe FreeBSD/macOS).
#    - Un singur worker procesează simultan mii de cereri de rețea multiplexate: în loc să aștepte
#      răspunsul lent de la disc sau de la baza de date, worker-ul trece instantaneu la următoarea
#      cerere gata pe socket-ul de rețea!

# 3. PROCESELE DE CACHE (Cache Manager & Cache Loader):
#    - Cache Loader: Încarcă metadatele cache-ului de pe disc în memoria RAM partajată la pornire.
#    - Cache Manager: Curăță periodic elementele de cache expirate sau care depășesc dimensiunea alocată.

Algoritmul Strict de Potrivire a Blocurilor Location

Una dintre cele mai mari surse de confuzie și erori de configurare în Nginx este ordinea în care sunt evaluate blocurile location. Nginx nu le evaluează pur și simplu de sus în jos în fișier, ci aplică o regulă strictă de prioritate matematică:

Modificator Tip Potrivire Prioritate Comportament și Exemplu
= Potrivire Exactă 1 (Maximă) Dacă URI-ul este identic caracter cu caracter, căutarea se oprește imediat.
Exemplu: location = /favicon.ico { ... }
^~ Prefix Fără Regex 2 Dacă cel mai lung prefix potrivit are acest modificator, blochează complet căutarea în expresiile regulate.
Exemplu: location ^~ /static/ { ... }
~ / ~* Expresii Regulate (Regex) 3 ~ = sensibil la majuscule (case-sensitive); ~* = insensibil.
Se evaluează în ordinea strictă de apariție în fișier. Prima potrivire câștigă!
Exemplu: location ~* \.(jpg|png|webp|avif)$ { ... }
(fără) Prefix Standard 4 (Minimă) Se selectează cel mai lung prefix potrivit, dar căutarea continuă în regex-uri dacă nu a fost întâlnit ^~.
Exemplu: location /api/ { ... } sau location / { ... }

Tehnologia Zero-Copy: sendfile, tcp_nopush și tcp_nodelay

Pentru a servi fișiere statice (imagini, video-uri, arhive, CSS/JS) la viteza maximă pe care o permite placa de rețea fără a irosi cicluri de procesor, Nginx utilizează mecanismele Zero-Copy din nucleul Linux:

Configurația recomandată pentru servire fișiere de viteză extremă
# În contextul http din /etc/nginx/nginx.conf:

# 1. SENDFILE (Zero-Copy):
# În mod tradițional, datele fișierului sunt copiate: Disc -> Buffer Kernel -> Memorie Nginx -> Buffer Socket -> Rețea.
# Directiva 'sendfile on' instruiește nucleul să transfere datele direct din Page Cache în placa de rețea,
# ocolind complet copierea în spațiul de memorie al procesului Nginx!
sendfile on;

# 2. TCP_NOPUSH:
# Forțează Nginx să trimită antetele HTTP și începutul pachetului de date într-un singur pachet TCP complet
# de mărime maximă (MSS), optimizând lățimea de bandă:
tcp_nopush on;

# 3. TCP_NODELAY:
# Dezactivează algoritmul Nagle pentru conexiunile active (keep-alive). Esențial pentru microservicii și API-uri,
# trimițând pachetele mici imediat fără o întârziere artificială de 200ms:
tcp_nodelay on;

# 4. OPEN_FILE_CACHE:
# Memorează în memoria RAM descriptorii de fișiere (file descriptors), dimensiunile și permisiunile,
# eliminând mii de apeluri de sistem lente de tip stat() pe disc pentru resurse accesate frecvent:
open_file_cache max=10000 inactive=30s;
open_file_cache_valid 60s;
open_file_cache_min_uses 2;
open_file_cache_errors on;

Cele 11 Faze Interne de Procesare a Cererilor HTTP

La fiecare cerere primită pe un port TCP, Nginx execută un lanț modular strict compus din 11 faze succesive:

  1. NGX_HTTP_POST_READ_PHASE: Punctul inițial de citire a antetelor cererii din socket.
  2. NGX_HTTP_SERVER_REWRITE_PHASE: Executarea directivelor rewrite definite în blocul server.
  3. NGX_HTTP_FIND_CONFIG_PHASE: Algoritmul de căutare a blocului location potrivit.
  4. NGX_HTTP_REWRITE_PHASE: Executarea directivelor rewrite definite în interiorul blocului location ales.
  5. NGX_HTTP_POST_REWRITE_PHASE: Verificarea numărului de rescrieri interne (previne ciclurile infinite de redirect, limitate la 10).
  6. NGX_HTTP_PREACCESS_PHASE: Verificări preliminare de limitare (directiva limit_req și limit_conn).
  7. NGX_HTTP_ACCESS_PHASE: Securitate și autentificare (directiva allow/deny, auth_basic, auth_request).
  8. NGX_HTTP_POST_ACCESS_PHASE: Verificarea satisfacției cerințelor de acces.
  9. NGX_HTTP_PRECONTENT_PHASE: Modulul de filtrare a imaginilor sau streaming MP4/FLV.
  10. NGX_HTTP_CONTENT_PHASE: Generarea răspunsului efectiv (citire fișier static, fastcgi_pass către PHP-FPM sau proxy_pass către Node/Python/Go).
  11. NGX_HTTP_LOG_PHASE: Înregistrarea detaliilor în access_log după finalizarea trimiterii datelor către client.
macOS • Windows • Linux

Ghid de instalare Nginx pe fiecare sistem de operare

Instalează serverul web Nginx, pornește serviciul și verifică configurația pe macOS, Windows (WSL2 / Docker) și Linux.

Cerințe de sistem: Acces de administrator (sudo); porturile 80 și 443 libere pentru producție.

Terminal macOS (Homebrew / zsh)
# Instalare prin Homebrew și pornire ca serviciu:
brew install nginx
brew services start nginx

# Pe macOS, Nginx ascultă implicit pe portul 8080:
curl -I http://localhost:8080

# Fișierul de configurare (Apple Silicon; pe Intel: /usr/local/etc/nginx/):
nginx -t
# /opt/homebrew/etc/nginx/nginx.conf

Comenzi de administrare 5 directive

Blocuri de bază 8 directive

Reverse proxy și load balancing 7 directive

Redirecționări și rescrieri 3 directive

SSL/TLS și securitate 6 directive

Performanță și PHP 8 directive

Jurnale și depanare 3 directive

Proxy și Rutare 1 directivă

Securitate și Protecție 3 directive

Criptare și Protocoale Moderne 2 directive

Scalare și Înaltă Disponibilitate 1 directivă

Securitate Web și Hardening 2 directive

Toate comenzile și directivele Nginx

Lista completă a comenzilor explicate în această secțiune, cu sintaxa lor uzuală. Fiecare comandă are o pagină dedicată, cu explicații detaliate, opțiuni și exemple practice.

Comenzi de administrare (5)

Comandă / Directivă Ce face
nginx -t Testează sintaxa fișierelor de configurare fără a opri sau reporni serverul.
nginx -t [-q] [-c fișier] [-p prefix] [-g directive]
nginx -s reload Trimite un semnal procesului master Nginx: reload, stop, quit sau reopen.
nginx -s reload|stop|quit|reopen
systemctl reload nginx Pornește, oprește, repornește sau reîncarcă serviciul Nginx prin systemd.
systemctl start|stop|restart|reload|status|enable|disable nginx
nginx -V / nginx -T Afișează versiunea și modulele compilate (-V) sau întreaga configurație rezultată (-T).
nginx -v | nginx -V | nginx -T
nginx.conf și sites-available Cum sunt organizate fișierele de configurare: nginx.conf, include, conf.d, sites-available și sites-enabled.
include cale/fișiere/*.conf;

Blocuri de bază (6)

Comandă / Directivă Ce face
server Definește un server virtual (un site) cu porturile, numele de domeniu și regulile sale.
server { ... }
listen Stabilește adresa IP și portul pe care un bloc server acceptă conexiuni.
listen [adresă:]port [default_server] [ssl] [quic] [reuseport] [backlog=număr];
server_name Stabilește numele de domeniu (antetul Host) pentru care răspunde un bloc server.
server_name nume [nume ...];
location Potrivește calea URI a cererii (exact, cu prefix sau cu expresie regulată) și aplică regulile corespunzătoare.
location [ = | ~ | ~* | ^~ ] uri { ... }
root / alias Stabilesc directorul de pe disc din care sunt servite fișierele: root lipește întregul URI, alias înlocuiește prefixul location.
root cale;
alias cale;
try_files Verifică pe rând existența fișierelor sau directoarelor și redirecționează intern către ultimul argument dacă niciunul nu există.
try_files fișier ... uri;
try_files fișier ... =cod;

Reverse proxy și load balancing (4)

Comandă / Directivă Ce face
proxy_pass Trimite cererea către un server backend (Node.js, Python, Go, Docker) și returnează răspunsul clientului.
proxy_pass URL;
proxy_set_header Setează sau modifică antetele HTTP trimise către backend (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto).
proxy_set_header câmp valoare;
upstream Definește un grup de servere backend între care Nginx distribuie traficul (load balancing) și gestionează conexiunile keepalive.
upstream nume { server adresă [parametri]; ... }
Proxy pentru WebSocket Configurează antetele Upgrade și Connection pe HTTP/1.1 pentru ca conexiunile WebSocket să treacă prin Nginx.
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Redirecționări și rescrieri (3)

Comandă / Directivă Ce face
return Oprește procesarea cererii și trimite imediat clientului un cod de stare HTTP, o redirecționare sau un text scurt.
return cod [text];
return cod URL;
return URL;
rewrite Modifică URI-ul cererii pe baza unei expresii regulate, pentru redirecționări externe sau rescrieri interne.
rewrite regex înlocuire [last | break | redirect | permanent];
Redirecționare HTTP → HTTPS Tiparul recomandat pentru redirecționarea traficului de pe portul 80 pe HTTPS (și canonizarea cu sau fără www).
return 301 https://$host$request_uri;

SSL/TLS și securitate (5)

Comandă / Directivă Ce face
ssl_certificate și HTTPS Configurează certificatul, cheia privată, versiunile TLS (1.2/1.3) și cache-ul de sesiuni pentru HTTPS.
ssl_certificate fișier.pem;
ssl_certificate_key cheie.key;
ssl_protocols TLSv1.2 TLSv1.3;
certbot --nginx Obține și reînnoiește automat certificate SSL gratuite Let’s Encrypt și actualizează configurația Nginx.
certbot --nginx -d domeniu.ro [-d www.domeniu.ro]
certbot certonly --webroot -w /var/www/site -d domeniu.ro
add_header Adaugă antete HTTP în răspunsul trimis clientului (antete de securitate HSTS, CSP, X-Frame-Options sau CORS).
add_header nume valoare [always];
limit_req Limitează rata cererilor (rate limiting) pe adresă IP pentru a proteja formularele de login și API-urile.
limit_req_zone $binary_remote_addr zone=nume:10m rate=10r/s;
limit_req zone=nume [burst=N] [nodelay];
allow / deny / auth_basic Restricționează accesul la o zonă după adresa IP (allow/deny) sau cu utilizator și parolă HTTP Basic (auth_basic).
allow adresă | CIDR | all;
deny adresă | CIDR | all;
auth_basic "Mesaj";
auth_basic_user_file /cale/htpasswd;

Performanță și PHP (5)

Comandă / Directivă Ce face
gzip Comprimă din mers răspunsurile text (HTML, CSS, JS, JSON, SVG) înainte de a le trimite către browser.
gzip on | off;
gzip_types mime/type ...;
gzip_comp_level 1..9;
expires Setează antetele Cache-Control și Expires pentru ca browserul și CDN-ul să păstreze în cache fișierele statice.
expires [modified] timp | epoch | max | off;
fastcgi_pass Trimite scripturile .php către PHP-FPM prin protocolul FastCGI (socket Unix sau port TCP).
fastcgi_pass adresă;
fastcgi_cache Salvează în cache răspunsurile HTML generate de PHP-FPM, servind paginile direct din Nginx fără a mai apela PHP și baza de date.
fastcgi_cache_path /var/cache/nginx levels=1:2 keys_zone=nume:100m inactive=60m;
fastcgi_cache nume;
fastcgi_cache_valid 200 60m;
client_max_body_size Stabilește dimensiunea maximă permisă pentru corpul unei cereri HTTP (încărcări de fișiere) și previne eroarea 413.
client_max_body_size dimensiune;

Jurnale și depanare (2)

Comandă / Directivă Ce face
access_log / error_log Configurează jurnalele de acces și de erori (fișiere separate pe site, niveluri de severitate, dezactivare pe rute).
access_log cale [format [buffer=dim] [flush=timp] [if=condiție]] | off;
error_log cale [debug | info | notice | warn | error | crit | alert | emerg];
log_format Definește structura unei linii din access_log (timpi de răspuns din backend, stare cache, format JSON pentru ELK/Loki).
log_format nume [escape=default|json|none] șir ...;