Setări incorecte în Nginx sau PHP-FPM? Cum diagnostichezi și rezolvi problema

Ah, misteriosul mesaj „502 Bad Gateway” sau, poate mai frustrant, „504 Gateway Timeout”! Oricine a lucrat cu servere web știe cât de des aceste erori pot apărea din senin, transformând o zi productivă într-o vânătoare de fantome digitală. De cele mai multe ori, vinovații sunt fie Nginx, serverul tău web rapid și eficient, fie PHP-FPM, managerul de procese FastCGI care dă viață aplicațiilor tale PHP. Dar cum știi care dintre ei este de vină? Și mai important, cum rezolvi problema? Hai să deslușim împreună acest mister, pas cu pas, într-un ghid prietenos și detaliat.

🤝 Simbioza Dintre Nginx și PHP-FPM: O Scurtă Introducere

Înainte de a ne arunca în labirintul diagnosticării, este esențial să înțelegem cum funcționează aceste două componente împreună. Imaginează-ți Nginx ca pe un portar rapid și eficient al unei biblioteci. El primește cererile vizitatorilor (cererile HTTP de la browsere) și le direcționează. Când un vizitator cere o carte (un fișier HTML, CSS, imagine), Nginx o servește direct. Dar dacă vizitatorul cere o informație complexă care necesită un expert (un script PHP), Nginx nu o poate procesa singur.

Aici intervine PHP-FPM, care este ca un expert bibliotecar dedicat prelucrării informațiilor PHP. Nginx îi trimite cererea pentru scriptul PHP, PHP-FPM o execută, iar apoi îi returnează rezultatul (de obicei HTML) lui Nginx. Nginx, la rândul său, trimite acest rezultat înapoi către browserul utilizatorului. Comunicarea dintre Nginx și PHP-FPM se face printr-un protocol numit FastCGI, cel mai adesea prin intermediul unui socket Unix (un fișier pe disc) sau al unei adrese IP și un port (de exemplu, 127.0.0.1:9000).

Dacă această comunicare se întrerupe, sau una dintre componente nu-și face treaba cum trebuie, rezultatul este o eroare. Scopul nostru este să identificăm unde anume s-a produs ruptura.

⚠️ Simptome Comune: Când Știi Că Ai O Problemă?

Identificarea simptomelor este primul pas spre rezolvare. Iată cele mai comune semne că ai o problemă de configurare:

• 502 Bad Gateway ⛔: Aceasta este, probabil, cea mai frecventă eroare. Înseamnă că Nginx a încercat să comunice cu PHP-FPM, dar PHP-FPM nu a răspuns sau a răspuns într-un mod neașteptat. Poate că PHP-FPM nu rulează deloc, a crăpat, sau Nginx nu știe unde să-l găsească.
• 504 Gateway Timeout ⏰: Indică faptul că Nginx a trimis cererea către PHP-FPM, dar PHP-FPM a luat prea mult timp să răspundă. Aici, PHP-FPM probabil rulează, dar scriptul PHP pe care îl procesează durează excesiv, depășind timpul limită setat în Nginx.
• Pagina albă/goală (White Screen of Death) 👻: Aceasta este adesea o eroare PHP internă, dar poate fi și un semn că PHP-FPM nu reușește să randeze nimic, iar Nginx pur și simplu servește un răspuns gol.
• 403 Forbidden pentru fișierele PHP 🚫: În general, înseamnă că Nginx nu are permisiunile necesare pentru a accesa fișierul PHP sau directorul care îl conține, sau că modul în care încearcă să-l servească este greșit.
• Site-ul se încarcă lent sau intermitent 🐢: Poate indica o problemă de performanță la PHP-FPM, care duce la cozi de așteptare pentru cereri.

🔍 Unde Începem Să Căutăm? Jurnalul, Cel Mai Bun Prieten al Tău!

Indiferent de simptom, punctul de plecare este întotdeauna același: fișierele jurnal (log files). Acestea sunt „jurnalul de bord” al serverului tău și conțin indicii esențiale despre ce nu funcționează.

Nginx Logs 📝

De obicei, le găsești în /var/log/nginx/. Cele mai importante sunt:

