Nginx: 504 Gateway Time-out — upstream не отвечает вовремя

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

Nginx передал запрос на upstream (PHP-FPM, Gunicorn, Node.js, другой сервер) и не дождался ответа за время proxy_read_timeout (по умолчанию 60 секунд) или fastcgi_read_timeout. Это не ошибка nginx — он лишь сообщает, что backend не отвечает вовремя. Поэтому решение лежит в двух плоскостях: настройка таймаутов и устранение причины медленной работы.

#Причины и решения

#Пошаговое решение

1. Посмотрите логиНа сервере Nginx через SSH выполните sudo grep "upstream timed out" /var/log/nginx/error.log | tail -n 20 и запишите конкретный URL, upstream и фазу connecting/reading. Отметьте, после какого времени Nginx выдаёт 504 и возникает ли это на одном запросе или массово.
2. Проверьте статус backendСопоставьте upstream-адрес с fastcgi_pass/proxy_pass из nginx -T, затем посмотрите статус соответствующего PHP-FPM или приложения. Если upstream недоступен, исправляйте его службу/порт, а не таймаут. На системах с несколькими пулами не перезапускайте все PHP-FPM ради одного сайта.
3. Найдите медленный запросЕсли backend работает, изучите slowlog PHP-FPM, медленные запросы MySQL и внешние API. Найдите конкретную операцию, удерживающую воркер, и проверьте её на тестовом окружении. Длительный SQL-запрос не станет быстрее после увеличения fastcgi_read_timeout.
4. Увеличьте таймаутыЕсли запрос по своей природе выполняется долго и это допустимо, подберите ограниченный fastcgi_read_timeout или proxy_read_timeout именно в нужном location, предварительно создав копию конфигурации. Слишком большой таймаут увеличит занятость соединений и может усугубить перегрузку.
5. Проверьте лимиты воркеровПосмотрите в журнале PHP-FPM сообщения server reached pm.max_children, измерьте память пула, количество активных процессов и очередь. Увеличивайте число воркеров только после расчёта свободной RAM; при OOM и swap сначала оптимизируйте запросы.
6. Проверьте конфигурацию и перезагрузитеПосле правок Nginx выполните sudo nginx -t и затем sudo systemctl reload nginx; при изменении PHP-FPM проверьте и примените его конфигурацию отдельно. Повторите исходный URL, убедитесь в ожидаемом ответе и отсутствии свежего 504 в журнале.

#Настройка таймаутов

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_read_timeout 300s;
    include fastcgi_params;
}

location /api/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 10s;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
}

Если за nginx стоит Cloudflare или другой CDN, помните, что у него свой лимит ответа (у бесплатного Cloudflare — 100 секунд, после чего появляется 524). Долгие операции лучше выносить в очередь задач и показывать пользователю прогресс. Подробнее — в документации nginx.