Nginx Linux

Nginx: upstream timed out только для API

  • Обновлено
  • Чтение ≈ 4 минуты
  • Нужны права администратора

Краткий ответ

Сообщение upstream timed out означает, что Nginx не дождался определённого этапа ответа от проксируемого приложения. Если проблема только на /api/, сначала сравните правила маршрута, тип запроса и время ответа API.

В этой статье
  1. Что означает и когда возникает ошибка
  2. Причины и как их различить
  3. Пошаговая диагностика и исправление
  4. Проверка результата
  5. Если проблема осталась

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

Текст журнала после while помогает отличить тайм-аут подключения, ожидания заголовка или чтения тела. Для долгой операции предпочтительнее исправить приложение или использовать очередь, а не просто выставить много минут ожидания.

#Причины и как их различить

Возможная причинаКак узнатьЧто делать
API выполняет медленный запросОдна операция ждёт базу, внешнюю службу или блокировку.Тайм-аут только у конкретного метода/пути, время до сбоя повторяется.Замерить длительность на приложении и оптимизировать.
У API отдельные директивы NginxУ location /api/ другой proxy_read_timeout или upstream.Обычные страницы открываются, а GET/POST к API зависают.Сравнить выбранный location и конфигурацию proxy_pass.
Доступен прокси, но недоступен backendУ приложения перегружен пул, нет свободных работников или не открывается порт.Логи API сообщают об отказах, очередь растёт; Nginx пишет timed out при connect/read.Восстановить работоспособность приложения, не открывая внутренний порт в интернет.

#Пошаговая диагностика и исправление

  1. Повторите только безопасный API-запросОпределите конкретный endpoint и метод (GET, POST и т. д.). Для GET без побочных действий с вашего компьютера выполните curl -sS -o /dev/null -w "HTTP:%{http_code} total:%{time_total} first_byte:%{time_starttransfer}\n" https://example.com/api/status, заменив URL. Если метод изменяет данные, не повторяйте его вслепую: используйте тестовую среду и согласованный тестовый запрос. Запишите время и статус.
  2. Прочитайте точную стадию тайм-аутаПодключитесь по SSH и посмотрите журнал Nginx по адресу из error_log фактической конфигурации. Найдите upstream timed out за время запроса и запишите, что следует после while: connecting to upstream, reading response header или reading upstream. Не публикуйте токены и параметры частных API. Если сообщения нет, проверьте журнал CDN либо внешнего балансировщика.
  3. Проверьте выбор location /api/ и проксиКомандой sudo nginx -T 2>&1 | grep -nE "location|proxy_pass|proxy_(connect|read|send)_timeout|upstream" найдите правила домена. Сопоставьте выбранный location и реально проксируемый адрес с рабочим URL; обратите внимание на косую черту в конце proxy_pass, способную изменить передаваемый путь. Не редактируйте конфигурацию на основании одного совпадения grep — прочитайте соседние строки полного файла.
  4. Проверьте приложение локально безопасным запросомЕсли API слушает локальный TCP-порт, выполните на сервере тестовый GET к проверенному безопасному пути непосредственно на 127.0.0.1 и нужный порт, используя curl. Порт надо взять из своей настройки proxy_pass, не подставлять случайный. Если приложение использует Unix-сокет или авторизацию, используйте штатный health-check приложения и его журнал; не открывайте внутренний порт публично для диагностики.
  5. Найдите истинную задержкуСравните время первого байта у Nginx и время выполнения в журнале приложения. Если ответ упирается в SQL, блокировки, медленный внешний API или очередь задач, оптимизируйте этот участок. Проверьте рабочие процессы, память и ошибки приложения. Увеличение proxy_read_timeout не исправит бесконечно зависший запрос: это интервал без передачи данных между чтениями, а не универсальный предел всей операции.
  6. Правьте тайм-аут только после подтвержденияЕсли API действительно должен законно отвечать дольше и все промежуточные уровни это поддерживают, сохраните копию файла, задайте для конкретного location обоснованное значение proxy_read_timeout 90s; (90s лишь пример) и выполните sudo nginx -t. Применяйте sudo systemctl reload nginx только после успешного теста. Убедитесь, что внешний балансировщик и клиент не обрывают запрос раньше.
  7. Проверьте отказоустойчивость и откатПовторите исходный безопасный запрос, сравните HTTP-статус, время ответа и отсутствие новых timed out в журнале. Если после настройки выросли очереди и 502/504, верните сохранённый файл, проверьте nginx -t, примените конфигурацию и исследуйте приложение. Для долгих отчётов и импорта используйте фоновые задачи с проверкой состояния.
  8. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
    Выберите подходящий вариант — это не команды для последовательного выполнения
    Вариант 1На компьютере пользователя без sudo; только для безопасного GET, замените URL и проверьте отсутствие побочн…
    Linux · Терминал (Bash)Команда
    На компьютере пользователя без sudo; только для безопасного GET, замените URL и проверьте отсутствие побочных действий.
    curl -sS -o /dev/null -w "HTTP:%{http_code} total:%{time_total} first_byte:%{time_starttransfer}\n" https://example.com/api/status
    Вариант 2Сервер по SSH; проверка синтаксиса после резервного копирования.
    Linux · Терминал (Bash)КомандаНужен sudo
    Сервер по SSH; проверка синтаксиса после резервного копирования.
    sudo nginx -t
    Вариант 3Неполный пример точечной настройки, не готовый блок для вставки: 90 секунд подбираются по измерениям.
    Nginx
    Неполный пример точечной настройки, не готовый блок для вставки: 90 секунд подбираются по измерениям.
    location /api/ {
    # Сохраните действующий proxy_pass и заголовки без изменения.
    proxy_read_timeout 90s;
}

