В чём разница между 502 и 504

Обе ошибки означают, что Nginx не смог получить нормальный ответ от бэкенда — PHP-FPM, Node.js-приложения или другого прокси-сервера. Но причины разные. 502 Bad Gateway означает, что бэкенд ответил некорректно или соединение оборвалось. 504 Gateway Timeout означает, что бэкенд не ответил за отведённое время — он просто слишком долго думает.

Первый шаг диагностики всегда один: открыть /var/log/nginx/error.log и посмотреть последние строки за момент ошибки.

Как читать error.log при 502

Типичные строки при 502 и что они значают:

Строка в логе	Причина
connect() failed (111: Connection refused)	PHP-FPM или бэкенд не запущен или слушает другой сокет
recv() failed (104: Connection reset by peer)	Бэкенд упал во время обработки запроса, чаще из-за нехватки памяти
upstream sent too big header	Заголовки ответа бэкенда превысили буфер Nginx

Проверьте, что процесс бэкенда вообще жив: systemctl status php8.3-fpm. Если сервис упал, смотрите его собственный лог: /var/log/php8.3-fpm.log.

Как читать error.log при 504

Строка upstream timed out (110: Connection timed out) while reading response header from upstream означает, что PHP-FPM принял запрос, но не ответил за время, заданное в proxy_read_timeout или fastcgi_read_timeout. Обычно так происходит из-за долгого SQL-запроса, внешнего API-вызова без таймаута или нехватки свободных воркеров PHP-FPM.

Проверьте очередь PHP-FPM: systemctl status php8.3-fpm | grep -A2 active и статус пула через fpm-status, если он включён в конфигурации.

Как настроить таймауты правильно

Таймауты нужно поднимать точечно, только для медленных маршрутов, а не глобально для всего сайта:

location /api/export/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_connect_timeout 5s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
}

Для связки с PHP-FPM аналогичные параметры называются fastcgi_connect_timeout, fastcgi_send_timeout и fastcgi_read_timeout. Значение по умолчанию — 60 секунд, поднимать выше 120 секунд почти никогда не нужно: это признак того, что медленный код стоит чинить, а не маскировать таймаутом.

Что проверить на стороне PHP-FPM

Частая причина и 502, и 504 — исчерпание пула воркеров PHP-FPM. Проверьте параметры пула в /etc/php/8.3/fpm/pool.d/www.conf:

pm.max_children — слишком маленькое значение создаёт очередь и таймауты под нагрузкой
pm.max_requests — периодический перезапуск воркеров против утечек памяти
лог медленных запросов slowlog и request_slowlog_timeout — показывает, какой именно код тормозит

Пошаговый чек-лист диагностики

Порядок действий при появлении 502 или 504 на проде:

открыть error.log и найти точную строку ошибки за время инцидента
проверить, жив ли процесс бэкенда: systemctl status
если бэкенд жив — проверить очередь и медленные запросы через slowlog
если проблема в единичном медленном маршруте — поднять таймаут точечно для него
если проблема системная — увеличить pm.max_children и добавить мониторинг памяти

Итог

502 значит, что бэкенд ответил неправильно или упал, 504 — что он не успел ответить вовремя. В обоих случаях решение ищут не в Nginx, а в логах и настройках бэкенда. Если ошибки связаны именно со связкой Nginx и PHP, посмотрите статью Nginx и PHP-FPM: сокеты, пулы и fastcgi_params, а базовые принципы прокси разобраны в статье reverse proxy на Nginx.

502 и 504 в Nginx: как найти причину и починить сайт