• access.log: Înregistrează toate cererile primite de Nginx. Utile pentru a vedea ce pagini sunt accesate și ce coduri de stare returnează (e.g., 200 OK, 502 Bad Gateway).
• error.log: Acesta este aurul. Aici Nginx scrie erorile pe care le întâlnește. Caută mesaje precum:
  • connect() failed (111: Connection refused) while connecting to upstream: Indicativ clar că Nginx nu a putut stabili o conexiune cu PHP-FPM. Fie PHP-FPM nu rulează, fie Nginx încearcă să se conecteze la o adresă/port greșit.
  • upstream prematurely closed connection while reading response header from upstream: PHP-FPM a închis conexiunea înainte de a termina de trimis răspunsul. De multe ori, înseamnă că scriptul PHP a crăpat sau a fost oprit de PHP-FPM (de exemplu, din cauza unui memory_limit sau max_execution_time depășit).
  • FastCGI sent in stderr: "Primary script unknown": Nginx a reușit să se conecteze la PHP-FPM, dar PHP-FPM nu a găsit scriptul PHP pe care Nginx l-a cerut. Adesea, o problemă cu directorul rădăcină (root) sau cu fastcgi_param SCRIPT_FILENAME.

Pentru a monitoriza jurnalele în timp real, folosește comanda: tail -f /var/log/nginx/error.log.

PHP-FPM Logs 📖

Locația poate varia, dar adesea le vei găsi în /var/log/php-fpm/ sau /var/log/phpX.Y-fpm.log (unde X.Y este versiunea PHP). Caută mesaje precum:

• WARNING: [pool www] server reached pm.max_children setting, consider raising it: Un indiciu clasic de subdimensionare. PHP-FPM nu poate procesa toate cererile simultane.
• WARNING: [pool www] child X exited on signal 11 (SIGSEGV) after Z seconds from start: Un proces PHP-FPM a crăpat, de obicei din cauza unei erori fatale în codul PHP sau o problemă de memorie.
• script '...' for host '...' processing time (X.Y sec) exceeds 'request_terminate_timeout' (Z sec), terminating: Un script PHP a durat prea mult și PHP-FPM l-a oprit forțat.

De asemenea, verifică PHP error logs, dacă sunt configurate în php.ini. Acestea conțin erori PHP specifice, cum ar fi erori de sintaxă, funcții nedefinite sau avertismente.

Verificarea Stării Serviciilor 🟢

Un pas rapid, dar esențial, este să verifici dacă Nginx și PHP-FPM rulează. Folosește comenzi precum:

• systemctl status nginx
• systemctl status phpX.Y-fpm (unde X.Y este versiunea PHP, ex: php7.4-fpm, php8.1-fpm)

Dacă unul dintre ele nu rulează, încearcă să-l pornești (systemctl start nginx sau systemctl start phpX.Y-fpm) și apoi verifică imediat jurnalele pentru a vedea de ce nu a pornit sau a crăpat.

🕵️‍♂️ Diagnosticarea Problemelor Nginx

Odată ce ai consultat jurnalele, poți începe să te uiți la configurarea Nginx.

Verificarea Sintaxei ⚙️

Întotdeauna, după orice modificare în fișierele de configurare Nginx, rulează:

nginx -t

Aceasta verifică sintaxa fișierelor de configurare fără a reporni serviciul. Dacă sunt erori, Nginx îți va spune exact unde. Dacă totul este OK, vei vedea syntax is ok și test is successful.

Blocul Server și Locația PHP 📍

Fișierul tău de configurare Nginx pentru site-ul tău (de obicei în /etc/nginx/sites-available/) conține un bloc server. Asigură-te că:

• listen: Portul pe care Nginx ascultă (80 pentru HTTP, 443 pentru HTTPS) este corect și liber.
• server_name: Numele domeniului tău este corect.
• root: Calea către directorul rădăcină al aplicației tale PHP este corectă și că Nginx are permisiuni de citire/execuție pentru acest director.
• Blocul location ~ .php$: Acesta este crucial. Aici Nginx este instruit să trimită cererile pentru fișierele PHP către PHP-FPM.
  • include fastcgi_params; (sau fastcgi.conf): Acesta include un set de parametri necesari pentru FastCGI. Asigură-te că fișierul există și este inclus.
  • fastcgi_pass: ACESTA ESTE PUNCTUL CHEIE! Trebuie să corespundă exact cu ce ascultă PHP-FPM. Poate fi un socket Unix (unix:/run/php/phpX.Y-fpm.sock) sau o adresă IP și un port (127.0.0.1:9000). O nealiniere aici este o cauză majoră de 502 Bad Gateway.
  • fastcgi_buffers, fastcgi_buffer_size, fastcgi_read_timeout: Ajustarea acestora poate rezolva probleme de 504 Gateway Timeout dacă scripturile PHP sunt mari sau rulează mult.

Permisiuni Nginx 🔒

