Ошибка 504 Gateway Timeout: причины и диагностика

HTTP 504 Gateway Timeout означает, что сервер, работающий как gateway или proxy, не получил вовремя ответ от upstream-сервера, необходимый для выполнения запроса. В типичной инфраструктуре пользователь обращается к CDN, балансировщику или Nginx, а тот ждёт приложение. Если установленный предел ожидания истекает раньше ответа upstream, клиент получает 504.

Главная ошибка — сразу увеличивать timeout. Это может убрать симптом на время, но не объясняет, почему backend перестал укладываться в допустимую длительность запроса.

Как устроен 504 Gateway Timeout

клиент → proxy / gateway → upstream
                         ↓
                    ожидание ответа
                         ↓
                  превышен timeout
                         ↓
клиент ← HTTP 504

RFC 9110 определяет 504 как ситуацию, когда gateway или proxy не получил своевременный ответ от upstream.

Чем 504 отличается от 502

502 → proxy получил некорректный ответ или столкнулся с ошибкой взаимодействия
504 → proxy не получил необходимый ответ вовремя

Если upstream-порт сразу отвечает connection refused, ожидать до timeout обычно не требуется. Если соединение установлено, но backend завис на SQL-запросе, более вероятен сценарий 504. Конкретный вывод делается по логам.

Основные причины 504

Медленный запрос к базе данных

Приложение приняло запрос, но ждёт SQL дольше, чем внешний proxy готов ждать ответ.

Признаки:

• 504 возникает на тяжёлых URL;
• время до ошибки повторяется;
• slow query log показывает длинные запросы;
• latency вырос ещё до появления 504;
• лёгкий /health остаётся быстрым.

Блокировки и длинные транзакции

Запрос может не потреблять заметный CPU, а ждать освобождения lock. Пользователь видит зависание, proxy ждёт приложение и возвращает 504.

Исчерпан пул worker

Даже быстрый обработчик становится медленным, если запрос долго ждёт очереди до начала выполнения.

Проверяйте worker pool, backlog, event-loop saturation и connection pools.

Медленная внешняя зависимость

Приложение может ждать БД, платёжный API, Redis, object storage или внутренний сервис. Несколько последовательных вызовов и retries легко превышают внешний timeout.

Сетевая деградация

Потери пакетов, firewall, проблемный маршрут или зависшее TLS-соединение могут заставить proxy ждать, а не получить быстрый отказ.

Несогласованные timeout

Плохая схема:

Nginx ждёт приложение: 10 секунд
приложение ждёт внешний API: 30 секунд

Клиент уже получил 504, а приложение продолжает занимать ресурсы.

Шаг 1. Измерьте код и время

curl -sS -o /dev/null \
  -w 'code=%{http_code} total=%{time_total}s\n' \
  https://example.com/

time_total — полная длительность операции, которую измерил curl.

Если 504 стабильно появляется около одного порога, сравните его с timeout CDN, load balancer, Nginx, ingress и приложения.

Шаг 2. Определите слой, который формирует 504

клиент → CDN → load balancer → Nginx → application

Проверяйте Server, служебные заголовки, request ID и логи. Не называйте любой 504 «ошибкой Nginx», если перед ним есть другие gateway.

Шаг 3. Найдите запрос в proxy logs

sudo tail -n 200 /var/log/nginx/access.log
sudo tail -n 200 /var/log/nginx/error.log

Ищите записи по точному времени и URL. Если есть request ID, найдите тот же идентификатор в application log.

Сообщение error log часто показывает этап, где ожидание завершилось. Интерпретируйте его по документации конкретной версии proxy.

Шаг 4. Проверьте upstream напрямую

curl -sS -o /dev/null \
  -w 'code=%{http_code} total=%{time_total}s\n' \
  http://127.0.0.1:8080/health

• напрямую быстро, через proxy 504 — исследуйте proxy и network path;
• напрямую тоже медленно — проблема ниже proxy;
• соединение не устанавливается — проверяйте процесс, порт и сеть.

В Docker 127.0.0.1 внутри контейнера не является адресом соседнего контейнера.

Шаг 5. Разберите время внутри приложения

очередь → обработчик → SQL → внешний API → сериализация → ответ

Полезны tracing, slow query log, application timings, p95/p99 latency и метрики внешних вызовов.

Среднее время может быть нормальным, если только небольшой процент запросов зависает.

Шаг 6. Проверьте БД

Логика проверки:

1. найти долгие запросы;
2. найти lock waits;
3. проверить connection pool;
4. проверить изменение плана выполнения;
5. сопоставить время деградации с 504.

Не увеличивайте pool механически.

Шаг 7. Проверьте внешние зависимости

Допустим:

API A: 3 с
API B: 4 с
повтор API B: 4 с
обработка: 2 с
итого: 13 с

При внешнем timeout 10 секунд клиент уже получит 504.

Внутренний timeout должен завершаться раньше внешнего, чтобы приложение успевало сформировать контролируемый ответ.

Шаг 8. Docker и Kubernetes

Docker:

docker ps
docker stats
docker logs --since 10m <container_name>

Kubernetes:

kubectl get pods
kubectl describe pod <pod-name>
kubectl logs <pod-name> --since=10m
kubectl get events --sort-by=.lastTimestamp

Проверяйте readiness, restarts, OOMKilled, CPU throttling, replicas и состояние Service/Ingress.

Когда увеличение timeout оправдано

Только если доказано, что операция:

• должна быть синхронной;
• имеет ожидаемую длительность;
• действительно выполняет полезную работу;
• приемлема для пользователя;
• не создаёт недопустимую нагрузку.

Если операция занимает десятки секунд или минуты, часто правильнее сделать её асинхронной.

Почему большой timeout опасен

медленный dependency
↓
запросы держатся дольше
↓
заняты worker / connections
↓
растёт очередь
↓
ещё выше latency

Timeout — часть управления ресурсами, а не просто «запас времени».

Как проверить восстановление

for i in {1..20}; do
  curl -sS -o /dev/null \
    -w '%{http_code} %{time_total}\n' \
    https://example.com/
  sleep 1
done

Смотрите не только код, но и latency.

Один успешный запрос не доказывает, что все backend восстановились.

Как предотвращать 504

• задавать конечные timeout для внешних вызовов;
• ограничивать retries;
• контролировать p95/p99 latency;
• искать медленные SQL-запросы;
• выносить длительные операции в фон;
• контролировать pools и очереди;
• отслеживать latency после deployment;
• мониторить критичные endpoint снаружи.

Автоматическое обнаружение

UpWatch можно использовать для регулярной HTTP-проверки публичного endpoint. После обнаружения корневая причина всё равно ищется по proxy, application, database и infrastructure telemetry.

Типичные ошибки

Сразу увеличивать proxy_read_timeout

Вы меняете порог симптома, не выясняя, что стало медленным.

Проверять только /health

Лёгкий endpoint может отвечать 200, пока реальный бизнес-запрос завершается 504.

Смотреть только среднее время

Проблема часто находится в хвосте распределения.

Практический чек-лист

1. Измерить HTTP-код и time_total.
2. Определить gateway, сформировавший 504.
3. Найти запрос в proxy log.
4. Проверить upstream напрямую.
5. Разобрать длительность внутри приложения.
6. Проверить БД и внешние зависимости.
7. Проверить иерархию timeout.
8. Проверить контейнеры и кластер.
9. Только затем менять timeout.
10. Подтвердить восстановление серией запросов.

Источники и спецификации

• RFC 9110: 504 Gateway Timeout
• curl: официальная документация --write-out