Як діагностувати помилки 502 і 504 у WordPress через PHP-FPM

Чим відрізняються 502 і 504

Код 502 означає, що проксі-сервер, зазвичай Nginx, отримав від PHP-FPM некоректну відповідь або взагалі не зміг підключитися до FastCGI-сервісу. Найчастіші причини — неактивний PHP-FPM, неправильний шлях до Unix-сокета, недостатні права доступу або аварійне завершення процесу.

Код 504 означає тайм-аут: Nginx підключився до PHP-FPM і передав запит, але відповідь не надійшла в допустимий час. PHP-код міг зависнути на SQL-запиті, очікувати зовнішній API, виконувати великий імпорт або працювати з перевантаженим диском чи базою даних.

Один і той самий сайт може повертати обидва коди в різних ситуаціях. Тому важливо орієнтуватися не лише на сторінку помилки, а на точний запис у логах і час виникнення проблеми.

• 502: спочатку перевіряйте доступність PHP-FPM і відповідність сокета в конфігураціях.
• 504: шукайте повільну операцію, яка утримує PHP-процес довше за встановлений таймаут.
• Якщо помилка виникає лише під навантаженням, перевіряйте пул PHP-FPM, CPU, RAM, диск і базу даних.

Почніть із логів у момент помилки

Перша діагностична дія — відкрити логи до повторення проблеми або відтворити помилку під час їх перегляду. Шляхи до файлів залежать від дистрибутива, версії PHP та налаштувань сервера, тому наведені команди потрібно адаптувати до конкретної системи.

Для Nginx корисно стежити за журналом помилок, а стан PHP-FPM — перевіряти через systemd. Якщо назва сервісу відома, краще використовувати її явно, наприклад php8.2-fpm.

• Шукайте записи про connect() до php-fpm.sock, upstream timed out, recv() failed, connection reset та upstream prematurely closed connection.
• Зіставляйте час запису в Nginx із журналом PHP-FPM і PHP error log.
• Перевірте, чи не перезапускався PHP-FPM через нестачу пам’яті або помилку конфігурації.

tail -f /var/log/nginx/error.log
journalctl -u php8.2-fpm -f
systemctl status php8.2-fpm

# Пошук типових повідомлень у журналі Nginx
grep -Ei "upstream|fastcgi|timed out|connect\(\)" /var/log/nginx/error.log | tail -n 50

Як читати ключові повідомлення

Повідомлення на кшталт connect() to unix:/run/php/php-fpm.sock failed вказує на проблему під час підключення до сокета. Це може бути неправильний шлях, відсутній файл, відсутній сервіс або відмова в доступі. upstream timed out зазвичай говорить про те, що PHP-FPM не встиг завершити обробку запиту.

Рядок server reached pm.max_children означає, що всі дочірні PHP-процеси пулу вже зайняті. Це не обов’язково означає, що ліміт потрібно одразу збільшити: спочатку з’ясуйте, чому процеси так довго не звільняються.

• Не плутайте помилку підключення до сокета з повільним виконанням PHP.
• Перевіряйте журнал саме того PHP-FPM-сервісу, який обслуговує сайт.
• Зберігайте кілька рядків до і після помилки — контекст часто важливіший за один запис.

Перевірка PHP-FPM і FastCGI-сокета

Nginx передає PHP-запити до PHP-FPM через Unix-сокет або TCP-адресу. У конфігурації Nginx значення fastcgi_pass має відповідати параметру listen у конфігурації пулу PHP-FPM. Якщо один сервіс слухає /run/php/php8.2-fpm.sock, а Nginx звертається до іншого шляху, сайт повертатиме 502.

Окрім шляху, перевірте власника та права сокета. Користувач Nginx, часто www-data або nginx, повинен мати можливість підключатися до нього. Не змінюйте права на 777: це створює зайвий ризик і приховує справжню проблему.

• Перевірте стан PHP-FPM: systemctl status php*-fpm.
• Знайдіть фактичний сокет: ls -l /run/php/ або ss -lx | grep php.
• Порівняйте listen у pool-конфігурації з fastcgi_pass у virtual host Nginx.
• Після зміни конфігурації перевірте її синтаксис і лише потім перезавантажуйте сервіс.