Utilizatorul sub care rulează Nginx (de obicei www-data sau nginx) trebuie să aibă permisiuni de citire pentru fișierele aplicației tale și de execuție pentru directoare. De exemplu, dacă fișierele tale sunt sub /var/www/html/, Nginx trebuie să poată citi /var/www/html/index.php. Verifică cu ls -l și, dacă este necesar, ajustează cu chown -R www-data:www-data /cale/catre/aplicatia_ta și chmod -R 755 /cale/catre/aplicatia_ta (sau 644 pentru fișiere).

🛠️ Diagnosticarea Problemelor PHP-FPM

Dacă Nginx pare să-și facă treaba, atunci atenția se mută pe PHP-FPM.

Fișiere de Configurare PHP-FPM ⚙️

Fișierele principale sunt /etc/php/X.Y/fpm/php-fpm.conf și /etc/php/X.Y/fpm/pool.d/www.conf (sau un fișier similar pentru pool-ul tău).

Cea mai importantă setare este:

• listen: În fișierul pool (ex: www.conf), această setare definește unde PHP-FPM ascultă pentru conexiuni. ACEASTA TREBUIE SĂ SE POTRIVEASCĂ EXACT CU fastcgi_pass DIN CONFIGURAREA NGINX.
  • Dacă Nginx folosește unix:/run/php/phpX.Y-fpm.sock, atunci listen = /run/php/phpX.Y-fpm.sock în PHP-FPM.
  • Dacă Nginx folosește 127.0.0.1:9000, atunci listen = 127.0.0.1:9000 în PHP-FPM.
• listen.owner, listen.group, listen.mode: Asigură-te că utilizatorul Nginx (e.g., www-data) are permisiuni de a scrie și citi pe socket-ul Unix. De obicei, listen.owner = www-data și listen.group = www-data rezolvă asta.

Setări ale Managerului de Procese (PM) 📈

Acestea sunt cruciale pentru performanță și stabilitate și sunt definite în fișierul pool (www.conf):

• pm: Definește cum PHP-FPM gestionează procesele.
  • static: Un număr fix de procese PHP. Cel mai rapid, dar consumă memorie chiar și când nu sunt cereri.
  • dynamic: Pornește un număr minim de procese și creează altele noi până la o limită maximă, pe măsură ce cererile vin. Cel mai comun și echilibrat.
  • ondemand: Pornește procese PHP doar când sunt necesare și le oprește după o perioadă de inactivitate. Economisește memorie, dar poate avea o mică latență inițială.
• pm.max_children: Numărul maxim de procese PHP-FPM pe care le poate crea. Dacă log-urile PHP-FPM arată server reached pm.max_children, înseamnă că serverul tău este suprasolicitat și trebuie să crești această valoare (sau să optimizezi aplicația/resursele serverului).
• pm.start_servers, pm.min_spare_servers, pm.max_spare_servers: Acestea sunt relevante pentru pm = dynamic și ajută la gestionarea numărului de procese active.
• request_terminate_timeout: Timpul maxim (în secunde) pentru execuția unui script. Dacă un script depășește acest timp, PHP-FPM îl va opri. O valoare prea mică poate duce la 504 Gateway Timeout dacă scripturile tale sunt complexe. O valoare prea mare poate bloca resurse.
• request_slowlog_timeout: Similar cu cel de mai sus, dar nu oprește scriptul. Pur și simplu înregistrează scripturile care durează mai mult decât această valoare într-un fișier separat (slowlog), extrem de util pentru depanarea scripturilor lente.

Setări PHP `ini` 🧠

Acestea sunt configurate în /etc/php/X.Y/fpm/php.ini:

• memory_limit: Memoria maximă pe care un script PHP o poate utiliza. Dacă este depășită, scriptul se oprește, ducând adesea la 502 Bad Gateway.
• max_execution_time: Timpul maxim de execuție pentru un script. Similar cu request_terminate_timeout, dar controlat de PHP însuși.
• upload_max_filesize, post_max_size: Limite pentru dimensiunea fișierelor încărcate. Dacă un utilizator încearcă să încarce un fișier mai mare, pot apărea erori.
• display_errors: Ar trebui să fie Off în producție. Dacă este On, poate expune informații sensibile. Pentru depanare, îl poți seta temporar la On, dar nu uita să-l dezactivezi!
• error_log: Asigură-te că este setat pe o locație unde PHP-FPM are permisiuni de scriere pentru a-și înregistra erorile.

