Зв'язка Nginx і PHP-FPM: сокети, пули і fastcgi_params

Як Nginx передає запити в PHP-FPM

Nginx не вміє виконувати PHP сам — він віддає статику і проксує динамічні запити окремому процесу PHP-FPM (FastCGI Process Manager) за протоколом FastCGI. За це відповідає директива fastcgi_pass усередині блоку location, який ловить файли з розширенням .php. PHP-FPM виконує скрипт і повертає результат назад тим самим каналом.

Зв'язок між Nginx і PHP-FPM можна побудувати двома способами: через Unix-сокет або через TCP-адресу 127.0.0.1:9000. На одному сервері сокет зазвичай швидший і не займає порт, а TCP зручний, коли PHP-FPM працює в окремому контейнері чи на іншій машині. На віртуальному хостингу і VDS ZevsHost.net з cPanel і ISPmanager 6 частіше використовують сокет — панель створює його автоматично для кожного користувача.

Налаштування location для .php-файлів

Базовий блок для сайту на PHP виглядає так — збіг за regex, передача сокета і обов'язковий SCRIPT_FILENAME.

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Без SCRIPT_FILENAME PHP-FPM не зрозуміє, який файл виконувати, і поверне порожню сторінку або помилку "No input file specified". Файл fastcgi_params зазвичай лежить у /etc/nginx/ і підключається директивою include — переписувати його цілком не потрібно, достатньо додати відсутні параметри поверх.

Сокет чи TCP: як обрати і не втратити з'єднання

Різниця між способами підключення — у швидкості і в лімітах на кількість одночасних з'єднань.

Якщо в логах Nginx з'являється помилка connect() to unix:/run/php/php8.3-fpm.sock failed (11: Resource temporarily unavailable), значить черга на сокеті переповнена: пул PHP-FPM не встигає обробляти запити. Рішення — збільшити listen.backlog у пулі або підняти кількість робочих процесів.

Налаштування пулу PHP-FPM під навантаження

Пул описується у файлі виду /etc/php/8.3/fpm/pool.d/www.conf. Три параметри керують тим, скільки запитів PHP-FPM обробляє одночасно.

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 8

pm.max_children — жорстка стеля процесів-воркерів. Її рахують за формулою: доступна пам'ять мінус пам'ять під систему і Nginx, поділена на середній розмір одного процесу PHP (зазвичай 40-80 МБ для CMS на кшталт WordPress). Якщо поставити значення завеликим, сервер піде у своп під час пікового навантаження; замалим — Nginx почне отримувати 502 при сплеску запитів.

Діагностика: де шукати причину, якщо сайт не відкривається

Порядок перевірки при помилці 502 або 504 на сайті з PHP-FPM:

• Статус сервісу: systemctl status php8.3-fpm.
• Шлях до сокета в конфізі пулу збігається зі шляхом у fastcgi_pass.
• Лог PHP-FPM у /var/log/php8.3-fpm.log на предмет "max_children reached".
• Лог Nginx у /var/log/nginx/error.log на предмет "upstream timed out".

Розбір конкретних кодів помилок 502 і 504 з командами для кожного випадку винесено в окрему статтю про діагностику 502 і 504. Загальні правила про те, який location спрацює першим для .php-файлів, — у статті про пріоритет location.

Підсумок: перелік перевірок зв'язки Nginx і PHP-FPM

• Шлях сокета чи TCP-адреса в fastcgi_pass збігається з listen у пулі PHP-FPM.
• Параметр SCRIPT_FILENAME заданий явно, а не успадкований зі старого шаблону конфігу.
• pm.max_children розрахований від обсягу оперативної пам'яті сервера, а не залишений за замовчуванням.
• Після правок конфігів виконані nginx -t і systemctl reload php8.3-fpm.
• Налаштована зв'язка з версією PHP, яка справді стоїть на сервері — перевірити через статтю про встановлення Nginx і вивід php -v.