În viața fiecărui administrator de sistem, există un moment de groază pură: încep să curgă rapoartele că "site-ul este picat", dar când verifici serverul, totul pare în regulă. Încărcarea CPU este mică. Discul nu este plin. Serviciile rulează. Totuși, fiecare browser care îți accesează domeniul este întâmpinat de ecranul alb al morții: 502 Bad Gateway.

Spre deosebire de o eroare 500 Internal Server Error (care înseamnă de obicei că codul tău PHP a crăpat fatal) sau o eroare 504 Gateway Timeout (care înseamnă că scriptul tău e prea lent), o eroare 502 este o defecțiune de rețea. Înseamnă că lanțul de comunicare s-a rupt. Nginx, acționând ca "Gateway" sau proxy, a încercat să paseze o cerere către aplicația backend (cum ar fi PHP-FPM), iar backend-ul, în esență, i-a închis telefonul în nas, a refuzat să răspundă sau a vorbit aiurea.

La ServerSpan, gestionarea a mii de instanțe Linux VPS ne-a învățat că erorile 502 sunt rareori simple. Pot fi cauzate de orice, de la un simplu conflict de plugin-uri până la depășiri complexe ale stivei TCP la nivel de kernel. Acest ghid complet este scris pentru a te duce de la un nivel de începător absolut ("Ce este un gateway?") la un nivel de sysadmin senior ("Cum urmăresc apelurile de sistem?"). Indiferent dacă găzduiești un mic blog WordPress sau un magazin WooCommerce masiv, așa repari tăcerea.

Partea 1: Înțelegerea arhitecturii

Înainte de a repara eroarea, trebuie să înțelegi fluxul datelor. Într-un stack web modern (LEMP: Linux, Nginx, MySQL, PHP), Nginx nu execută cod PHP. Este un reverse proxy. Servește fișiere statice (imagini, CSS, JS) eficient, dar când vede un fișier `.php`, pasează cererea către un proces separat numit PHP-FPM (FastCGI Process Manager).

Gândește-te la Nginx ca la chelnerul dintr-un restaurant și la PHP-FPM ca la bucătarul din bucătărie.

  • Cererea: Un client (browser) comandă o friptură (index.php).
  • Pasarea comenzii: Chelnerul (Nginx) scrie comanda pe un bon și o glisează prin fereastră (Socket/Port) către bucătărie (PHP-FPM).
  • Eroarea 502: Chelnerul glisează bonul prin fereastră, dar:
    • Bucătăria este în flăcări (Serviciul a crăpat).
    • Fereastra este bătută în cuie (Permisiuni refuzate/Permission Denied).
    • Bucătarii ignoră fereastra pentru că sunt prea ocupați (Backlog Full).
    • Bucătarul ia bonul și moare instant de infarct (Segfault).

În oricare dintre aceste cazuri, chelnerul trebuie să se întoarcă la client și să spună: "Nu pot să vă preiau comanda". Aceasta este eroarea 502 Bad Gateway.

Partea 2: Lista de verificare pentru "Junior Admin" (Începe aici)

Înainte să începi să umbli la parametrii de kernel, fă verificările de sănătate de bază. 80% dintre erorile 502 sunt cauzate de simple eșecuri ale serviciilor.

1. PHP-FPM chiar rulează?

Sună evident, dar serviciile crapă. Dacă PHP-FPM nu rulează, Nginx nu are cu cine să vorbească.

sudo systemctl status php8.2-fpm

Dacă scrie "inactive" sau "failed", repornește-l. Dacă eșuează la repornire, verifică sintaxa configurației:

sudo php-fpm8.2 -t

2. Nginx vorbește cu cine trebuie?

Un scenariu comun pe serverele Managed VPS este un upgrade de versiune PHP. Faci upgrade de la PHP 8.1 la 8.2 folosind `apt upgrade`. Vechiul serviciu (`php8.1-fpm`) se oprește, iar cel nou (`php8.2-fpm`) pornește.

Totuși, fișierele tale de configurare Nginx (`/etc/nginx/sites-available/your-site`) s-ar putea să indice încă spre vechea cale de socket:

fastcgi_pass unix:/run/php/php8.1-fpm.sock; # GREȘIT

Verifică directorul `/run/php/` să vezi ce socket există de fapt și actualizează config-ul Nginx pentru a se potrivi.

3. Verifică log-urile de eroare (În mod corect)

Nu da doar `tail` la log uitându-te cum curge textul. Folosește `grep` pentru codul specific de eroare. Log-ul de eroare Nginx se află de obicei la `/var/log/nginx/error.log`.

grep "502" /var/log/nginx/access.log
tail -n 100 /var/log/nginx/error.log

Caută fraze precum "Connection refused" (Serviciu picat), "No such file or directory" (Cale socket greșită) sau "Upstream sent too big header" (Buffer overflow). Aceste indicii îți definesc următorii pași.

Partea 3: Fix-urile Intermediare (Tuning de Configurație)

Dacă serviciul este pornit și căile sunt corecte, dar încă primești erori 502—în special intermitente sub sarcină mare—te confrunți probabil cu un blocaj de configurare. Asta este comun pe planurile VPS de înaltă performanță unde setările implicite limitează hardware-ul.

