Связка 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.