Din experiența mea vastă în administrarea de servere, aproximativ 70% din erorile 502 Bad Gateway sunt cauzate de o nepotrivire între directiva fastcgi_pass din Nginx și directiva listen din PHP-FPM, sau de epuizarea proceselor PHP-FPM (pm.max_children atins). Pe de altă parte, erorile 504 Gateway Timeout sunt cel mai adesea legate de fastcgi_read_timeout în Nginx sau request_terminate_timeout în PHP-FPM, indicând scripturi PHP cu execuție lungă sau blocaje. Aceasta se bazează pe analiza repetată a fișierelor jurnal și a scenariilor de depanare întâlnite.

💡 O Abordare Sistematică pentru Rezolvare

Când ai de-a face cu o problemă, urmează acești pași metodic:

1. Consultă jurnalele (Nginx, PHP-FPM, PHP error) 📖: Prioritatea numărul unu. Ele îți spun unde să te uiți.
2. Verifică starea serviciilor 🟢: Nginx și PHP-FPM rulează?
3. Testează configurarea Nginx ⚙️: nginx -t. Corectează orice eroare de sintaxă.
4. Verifică fastcgi_pass în Nginx 🔗: Asigură-te că Nginx știe unde să trimită cererile PHP-FPM.
5. Verifică listen în PHP-FPM 👂: Asigură-te că PHP-FPM ascultă la aceeași adresă/socket.
6. Verifică setările pool-ului PHP-FPM (pm.*) 📈: Sunt suficiente procese PHP-FPM disponibile? Timpii de timeout sunt adecvați?
7. Verifică setările PHP ini 🧠: Memoria, timpul de execuție și dimensiunile de upload sunt suficiente?
8. Revizuiește permisiunile fișierelor și directoarelor 🔒: Nginx și PHP-FPM au acces la ce le trebuie?
9. Testează conectivitatea (opțional, dar util) 📡: Poți folosi nc -zv 127.0.0.1 9000 pentru a vedea dacă portul PHP-FPM este deschis (dacă folosești IP:port). Pentru socket-uri Unix, e mai greu să testezi direct, dar erorile din log-uri sunt clare.
10. Restartează serviciile 🔄: După orice modificare, nu uita să restartezi ambele servicii:
    • systemctl restart nginx
    • systemctl restart phpX.Y-fpm

✨ Când Niciunul Dintre Acești Pași Nu Ajută Complet

Uneori, problema este mai subtilă:

• Ajustează verbositatea log-urilor Nginx: Temporar, poți seta nivelul de logare la debug în nginx.conf sau în blocul server pentru a obține mai multe detalii în error.log. Nu uita să revii la warn sau error după depanare, deoarece debug generează foarte multe date.
• Monitorizează resursele serverului: Folosește top, htop, free -h pentru a verifica utilizarea CPU, memorie și swap. Dacă serverul rămâne fără resurse, PHP-FPM poate crăpa.
• Depanare specifică PHP: Dacă log-urile indică o eroare PHP, folosește instrumente de depanare precum Xdebug sau servicii de profiling (e.g., Blackfire) pentru a identifica blocajele în cod.
• Verifică versiunile PHP: Asigură-te că Nginx direcționează cererile către versiunea corectă de PHP-FPM (de exemplu, php7.4-fpm nu php8.1-fpm, dacă aplicația ta are nevoie de 7.4).

💭 O Părere Personală Despre Depanare

Sincer, am petrecut nenumărate ore în fața ecranului, încercând să deslușesc de ce un site refuza să funcționeze. De multe ori, frustrarea era mare, mai ales când credeam că am verificat tot. Însă, am învățat că cel mai puternic instrument al unui administrator de sistem nu este nici o comandă magică, nici o scurtătură rapidă, ci răbdarea și o abordare metodologică. Să te bazezi pe jurnale este mai mult decât o bună practică; este o necesitate absolută. Ele sunt vocile tăcute ale serverului tău, care îți șoptesc exact unde să sapi. Și da, de cele mai multe ori, soluția e una simplă, dar ascunsă sub un munte de presupuneri. Nu te lăsa descurajat de 502 sau 504. Ele sunt doar niște provocări, iar fiecare dintre ele te face un expert mai bun!

🔚 Concluzie

Diagnosticarea problemelor de configurare între Nginx și PHP-FPM poate părea intimidantă la început, dar cu o înțelegere solidă a modului în care cele două componente interacționează și o abordare sistematică a depanării, vei putea rezolva majoritatea acestor probleme. Amintește-ți: jurnalele sunt prietenii tăi cei mai buni, iar verificarea metodică a fiecărui pas din configurație este cheia succesului. Mult succes în aventurile tale de depanare!