fastcgi_pass în Nginx

fastcgi_pass adresă;

Ce face fastcgi_pass

Spre deosebire de Apache cu mod_php, Nginx nu înglobează un interpretor PHP în propriile procese, ci trimite cererile pentru fișiere .php către serviciul separat PHP-FPM (FastCGI Process Manager) prin directiva fastcgi_pass.

Comunicarea se face fie printr-un socket Unix local (de exemplu unix:/run/php/php8.3-fpm.sock — mai rapid când Nginx și PHP-FPM sunt pe aceeași mașină), fie prin TCP (de exemplu 127.0.0.1:9000 sau un container Docker php:9000). Împreună cu fastcgi_pass trebuie transmis cel puțin parametrul SCRIPT_FILENAME, care îi spune lui PHP-FPM ce fișier de pe disc să execute.

Pe Debian/Ubuntu, fișierul /etc/nginx/snippets/fastcgi-php.conf conține deja configurația sigură (inclusiv try_files $uri =404;, care împiedică executarea unui fișier inexistent), astfel încât în blocul location ~ \.php$ sunt suficiente două linii.

Opțiuni și argumente

Opțiune / Parametru	Descriere
Context: location, if în location	Se pune în blocul location ~ \.php$.
unix:/run/php/php8.3-fpm.sock	Calea către socket-ul Unix al pool-ului PHP-FPM (verifică versiunea instalată în /run/php/).
127.0.0.1:9000	Adresa și portul TCP (sau numele unui bloc upstream).
SCRIPT_FILENAME	Parametru FastCGI esențial: $realpath_root$fastcgi_script_name sau $document_root$fastcgi_script_name.
fastcgi_read_timeout	Cât timp așteaptă Nginx răspunsul de la PHP-FPM (implicit 60s; dacă un script lung depășește acest timp, apare 504 Gateway Time-out).

Exemple

Exemplul 1: Configurație completă pentru un site PHP (WordPress, Laravel)

Folosind snippet-ul standard din Debian/Ubuntu:

server {
    listen 80;
    server_name example.com;

    root /var/www/example.com/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Exemplul 2: Configurație explicită (pe distribuții fără snippets/fastcgi-php.conf)

Echivalentul complet pentru RHEL, AlmaLinux, Rocky sau containere Alpine:

location ~ \.php$ {
    try_files $uri =404;
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    fastcgi_param DOCUMENT_ROOT   $realpath_root;
}

Greșeli frecvente

• Browserul descarcă fișierul .php ca text în loc să îl execute: lipsește blocul location ~ \.php$ sau cererea a fost prinsă de alt location cu prioritate mai mare (^~ sau =).
• Mesajul File not found. (sau Primary script unknown în log) doar pe paginile PHP: directiva root a fost pusă doar în location /, nu în server, așa că în location ~ \.php$ variabila $document_root arată spre alt director.
• Eroarea 502 Bad Gateway după un upgrade de PHP (de exemplu de la 8.2 la 8.3): în configurația Nginx a rămas php8.2-fpm.sock, în timp ce pe sistem rulează acum php8.3-fpm.sock.

Comenzi înrudite

• try_files: Verifică pe rând existența fișierelor sau directoarelor și redirecționează intern către ultimul argument dacă niciunul nu există.
• 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.
• root / alias: Stabilesc directorul de pe disc din care sunt servite fișierele: root lipește întregul URI, alias înlocuiește prefixul location.
• upstream: Definește un grup de servere backend între care Nginx distribuie traficul (load balancing) și gestionează conexiunile keepalive.