PHP-FPM и nginx: настройка связки
PHP-FPM запускает PHP-скрипты, а nginx принимает HTTP-запросы, отдаёт статические файлы и передаёт выполнение PHP по FastCGI. Чтобы связка заработала, адрес пула должен совпасть с fastcgi_pass, а SCRIPT_FILENAME — указывать на файл, доступный процессам PHP-FPM.
Как nginx передаёт запросы в PHP-FPM
PHP-FPM (FastCGI Process Manager) управляет рабочими процессами PHP. Рабочие процессы объединены в пулы. У каждого пула свой адрес прослушивания, пользователь и лимит одновременно выполняемых запросов. Один экземпляр FPM может обслуживать несколько сайтов через разные пулы.
Для запроса к приложению nginx выбирает блок location, формирует параметры FastCGI и подключается к пулу. Параметр SCRIPT_FILENAME говорит PHP-FPM, какой файл выполнить. Параметры запроса, например QUERY_STRING и REQUEST_METHOD, передаются отдельно. PHP-FPM возвращает статус, заголовки и тело ответа, которые nginx отправляет клиенту.
При поиске по запросам nginx php и nginx php fpm часто встречаются примеры под разные дистрибутивы. Сверяйте имя службы, путь к файлу пула, адрес listen и пользователя рабочих процессов nginx с вашей установкой.
Настройка PHP-FPM: пул, процессы и права
Ниже пример отдельного пула для PHP 8.4 на Debian или Ubuntu. Установите nginx и пакет FPM для выбранной ветки из репозитория вашей системы. Поместите конфигурацию в каталог, подключаемый основным конфигом FPM. Для пакетной установки PHP 8.4 на Debian и Ubuntu типичный путь — /etc/php/8.4/fpm/pool.d/site.conf.
[site]
; Пользователь приложения должен существовать в системе.
user = app
group = app
; Рабочие процессы nginx подключаются к этому сокету.
listen = /run/php/site.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
; Стартовые значения для небольшого пула.
pm = dynamic
pm.max_children = 8
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3
; Разрешаем выполнение основного скрипта с расширением .php.
security.limit_extensions = .php
php_admin_flag[display_errors] = off
php_admin_flag[log_errors] = onЗамените www-data на пользователя и группу, под которыми работают воркеры nginx. При использовании listen.acl_users или listen.acl_groups проверьте ACL сокета: на системах с поддержкой POSIX ACL эти параметры имеют приоритет над listen.owner и listen.group. Проверьте также права прохода по родительским каталогам. Пользователь app должен читать код и писать в каталоги, где приложение хранит кеш, сессии или загрузки. nginx нужен доступ к публичной статике и к сокету.
pm.max_children ограничивает число PHP-запросов, которые пул выполняет одновременно. Число 8 в примере служит отправной точкой. Подбирайте лимит по памяти рабочих процессов под характерной нагрузкой, оставляя запас для nginx, ОС и соседних служб. При pm = static число процессов постоянно. При pm = ondemand процессы запускаются по запросу и завершаются после простоя. При pm = dynamic FPM поддерживает заданный диапазон свободных процессов.
nginx и PHP-FPM: конфигурация сайта
Пример подходит для приложения с единой точкой входа public/index.php. Каталог public является корнем сайта. Конфигурация приложения, зависимости и другие закрытые файлы находятся выше него. Существующая статика отдаётся напрямую. Остальные запросы передаются в index.php с исходной строкой запроса.
server {
listen 80;
server_name app.test;
root /srv/site/public;
index index.php;
location / {
# Проверяем файл или каталог, затем передаём запрос приложению.
try_files $uri $uri/ /index.php?$query_string;
}
location = /index.php {
# Проверяем наличие точки входа перед обращением к FPM.
try_files $uri =404;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass unix:/run/php/site.sock;
}
# Закрываем прямые запросы к остальным PHP-файлам.
location ~* \.php(?:/|$) {
return 404;
}
}Поместите блок в конфигурацию, которую nginx загружает из контекста http. В примере используется стандартный fastcgi_params без определения SCRIPT_FILENAME. Проверьте комплектный файл: если параметр уже задан в подключаемом фрагменте, оставьте одно определение с правильным путём. В этой конфигурации FPM получает /srv/site/public/index.php. Если nginx и FPM работают в разных контейнерах, этот путь должен существовать внутри контейнера FPM. Для проверки через try_files точка входа должна быть доступна и nginx.
Проверка выполнения PHP
Для нового тестового сайта сохраните этот код в public/index.php. Он возвращает короткий ответ и позволяет проверить выполнение PHP через nginx.
<?php
declare(strict_types=1);
// Возвращаем короткий текстовый ответ для проверки FastCGI.
function healthMessage(): string
{
return "PHP-FPM работает\n";
}
header('Content-Type: text/plain; charset=UTF-8');
echo healthMessage();Проверьте конфигурации и перечитайте их. Команды ниже рассчитаны на пакетную установку PHP 8.4 и systemd. Выполняйте перезагрузку конфигурации после успешной проверки соответствующей службы.
# Проверяем конфигурации PHP-FPM и nginx.
sudo php-fpm8.4 -t
sudo nginx -t
# Перечитываем конфигурации запущенных служб.
sudo systemctl reload php8.4-fpm
sudo systemctl reload nginxДля локальной проверки направьте имя app.test на сервер. Откройте корень сайта, затем заведомо отсутствующий путь, например /probe. Оба запроса должны вернуть текст из index.php. Запрос к /other.php должен вернуть 404. Если приложение содержит собственный маршрутизатор, итоговый статус для /probe определяет приложение.
Unix-сокет или TCP для FastCGI
Unix-сокет удобен, когда nginx и PHP-FPM работают на одном хосте и имеют общий доступ к каталогу сокета. TCP удобен при раздельных контейнерах или хостах. При смене транспорта меняйте обе стороны: listen в пуле FPM и fastcgi_pass в nginx.
; TCP для nginx и FPM в одном сетевом пространстве.
listen = 127.0.0.1:9000
listen.allowed_clients = 127.0.0.1# Адрес должен совпадать с адресом TCP-пула.
fastcgi_pass 127.0.0.1:9000;При переходе на TCP уберите из пула параметры владельца, группы и режима Unix-сокета. В разных контейнерах 127.0.0.1 указывает на сам контейнер. Используйте внутреннее имя сервиса FPM, например fastcgi_pass php:9000;, и настройте пул на прослушивание интерфейса контейнера. Ограничьте доступ внутренней сетью. Порт FastCGI должен быть доступен только доверенным прокси. Если используете listen.allowed_clients, указывайте IP-адреса клиентов, которые FPM действительно видит.
Почему nginx с PHP возвращает 403, 404, 502 или 504
Начните с журнала ошибок nginx и журнала службы FPM за время одного запроса. Сопоставьте адрес upstream, имя файла и точный текст ошибки. Один статус может возникнуть на разных этапах выполнения.
| Симптом | Что проверить |
|---|---|
502 и No such file or directory при подключении к сокету | Пул запущен, его listen совпадает с fastcgi_pass, сокет виден из окружения nginx. |
502 и Permission denied при подключении к сокету | Права сокета и родительских каталогов, пользователь воркеров nginx, ACL и ограничения SELinux или AppArmor, если они действуют. |
502 и Connection refused при подключении по TCP | FPM слушает нужный адрес и порт в своём сетевом пространстве, nginx подключается к правильному сервису. |
404 и Primary script unknown | Значение SCRIPT_FILENAME, наличие файла и права доступа к нему со стороны FPM. При chroot проверьте путь внутри него. |
| 403 на корне сайта | Доступ к каталогу, директиву index и наличие индексного файла. Журнал nginx покажет, запрещён ли просмотр каталога или сработало другое правило доступа. |
504 и upstream timed out | На каком этапе nginx дождался таймаута, заняты ли воркеры FPM, задерживают ли ответ запросы к БД или внешним сервисам. |
Если файл PHP скачивается или отображается как текст, закройте доступ к сайту и проверьте выбранный server, правила location и наличие fastcgi_pass. При раскрытии конфигурации или секретов замените затронутые ключи и пароли.
При повторяющихся 504 включите журнал медленных запросов FPM через request_slowlog_timeout и slowlog. Он помогает найти код, на котором задержался воркер. Настройте таймауты приложения и внешних запросов по требуемому времени ответа. fastcgi_read_timeout задаёт допустимый интервал между чтениями данных от upstream. Для ограничения времени обслуживания запроса в FPM предусмотрен request_terminate_timeout.
Apache и PHP: чем отличается конфигурация
В случае apache php распространены две схемы. Первая — Apache передаёт запросы в тот же PHP-FPM через mod_proxy_fcgi. Вторая — PHP загружается как модуль Apache, обычно вместе с mpm_prefork. При переходе с модуля на FPM PHP выполняется в отдельных процессах, а параметры php_value и php_flag из .htaccess следует перенести в конфигурацию PHP или пула. Проверьте значения на уровне веб-приложения: у CLI и FPM могут быть разные файлы php.ini.
nginx не читает .htaccess. При переносе сайта с Apache перенесите правила маршрутизации, редиректы и ограничения доступа в конфиг nginx. Проверьте корень сайта, закрытые каталоги, старые адреса и страницы, которым нужны параметры запроса. При переходе с Apache и FPM пул можно переиспользовать, если nginx видит его адрес, имеет право подключения и передаёт корректный путь к скрипту.
PHP 8.3–8.5: что меняется при обновлении
На конец 2026 года для этой конфигурации подходят поддерживаемые ветки PHP 8.3, 8.4 и 8.5. Формат основных директив nginx и FPM из примеров одинаков. При переключении версии меняются бинарник, служба, каталог конфигурации и пакетные расширения. Две версии, запущенные параллельно, должны слушать разные сокеты или порты.
- PHP 8.3. Добавлены типизированные константы классов и функция
json_validate(). Для проверки JSON без преобразования в PHP-значение используйте её. Если данные всё равно нужны приложению, достаточноjson_decode()сJSON_THROW_ON_ERROR. - PHP 8.4. Добавлены хуки свойств и функции
array_find(),array_find_key(),array_any()иarray_all(). Неявно nullable-параметры видаstring $name = nullобъявлены устаревшими. Пишите?string $name = null. - PHP 8.5. Появились оператор конвейера
|>и функцияarray_first(). Если приложение должно работать и под 8.3 или 8.4, учитывайте минимальную версию в зависимостях и при выборе синтаксиса.
declare(strict_types=1) задаётся в PHP-файле. Для скалярных аргументов пользовательских функций строгий режим определяется файлом, из которого сделан вызов. Параметры HTTP-запроса по-прежнему нужно проверять и явно преобразовывать перед вызовом типизированного кода.
Чек-лист запуска nginx и PHP-FPM
- Выберите ветку PHP и установите FPM и расширения, которые нужны приложению.
- Укажите публичный каталог в
rootи проверьте, что закрытые файлы лежат вне него. - Сопоставьте
listenпула сfastcgi_pass. Проверьте права на сокет или сетевую доступность порта. - Проверьте
SCRIPT_FILENAMEиз окружения FPM и ограничьте прямое выполнение PHP точками входа приложения. - Проверьте синтаксис конфигураций, перечитайте их и запросите статический файл, PHP-страницу и запрещённый путь.
- Проверьте журналы после первых запросов. Подберите лимит процессов по потреблению памяти и очереди под рабочей нагрузкой.
Частые вопросы
Что такое PHP-FPM и зачем он нужен nginx?
PHP-FPM управляет рабочими процессами PHP и принимает запросы по FastCGI. nginx принимает HTTP-запрос и передаёт его в FPM, когда для ответа нужно выполнить PHP-скрипт.
Что выбрать для nginx и PHP-FPM: Unix-сокет или TCP?
При общем файловом пространстве обычно удобно использовать Unix-сокет и ограничить доступ к нему правами. Для раздельных контейнеров или серверов удобно использовать TCP во внутренней сети. В обоих случаях согласуйте listen и fastcgi_pass.
Можно ли при переходе с Apache на nginx сохранить пул PHP-FPM?
Да. Проверьте доступ nginx к сокету или порту пула, путь к скрипту в SCRIPT_FILENAME и права пользователя FPM. Правила из .htaccess перенесите в конфигурацию nginx.