Как диагностировать ошибки 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 и error log PHP.
• Проверьте, не перезапускался ли 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 в конфигурации пула с 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'

# Параметры, которые стоит проверить в конфигурации пула
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: проверяйте сеть, базу данных и внешние сервисы.
• Не ограничивайтесь проверкой только одного журнала.