grep -R "^listen" /etc/php/*/fpm/pool.d/
grep -R "fastcgi_pass" /etc/nginx/
nginx -t
php-fpm8.2 -t
systemctl reload nginx
systemctl restart php8.2-fpm

Коли PHP-FPM вичерпує процеси

PHP-FPM працює пулом дочірніх процесів. Якщо всі вони зайняті, нові запити чекатимуть у черзі, а згодом Nginx може повернути 504. У логах це часто видно як server reached pm.max_children. Джерелом проблеми можуть бути WooCommerce-запити, важкий пошук, резервне копіювання, імпорт товарів, WP-Cron або плагін, який виконує довгу операцію.

Параметр pm.max_children не можна збільшувати без урахування доступної оперативної пам’яті. Кожен PHP-процес споживає пам’ять, а її дефіцит провокує swap, завершення процесів OOM-killer і нові 502/504. Оптимальне значення залежить від навантаження, версії PHP, коду та обсягу RAM.

• Перевірте використання RAM, CPU, swap і load average під час помилки.
• Подивіться, скільки процесів PHP-FPM реально працює та чи не накопичується черга.
• Увімкніть slow log PHP-FPM і встановіть request_slowlog_timeout для пошуку повільних PHP-викликів.
• Перевірте max_execution_time, memory_limit і ліміти пулу, але змінюйте їх поступово.
• Знайдіть причину тривалого виконання до збільшення pm.max_children.

free -h
uptime
ps -eo pid,ppid,%mem,%cpu,etime,cmd | grep '[p]hp-fpm'

# Назви параметрів, які варто перевірити у конфігурації pool
pm = dynamic
pm.max_children
pm.max_requests
request_slowlog_timeout
slowlog

Як відрізнити повільний PHP-код від проблеми MySQL

504 не завжди означає, що PHP-код сам по собі складний. Скрипт може чекати на MySQL, блокування таблиці, повільний диск або зовнішній сервіс. Якщо помилка виникає на сторінці каталогу, оформленні замовлення чи під час імпорту, перевірте базу даних і запити, які виконує конкретний сценарій.

Для пошуку проблеми корисно тимчасово відтворити запит у тестовий час, перевірити активні процеси бази даних і slow query log. У WordPress також варто ізолювати плагіни: якщо проблема зникає після вимкнення конкретного розширення на копії або в безпечному режимі, напрямок пошуку стає очевиднішим.

• Перевірте, чи не збігається помилка з імпортом, резервним копіюванням або запуском WP-Cron.
• Для WooCommerce окремо перевірте кошик, checkout, адмінські звіти та фонові завдання.
• Подивіться slow query log MySQL/MariaDB та активні запити під час зависання.
• Не вимикайте плагіни на робочому сайті без плану відновлення; використовуйте staging або резервну копію.
• Перевірте зовнішні HTTP-запити до платіжних систем, API, поштових сервісів і служб аналітики.

mysqladmin processlist
# Або в клієнті MySQL/MariaDB:
SHOW FULL PROCESSLIST;

Таймаути, кешування та безпечне виправлення

Параметри fastcgi_read_timeout, max_execution_time та аналогічні ліміти визначають, скільки система чекає на відповідь. Їх можна коригувати для обґрунтовано довгих операцій, наприклад контрольованого імпорту, але це не лікує завислий запит. Довший таймаут означає, що PHP-FPM-процес довше залишається зайнятим.

Спочатку оптимізуйте запит, плагін або процес імпорту. Для великих операцій використовуйте пакетну обробку, черги або CLI-запуск, якщо це підтримує конкретний інструмент. Кеш сторінок зменшує кількість звернень до PHP для публічних сторінок, але не замінює оптимізацію checkout, адмінки чи персоналізованих запитів.

Після зміни конфігурації перевірте синтаксис, виконайте контрольний запит і подивіться логи повторно. Важливо змінювати один параметр за раз, щоб розуміти, що саме вплинуло на результат.

• Не збільшуйте всі таймаути одночасно і не копіюйте значення з іншого сервера.
• Враховуйте обмеження балансувальника, CDN або reverse proxy, якщо вони є перед Nginx.
• Для довгих завдань краще розділяти операцію на частини, ніж тримати один HTTP-запит відкритим хвилинами.
• Після виправлення перевірте не лише головну сторінку, а й форми, авторизацію, пошук та критичні сценарії WooCommerce.

Типові помилки під час діагностики

Найчастіша помилка — змінити wp-config.php або збільшити PHP memory_limit, коли проблема насправді пов’язана з недоступним сокетом, MySQL чи вичерпаним пулом. Налаштування WordPress важливі, але вони не замінюють перевірку системних сервісів.

Інша помилка — перезапускати Nginx і PHP-FPM без збереження логів. Перезапуск може тимчасово очистити чергу, але водночас знищить ознаки першопричини. Якщо сайт критичний, спочатку зафіксуйте час, повідомлення журналів і поточне навантаження.

Не варто також бездумно збільшувати pm.max_children: це може швидко вичерпати RAM. Спочатку визначте, чи процеси справді потрібні через високий трафік, чи їх утримує один повільний плагін або заблокований запит.

• Не редагуйте робочі конфігурації без резервної копії та перевірки синтаксису.
• Не використовуйте права 777 для сокета або каталогів як універсальне виправлення.
• Не вважайте кожен 504 проблемою WordPress: перевіряйте мережу, базу й зовнішні сервіси.
• Не обмежуйтеся перевіркою тільки одного журналу.