#Проверка результата

Успех: целевой API возвращает ожидаемый код и содержимое, время ответа стабильно, новых сообщений timed out для этого пути нет.

#Если проблема осталась

Сохраните дату, точный URL без паролей и токенов, код ответа, обезличенные строки error.log и access.log за это время и перечень уже сделанных изменений. Сравните работу при обращении через публичный адрес и через внутренний балансировщик, если он есть. Если причину пока не удалось подтвердить, восстановите исходную конфигурацию из копии и передайте эти сведения администратору или разработчику приложения; не меняйте несколько параметров одновременно.

Так эту ошибку тоже называют

502 502 Bad Gateway в Nginx: причины и быстрый способ найти виновника Ответ `502 Bad Gateway` означает, что Nginx, выступая шлюзом, не смог получить корректный ответ от backend-сервера — чаще всего PHP-FPM или приложения за `proxy_pass`. С… Сайты, серверы и хостинг Nginx NginxLinux Nginx: 502 Bad Gateway с PHP-FPM — причины и решение Проверьте, запущен ли php-fpm, путь к сокету и права. Сайты, серверы и хостинг Nginx Linux 504 Nginx 504 Gateway Time-out — причины и как исправить Ошибка `504 Gateway Time-out` значит, что Nginx отправил запрос приложению (PHP-FPM, Node.js, другому серверу), но не дождался ответа за отведённое время. Чаще всего при… Сайты, серверы и хостинг Nginx NginxLinuxPHP-FPM Nginx: ERR_TOO_MANY_REDIRECTS — цикл редиректов http/https и www — причины и решение Найдите петлю редиректов в конфиге и CMS, проверьте Cloudflare и proxy. Сайты, серверы и хостинг Nginx Linux 504 Nginx: 504 Gateway Time-out — upstream не отвечает вовремя — причины и решение Nginx выдаёт 504 Gateway Time-out, когда backend (PHP-FPM, Node.js, прокси) не успевает ответить за отведённое время. Увеличьте proxy_read_timeout или fastcgi_read_timeo… Сайты, серверы и хостинг Nginx Linux

Источники и обновления

Последнее обновление статьи: 2 ноября 2026. Версии программ и интерфейсы меняются — если шаги не совпадают с вашей версией, сверяйтесь с документацией производителя.