PHPTime

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.

ini
[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 с исходной строкой запроса.

nginx
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
<?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. Выполняйте перезагрузку конфигурации после успешной проверки соответствующей службы.

Shell
# Проверяем конфигурации 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.

ini
; TCP для nginx и FPM в одном сетевом пространстве.
listen = 127.0.0.1:9000
listen.allowed_clients = 127.0.0.1
nginx
# Адрес должен совпадать с адресом 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 при подключении по TCPFPM слушает нужный адрес и порт в своём сетевом пространстве, 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

  1. Выберите ветку PHP и установите FPM и расширения, которые нужны приложению.
  2. Укажите публичный каталог в root и проверьте, что закрытые файлы лежат вне него.
  3. Сопоставьте listen пула с fastcgi_pass. Проверьте права на сокет или сетевую доступность порта.
  4. Проверьте SCRIPT_FILENAME из окружения FPM и ограничьте прямое выполнение PHP точками входа приложения.
  5. Проверьте синтаксис конфигураций, перечитайте их и запросите статический файл, PHP-страницу и запрещённый путь.
  6. Проверьте журналы после первых запросов. Подберите лимит процессов по потреблению памяти и очереди под рабочей нагрузкой.

Частые вопросы

Что такое 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.

Справка по теме

Ещё в разделе «Справочник PHP»

Ассоциативные и многомерные массивы в PHP

Как создавать ассоциативные и многомерные массивы в PHP, читать вложенные данные, получать ключи и значения через array_keys() и array_values().

10 мин

Вывод ошибок в PHP: display_errors, error_reporting и логи

Как включить вывод ошибок PHP через display_errors и ini_set, настроить error_reporting и error_log, найти логи и разобраться с deprecated в PHP 8.3–8.5.

9 мин

Дата и время в PHP: date, DateTime и часовые пояса

Как получить текущую дату и время в PHP, настроить часовой пояс, разобрать строку и отформатировать дату с date(), strtotime() и DateTimeImmutable.

8 мин

Загрузка файлов на сервер в PHP: $_FILES и безопасность

Как принять файл через $_FILES, проверить размер, MIME-тип и расширение, сохранить его вне публичной папки, выдать на скачивание и обработать ZIP.

10 мин