1. Depășirea buffer-ului de antet (Header Buffer Overflow)

Problema:
Aplicațiile web moderne trimit antete HTTP mari. Cookie-urile, token-urile de securitate (JWT) și datele complexe de sesiune pot umfla antetul de răspuns trimis de PHP către Nginx. Nginx are un buffer dedicat pentru citirea acestor antete, definit de `fastcgi_buffer_size`. Valoarea implicită este adesea minusculă (4KB sau 8KB—o pagină de memorie).

Dacă PHP trimite un antet de 10KB, Nginx nu știe ce să facă cu surplusul. În loc să îl trunchieze, consideră răspunsul invalid și aruncă o eroare 502.

Soluția:
Mărește limitele buffer-ului în `nginx.conf` în blocul `http {}` sau în blocul specific al serverului.

http {
    ...
    fastcgi_buffers 16 16k; 
    fastcgi_buffer_size 32k;
    ...
}

Dă reload la Nginx după această schimbare (`nginx -s reload`). Asta rezolvă cam 30% dintre erorile 502 "misterioase" legate de plugin-urile de login/autentificare.

2. Nepotrivirea de Timeout (Timeout Mismatch)

Problema:
Există o negociere a răbdării între Nginx și PHP. Nginx are `fastcgi_read_timeout` (cât timp așteaptă ca PHP să răspundă). PHP are `max_execution_time` (cât timp rulează înainte să se sinucidă).

Dacă Nginx așteaptă 30 de secunde, dar PHP încearcă să ruleze 60 de secunde, Nginx va închide telefonul la secunda 30. Asta cauzează de obicei un 504 Gateway Timeout, dar uneori poate rezulta într-un 502 dacă socket-ul se închide brusc.

Soluția:
Asigură-te că Nginx este mai răbdător decât PHP.

# În php.ini
max_execution_time = 300

# În nginx.conf
fastcgi_read_timeout 300;

Partea 4: Senior Admin Deep Dive (Kernel & Analiză Forensică)

Aici începe munca adevărată. Dacă log-urile tale tac, configurația pare ok, dar serverul tău încă aruncă erori 502 sub trafic intens, ai de-a face cu epuizarea resurselor la nivel de sistem de operare. Bun venit în kernel.

1. Aruncarea silențioasă din coadă (SYN Flood / Backlog Drop)

Conceptul:
Când Nginx se conectează la PHP-FPM via TCP (127.0.0.1:9000), execută un handshake TCP. Sistemul de operare ține aceste conexiuni într-o "Coadă de Ascultare" (Listen Queue) până când aplicația (PHP-FPM) le acceptă.

Această coadă are o limită de mărime. Dacă PHP-FPM este copleșit (procesează cererile mai lent decât sosesc), această coadă se umple. Odată plină, kernel-ul Linux aruncă silențios noile tentative de conexiune. Nginx trimite un pachet SYN, așteaptă, nu primește răspuns și presupune că backend-ul este mort -> Eroare 502.

Diagnosticare:
Trebuie să verifici statisticile de rețea ale kernel-ului pentru pachete aruncate (dropped packets).

# Verifică ListenDrops
nstat -az | grep ListenDrop

Dacă acest număr crește în timp ce vezi erori 502, backlog-ul tău este prea mic.

Soluția:
Trebuie să ridici limita în două locuri: în Kernel (OS) și în Aplicație (PHP).

# 1. Editează /etc/sysctl.conf
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535

# Aplică schimbările
sysctl -p

# 2. Editează config-ul pool-ului PHP-FPM (www.conf)
listen.backlog = 65535

# Repornește PHP-FPM
systemctl restart php8.2-fpm

2. Epuizarea Porturilor Efemere (Ephemeral Port Exhaustion)

Conceptul:
Fiecare conexiune dintre Nginx și PHP-FPM consumă o pereche de porturi TCP. Chiar și după ce cererea se termină, conexiunea rămâne într-o stare numită `TIME_WAIT` timp de 60 de secunde pentru a asigura integritatea datelor. Linux are o gamă limitată de "porturi efemere" (de obicei cam 28.000) pentru aceste conexiuni de ieșire.

Dacă servești 500 de cereri pe secundă, consumi 30.000 de porturi pe minut. Vei rămâne fără porturi. Nginx nu va reuși să deschidă o nouă conexiune -> Eroare 502.

Diagnosticare:
Numără conexiunile în starea TIME_WAIT.

netstat -n | grep TIME_WAIT | wc -l

Dacă acest număr este aproape de 28.000, ai probleme serioase.

Soluția:
Activează "TCP Reuse" în kernel. Asta permite Linux-ului să refolosească socket-urile `TIME_WAIT` în siguranță pentru conexiuni noi.

# /etc/sysctl.conf
net.ipv4.tcp_tw_reuse = 1
net.ipv4.ip_local_port_range = 1024 65535

3. Urmărirea erorilor de segmentare (Segfaults) cu strace

