Ошибка 504 Gateway Timeout: что это и как исправить

Что означает ошибка 504

RFC 9110 (раздел 15.6.5) определяет 504 Gateway Timeout как ответ шлюза или прокси, который не получил своевременный ответ от вышестоящего сервера, к которому ему нужно было обратиться. Иными словами, прокси ждал ответа дольше положенного, сдался и сообщил об этом посетителю.

Сам запрос посетителя корректен. От 502 Bad Gateway, где upstream ответил некорректно или оборвал соединение, 504 отличается тем, что upstream молчал и таймаут истёк. Обычная причина — медленный скрипт, тяжёлый запрос к базе или перегруженный сервер приложений.

Что делать посетителю

1. Обновите страницу. Если 504 появилась из-за пиковой нагрузки, повторный запрос часто проходит.
2. Если ошибка возникла после долгой операции (экспорт, формирование отчёта, загрузка большого файла), не повторяйте её сразу много раз: подождите и попробуйте с меньшим объёмом данных или в другое время.
3. Проверьте доступность сайта из другой сети или через проверку кода ответа: если другие тоже видят 504, дело в сайте.
4. Отключите VPN или прокси: лишний узел на пути добавляет задержку и сам может обрываться по таймауту.
5. Если ошибка постоянная, сообщите владельцу сайта адрес страницы и время. Заранее приложите, что именно вы делали на странице.

Почему возникает 504: что проверить владельцу

• Долгий скрипт или запрос. Выгрузка каталога, импорт, сложный отчёт, неоптимизированный запрос к базе данных (нет индекса, полное сканирование большой таблицы).
• Перегруженный сервер приложений. Все процессы PHP-FPM или воркеры Node.js заняты, и запрос ждёт в очереди дольше таймаута.
• Слишком короткие таймауты. Прокси или PHP отрезают запрос раньше, чем приложение успевает его выполнить. В nginx по умолчанию proxy_read_timeout и fastcgi_read_timeout равны 60 секундам.
• Сеть между прокси и приложением. Фаервол, неверный адрес upstream, проблемы DNS или потеря пакетов: прокси не может даже установить соединение вовремя.
• Зависший внешний сервис. Приложение само ждёт ответа сторонней API, которая тормозит или недоступна.

Найдите медленные запросы

В журнале ошибок nginx 504 выглядит так: upstream timed out (110: Connection timed out) while reading response header from upstream. Чтобы понять, какие запросы тормозят, добавьте в журнал доступа время обработки:

http {
    log_format timing '$remote_addr [$time_local] "$request" $status '
                      '$request_time $upstream_response_time';

    server {
        access_log /var/log/nginx/timing.log timing;
        # ...
    }
}

# 20 самых долгих запросов (предпоследнее поле — $request_time)
awk '{print $(NF-1), $7}' /var/log/nginx/timing.log | sort -rn | head -20

# какие адреса чаще всего заканчиваются 504
awk '$9 == 504 {print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head

На стороне PHP включите журнал медленных запросов в пуле PHP-FPM: он записывает трассировку скриптов, которые выполняются дольше заданного порога.

request_slowlog_timeout = 5s
slowlog = /var/log/php8.2-fpm.slow.log
; жёсткий предел выполнения одного запроса
request_terminate_timeout = 120s

Для базы данных MySQL включите журнал медленных запросов (slow_query_log = 1, long_query_time = 2) и проверьте найденные запросы командой EXPLAIN. Часто индекс решает проблему лучше любого увеличения таймаута.

Таймауты nginx и PHP

Если работа действительно занимает больше минуты и это нормально (например, ручной импорт в админке), согласованно поднимите таймауты во всей цепочке. Достаточно упереться в любой из них, чтобы ошибка осталась.

# PHP через PHP-FPM
location ^~ /admin/export/ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root/index.php;
    fastcgi_read_timeout 300s;
}

# приложение за proxy_pass
location /api/reports/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 10s;
    proxy_read_timeout 300s;
}

После правки проверьте синтаксис командой nginx -t и примените конфигурацию через systemctl reload nginx. Общие принципы настройки сервера собраны в руководстве по nginx.

Как проверить код ответа

Проверяйте не только главную: 504 часто возникает на отдельных тяжёлых адресах (поиск, фильтры каталога, выгрузки). Введите такой URL в инструмент и посмотрите код и время ответа.

Ошибка 504 и индексация

• Для Яндекса и Google 504 — временная серверная ошибка. Робот повторит запрос позже, и пока проблема не затянулась, страница остаётся в индексе.
• Медленные страницы, на которых робот регулярно упирается в таймаут, получают обход реже. Если на сайте много таких URL (бесконечные фильтры, поиск), робот тратит на них лимит обхода.
• Постоянный 504 на странице в течение длительного времени ведёт к её исключению из индекса, точные сроки не фиксируются.
• Закройте от обхода бессмысленные тяжёлые адреса (внутренний поиск, комбинации фильтров) через robots.txt и noindex, а не оставляйте их на таймауте.

Если вы выпускали обновление и вместе с ним правили структуру адресов, держите включённым Monitor404: он покажет, какие URL перестали открываться и куда лучше поставить 301.