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

> Як з'єднати Nginx із PHP-FPM через сокет або TCP, налаштувати пул і fastcgi_params, щоб сайт на PHP не падав під навантаженням.

## Як 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: як обрати і не втратити з'єднання

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

| Спосіб | Приклад адреси | Коли використовувати |
| --- | --- | --- |
| Unix-сокет | unix:/run/php/php8.3-fpm.sock | Nginx і PHP-FPM на одному сервері |
| TCP localhost | 127.0.0.1:9000 | PHP-FPM у контейнері, потрібен явний порт |
| TCP по мережі | 10.0.0.5:9000 | PHP-FPM винесено на окремий сервер |

Якщо в логах 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](https://www.zevshost.net/uk/kb/nginx-502-504-diagnostika/). Загальні правила про те, який location спрацює першим для .php-файлів, — у статті про [пріоритет location](https://www.zevshost.net/uk/kb/nginx-location-prioritet/).

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

- Шлях сокета чи TCP-адреса в `fastcgi_pass` збігається з `listen` у пулі PHP-FPM.
- Параметр `SCRIPT_FILENAME` заданий явно, а не успадкований зі старого шаблону конфігу.
- `pm.max_children` розрахований від обсягу оперативної пам'яті сервера, а не залишений за замовчуванням.
- Після правок конфігів виконані `nginx -t` і `systemctl reload php8.3-fpm`.
- Налаштована зв'язка з версією PHP, яка справді стоїть на сервері — перевірити через [статтю про встановлення Nginx](https://www.zevshost.net/uk/kb/nginx-ustanovka-ubuntu-debian/) і вивід `php -v`.

---

Джерело: https://www.zevshost.net/uk/kb/nginx-php-fpm-svyazka/