Conceptul:
Uneori PHP-FPM nu doar îngheață; moare. O eroare de segmentare (Segfault) apare când un proces încearcă să acceseze memorie pe care nu o deține. Kernel-ul îl omoară instantaneu. Asta se întâmplă des din cauza extensiilor PHP cu bug-uri (precum ImageMagick, Redis sau IonCube).

Când procesul moare în mijlocul cererii, Nginx vede conexiunea tăiată brusc ("Connection reset by peer") -> Eroare 502.

Diagnosticare:
Log-urile standard adesea nu îți vor arăta de ce a crăpat. Trebuie să atașezi un "tracer" la proces.

1. Găsește ID-ul procesului Master (PID) al PHP-FPM:

pgrep -P 1 php-fpm

2. Rulează `strace` pe master și urmărește toate procesele copil (`-f`). Salvează output-ul într-un fișier pentru că va fi masiv.

strace -f -p [PID] -s 1024 -o /tmp/debug.log

3. Reprodu eroarea 502 vizitând site-ul.

4. Oprește `strace` (Ctrl+C) și inspectează log-ul.

grep "SIGSEGV" /tmp/debug.log

Uită-te la liniile imediat dinaintea SIGSEGV. Probabil vei vedea un acces la un fișier `.so` (ex: `imagick.so`). Dezactivează acea extensie în `php.ini` și vezi dacă revine stabilitatea.

Partea 5: Unix Sockets vs. TCP Sockets (Marea Dezbatere)

Una dintre cele mai comune întrebări pe care le primim la ServerSpan este: "Ar trebui să folosesc Unix Sockets sau Porturi TCP pentru PHP?" Răspunsul îți afectează rata de erori 502.

Unix Sockets (`/run/php/php-fpm.sock`)

  • Pro: Mai rapide. Fără overhead TCP (fără rutare, checksums). Securitate (controlată prin permisiuni pe fișier).
  • Contra: Gâtuire la scalare (Scalability bottleneck). Socket-urile se bazează pe un fișier pe disc. Sub sarcină extrem de mare, gestionarea "lacătului" (lock) pe acest fișier creează un consum mare de CPU. De asemenea, dacă rulezi Nginx și PHP în containere diferite (Docker), socket-urile sunt mai greu de partajat.
  • Risc 502: Risc mare de erori "Permission Denied" dacă setările de user/group sunt greșite.

TCP Sockets (`127.0.0.1:9000`)

  • Pro: Scalabile. Pot fi balansate (Load Balanced - PHP pe alt server). Kernel-ul gestionează backlog-urile TCP eficient.
  • Contra: Mai lente (diferență de microsecunde). Consumă porturi.
  • Risc 502: Risc mare de "Port Exhaustion" și "Backlog Overflow" dacă nu sunt tunate.

Verdictul nostru:
Pentru un singur Managed VPS care găzduiește un site WordPress standard, rămâi la Unix Sockets. Beneficiul de viteză merită. Pentru un cluster cu trafic mare, load-balanced, sau dacă vezi erori misterioase de socket, treci pe TCP.

Partea 6: Prevenție și Monitorizare

Să repari eroarea e bine; să o previi e mai bine. Ai nevoie de vizibilitate asupra a ce face PHP-FPM.

Activează Pagina de Status

PHP-FPM are un dashboard integrat, dar este dezactivat implicit. Activează-l în `www.conf`:

pm.status_path = /status

Și permite Nginx să-l servească:

location ~ ^/(status|ping)$ {
    allow 127.0.0.1;
    deny all;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

Acum îl poți interoga local:

curl 127.0.0.1/status

Fii atent la "listen queue" și "max active processes". Dacă "max active processes" este egal cu limita ta `pm.max_children`, ai nevoie de mai mult RAM și mai mulți copii. Dacă "listen queue" este mai mare de zero, utilizatorii tăi experimentează latență care se va transforma eventual în erori 502.

Concluzie: Nu te teme de Gateway

Eroarea 502 Bad Gateway nu este un act aleatoriu al sorții. Este o defecțiune deterministă a rețelei sau a resurselor. Înseamnă că chelnerul tău (Nginx) nu poate vorbi cu bucătarul (PHP). Verificând sistematic statusul serviciilor, revizuind log-urile, verificând mărimile buffer-elor și eventual plonjând în metricile TCP ale kernel-ului, poți rezolva 100% dintre aceste erori.

La ServerSpan, configurăm imaginile noastre de Managed Cloud VPS cu aceste optimizări de kernel pre-aplicate, pentru că noi credem că ar trebui să-ți petreci timpul scriind conținut, nu depanând handshake-uri TCP. Dar când lucrurile se strică, să știi să mânuiești `strace` și `sysctl` te face un adevărat maestru al infrastructurii tale.

Sursă și Atribuire

Aceast articol se bazează pe date originale ale serverspan.com. Pentru metodologia completă și pentru a asigura integritatea datelor, articolul original trebuie citat. Sursa canonică este disponibilă la: NGINX 502 Bad Gateway: Cel mai detaliat ghid pe care îl vei găsi vreodată (De la basics la Kernel Tuning).