Nginx: отдаёт 504 Gateway Timeout — причины и решение

MAATRIX

Пользователь ждёт, страница висит, и Nginx отдаёт 504 Gateway Timeout. Эта ошибка означает одно: Nginx как прокси не дождался ответа от бэкенда — PHP-FPM, приложения, другого сервера — за отведённое время и сдался. Проблема почти всегда не в самом Nginx, а в том, что стоит за ним. Разберём, как быстро найти узкое место и убрать 504.

Первое действие: поймите, кто именно тормозит

504 — это сигнал, что бэкенд не ответил вовремя. Первым делом посмотрите лог ошибок Nginx: там прямо написано, какой upstream и по какому таймауту отвалился.

tail -n 50 /var/log/nginx/error.log

Строки вида upstream timed out (110: Connection timed out) while reading response header from upstream укажут адрес бэкенда и стадию, на которой оборвалось ожидание. Это ключ: если тайм-аут на PHP-FPM — проблема в PHP-скрипте или базе; если на проксируемом приложении — тормозит оно. 504 почти никогда не решается на стороне Nginx в одиночку: он лишь мессенджер. Ваша задача — понять, почему бэкенд отвечает дольше таймаута, и либо ускорить его, либо осознанно поднять лимит ожидания.

Причина 1: бэкенд реально медленный

Чаще всего 504 означает, что скрипт или запрос выполняется слишком долго: тяжёлый SQL-запрос, обращение к внешнему API, которое зависло, неоптимальный код, генерирующий страницу минуту. Nginx по умолчанию ждёт ответа 60 секунд и, не дождавшись, отдаёт 504. Проверьте, что происходит на бэкенде в момент запроса: загрузку CPU, медленные запросы в базе, зависшие процессы.

top -o %CPU

Правильное решение здесь — не бесконечно поднимать таймаут, а устранить причину медлительности: оптимизировать запрос, добавить индекс в базу, кэшировать тяжёлый результат, убрать зависающий вызов внешнего сервиса. Поднятие таймаута лечит симптом, но если страница честно генерируется минуту, пользователю всё равно плохо. Сначала ускорьте бэкенд, и только затем, если долгий ответ действительно нужен (выгрузка, отчёт), осознанно увеличьте лимит именно для этого маршрута.

Причина 2: слишком низкие таймауты прокси

Если ответ по своей природе долгий и это оправдано — генерация большого отчёта, экспорт данных — стандартных 60 секунд может не хватать. Тогда таймауты прокси поднимают явно. В блоке location или server задайте увеличенные значения:

proxy_connect_timeout 75s;
proxy_read_timeout 300s;
proxy_send_timeout 300s;

Для PHP-FPM аналогично работают fastcgi_read_timeout и fastcgi_send_timeout. После правки не забудьте nginx -t && systemctl reload nginx. Важно поднимать таймаут точечно для конкретного тяжёлого маршрута, а не глобально на весь сайт: иначе зависший бэкенд будет держать соединения по пять минут для всех запросов и легко исчерпает ресурсы. Долгие операции лучше выносить в фоновые задачи и очереди, а не заставлять пользователя и Nginx ждать синхронного ответа.

Причина 3: бэкенд упал или перегружен

504 появляется и когда бэкенд просто не работает: PHP-FPM не запущен, приложение упало, воркеры кончились. Проверьте, жив ли сервис, к которому проксирует Nginx:

systemctl status php8.2-fpm

Если сервис лежит — поднимите его и разберитесь, почему упал (смотрите его собственные логи). Частая ситуация под нагрузкой — пул воркеров PHP-FPM исчерпан: все процессы заняты, новые запросы встают в очередь и не получают ответа вовремя. В логах PHP-FPM тогда будет server reached pm.max_children. Решение — увеличить pm.max_children в конфиге пула с учётом доступной памяти, оптимизировать код, чтобы запросы отрабатывали быстрее и освобождали воркеры, или добавить ресурсов серверу. Перегруженный бэкенд — частая причина плавающих 504 на пике посещаемости.

Причина 4: нехватка ресурсов сервера

Если сервер упёрся в лимит памяти или диск, бэкенд начинает тормозить или уходить в своп, и ответы перестают укладываться в таймаут. Проверьте память и нагрузку:

free -m && uptime

Высокий load average, забитая память, активный своп — всё это замедляет бэкенд и порождает 504 под нагрузкой. Здесь помогает либо оптимизация (уменьшить потребление, добавить кэш), либо увеличение ресурсов сервера. Если проект вырос, а VPS остался прежним, регулярные 504 на пиках — прямой сигнал, что пора добавить памяти и ядер. Иногда причина проще — забился диск, база не может писать временные файлы, и запросы виснут; тогда сначала освободите место.

Как отличить разовый сбой от системной проблемы

Единичный 504 при внешнем сбое (завис сторонний API) — это одно, а регулярные — совсем другое. Чтобы понять масштаб, посмотрите, как часто ошибка встречается в логах за последнее время:

grep "504" /var/log/nginx/access.log | wc -l

Если 504 единичны и совпадают с обращениями к внешним сервисам — добавьте таймауты и обработку недоступности этих сервисов на стороне приложения. Если же 504 идут пачками на пике трафика — это системная проблема производительности или ресурсов, и её надо решать по существу: оптимизацией бэкенда, кэшированием, увеличением пула воркеров или мощности сервера. Регулярность и привязка ко времени суток — главная подсказка о природе проблемы.

Профилактика: как не ловить 504 под нагрузкой

Чтобы 504 не возвращался, работайте на опережение. Кэшируйте тяжёлые страницы и результаты запросов, выносите долгие операции (отчёты, рассылки, обработку файлов) в фоновые очереди вместо синхронных ответов, держите базу в форме с нужными индексами. Настройте мониторинг времени ответа бэкенда и загрузки сервера — тогда вы увидите приближение проблемы до того, как посыплются ошибки. Разумные, а не гигантские таймауты в связке с быстрым бэкендом — правильный баланс.

Отдельно заложите запас по ресурсам под пиковую нагрузку: сервер, который на среднем трафике работает на пределе, гарантированно даст 504 в час пик. Если проект растёт, планируйте апгрейд заранее. Регулярный 504 — не каприз Nginx, а честный индикатор, что цепочка «сервер — бэкенд — база» перестала укладываться в отведённое время, и лечить нужно именно её.

Полезно также заранее продумать поведение при недоступности внешних сервисов. Если ваш бэкенд синхронно ходит в чужой API, любой его сбой или замедление отзовётся у вас чередой 504. Задайте на стороне приложения короткие таймауты на такие вызовы и корректную обработку ошибки, чтобы страница отдавала понятный ответ, а не заставляла пользователя и Nginx ждать минуту впустую. Так одна внешняя проблема не превращается в каскад таймаутов по всему сайту, и вы сохраняете контроль над временем ответа.

Частые вопросы