Выберите продукт

Безопасные ретраи в Nginx: proxy_next_upstream, try‑next и идемпотентность

Ретраи на уровне Nginx могут спасать SLA, но при неверной настройке превращают частичный сбой backend в лавину дублированных запросов. Разбираем proxy_next_upstream, try‑next, идемпотентность и безопасные границы таймаутов.
Безопасные ретраи в Nginx: proxy_next_upstream, try‑next и идемпотентность

Ретраи в реверс‑прокси — мощный инструмент повышения доступности. Но если включить их бездумно, можно превратить единичный сбой upstream в лавину дублирующих запросов, каскадные таймауты и «залипшие» очереди. В этой статье разберём практику безопасных ретраев в Nginx вокруг proxy_next_upstream, логику «try‑next» (переход к следующему серверу) и роль идемпотентности HTTP‑методов.

Зачем ретраи и почему это опасно

Смысл ретрая прост: если выбранный backend ответил ошибкой или вовсе не ответил, Nginx может «попробовать следующий» сервер в апстриме. Это уменьшает долю 5xx для клиентов и разгружает выпавшие из строя инстансы. Но риск в том, что повторы могут вызвать повторное выполнение бизнес‑операций (например, списание платежа) или, при массовом сбое, создать шторм повторных запросов, усугубляющий деградацию.

Правило №1: ретраить только то, что безопасно повторять. Безопасность = идемпотентность операции с точки зрения приложения, а не только HTTP‑метода.

Идемпотентность: не только про GET

Идемпотентная операция — та, многократное выполнение которой даёт тот же эффект, что и одно. В HTTP к идемпотентным обычно относят GET, HEAD, OPTIONS, TRACE. Формально PUT и DELETE тоже должны быть идемпотентны по семантике RFC, но реальная бизнес‑логика сервисов часто нарушает это ожидание (например, нестабильные побочные эффекты, триггеры, расчётные балансы).

POST по определению не идемпотентен. Повтор запроса потенциально создаёт повторную сущность или двойную транзакцию. Если нужно повторять POST, это уже архитектурная задача приложения: ключи идемпотентности (Idempotency‑Key), дедупликация по X-Request-ID, транзакции и блокировки на стороне сервера.

Как Nginx «переходит к следующему»: try‑next на практике

В контексте Nginx «try‑next» — это общий паттерн: при определённых ошибках прокси не сдаётся, а выбирает следующий сервер из группы upstream. Делают это профильные директивы для конкретных протоколов: proxy_next_upstream для HTTP‑прокси, а также аналоги для fastcgi_*, uwsgi_*, scgi_*, grpc_* в соответствующих модулях. Далее фокусируемся на HTTP‑прокси (proxy_* ).

Чтобы безопасно обкатать конфигурацию и собрать метрики без риска для продакшена, поднимите тестовый стенд на VDS и воспроизводите типовые сбои: тормозные диски, отказ инстанса, «битые» заголовки.

Фрагмент конфига Nginx с proxy_next_upstream и таймаутами

Базовые настройки ретраев в HTTP‑прокси

Ключевые директивы:

  • proxy_next_upstream — перечень событий/кодов, при которых идти к следующему серверу.
  • proxy_next_upstream_tries — максимальное число попыток (включая первую).
  • proxy_next_upstream_timeout — общий лимит времени, отведённый на все попытки.
  • proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout — детализируют таймауты соединения и обмена.
  • proxy_request_buffering — управляет буферизацией тела запроса перед отправкой на backend, критично для безопасных повторов с телом.

Что именно ретраить? В значениях proxy_next_upstream используются «причины»:

  • error — сетевые ошибки и разрывы соединений.
  • timeout — сработали proxy_*_timeout.
  • invalid_header — некорректные заголовки от upstream.
  • http_500, http_502, http_503, http_504 — типичные серверные сбои.
  • опционально http_429 — перегрузка/лимитирование; уместно, если upstream способен быстро отдать ответ при следующей попытке.
  • off — отключить переходы.
  • non_idempotent — разрешить ретраи для неидемпотентных методов (см. ниже).

Контроль числа попыток и суммарного времени

Две страховки от «бесконечного» поиска живого сервера:

  • proxy_next_upstream_tries задаёт верхнюю границу попыток.
  • proxy_next_upstream_timeout завершает цикл ретраев по времени, даже если попытки ещё остались.

Без этих ограничений под нагрузкой легко устроить retry‑storm: каждый клиент будет повторять запросы, дожимая остатки живых инстансов.

Идемпотентность и флаг non_idempotent

По умолчанию Nginx не повторяет явно неидемпотентные методы. Чтобы изменить поведение, есть флаг non_idempotent в списке значений proxy_next_upstream. Включать его следует только если приложение гарантирует безопасную дедупликацию (например, через ключи идемпотентности для POST). В противном случае вы рискуете продублировать операции.

Практичные пресеты: чит‑листы для боевых окружений

Цели: высокий SLA, быстрое переключение на здоровые инстансы, контроль суммарной задержки. Для безопасной обкатки таких пресетов используйте тестовую среду на VDS.

Пресет для чтения (API GET, поиски, страницы)

upstream app {
    zone app 64k;
    server 10.0.0.11:8080 max_fails=3 fail_timeout=10s;
    server 10.0.0.12:8080 max_fails=3 fail_timeout=10s;
    keepalive 64;
}

server {
    listen 80;
    location /api/ {
        proxy_pass http://app;
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        # Идем к следующему при типичных временных сбоях
        proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
        proxy_next_upstream_tries 3;
        proxy_next_upstream_timeout 2s;

        # Таймауты коннекта/обмена
        proxy_connect_timeout 300ms;
        proxy_send_timeout 2s;
        proxy_read_timeout 2s;

        # Логи для анализа ретраев
        access_log /var/log/nginx/access.log main;
    }
}

Комментарии:

  • Низкий proxy_connect_timeout полезен при деградации сети или синхронных рестартах.
  • keepalive уменьшает накладные расходы и сокращает вероятность таймаута коннекта.
  • Ограничения по времени и попыткам держат SLA и латентность под контролем.

Пресет для запросов с телом (загрузки, PUT)

Если запрос несёт значительное тело, важна буферизация на стороне Nginx: так прокси сможет повторно отправить тот же body, не требуя от клиента перезаливки.

location /upload/ {
    proxy_pass http://app;

    # Буферизуем тело запроса перед отправкой upstream
    proxy_request_buffering on;
    client_body_buffer_size 512k;
    client_max_body_size 200m;

    # Ретраим только безопасные причины
    proxy_next_upstream error timeout invalid_header http_502 http_503 http_504;
    proxy_next_upstream_tries 2;
    proxy_next_upstream_timeout 5s;
}

Если proxy_request_buffering off, а тело уже частично ушло на backend, переключение на следующий сервер может оказаться невозможным или рискованным, особенно для неидемпотентных методов.

Гейт по методу: блокируем ретраи для POST

Часто достаточно разрешить ретраи только для чтения и явно запретить для создания/мутаций:

map $request_method $safe_retry {
    default 0;
    GET     1;
    HEAD    1;
    OPTIONS 1;
}

server {
    listen 80;
    location /api/ {
        proxy_pass http://app;
        proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
        proxy_next_upstream_tries 2;
        proxy_next_upstream_timeout 1s;

        # Включаем переход к следующему только для безопасных методов
        if ($safe_retry = 0) {
            proxy_next_upstream off;
        }
    }
}

Так мы не задействуем ретраи для POST, оставляя повтор на совести клиента или приложения с ключом идемпотентности.

FastFox VDS
Облачный VDS-сервер
Виртуальные серверы с быстрым запуском и гибкой конфигурацией от 390₽ / мес
Доступные локации
Россия Нидерланды Финляндия

Какие статусы и ошибки ретраить, а какие — нет

Рекомендации, проверенные в проде:

  • Ретраить: error, timeout, invalid_header, http_502, http_503, http_504. Эти случаи чаще всего означают «попробуй другой инстанс».
  • Опционально ретраить: http_500 — если причина может быть транзитной (OOM‑kill, холодный старт). Если 500 часто означает логическую ошибку приложения, лучше не повторять.
  • Иногда ретраить: http_429 — зависит от политики rate‑limit upstream. Если есть поддержка Retry-After на backend, но Nginx не умеет «подождать» между попытками, ограничивайте число попыток и суммарный таймаут, чтобы не усилить перегрузку.
  • Не ретраить: http_401, http_403, http_404, http_422 и прочие ожидаемые клиентские ошибки. Повторы только увеличат нагрузку.

Таймауты: где тонко — там Nginx должен рвать

Три таймаута часто путают:

  • proxy_connect_timeout — время на установление TCP‑соединения с backend.
  • proxy_send_timeout — время на отправку запроса upstream (включая тело).
  • proxy_read_timeout — ожидание ответа после отправки запроса.

Слишком большие таймауты приводят к долгим подвисаниям и накоплению очередей в Nginx. Слишком маленькие — к «ложным» ретраям и лишней турбулентности. Правильные значения подбирают по SLO сервиса и реальным перцентилям задержек. Практично начинать с сотен миллисекунд для connect и единиц секунд для send/read на синхронных API, затем уточнять по метрикам.

Очереди, backpressure и защита от retry‑storm

Даже идеальные ретраи не спасут сервис, если фронт‑прокси допускает бесконечный рост очереди. Несколько приёмов:

  • Ограничивайте суммарное время ретраев через proxy_next_upstream_timeout и число попыток через proxy_next_upstream_tries.
  • Настройте пассивные health‑checks через max_fails и fail_timeout у серверов в upstream, чтобы быстрeе исключать «битые» инстансы.
  • Используйте slow_start у upstream при возвращении инстанса в строй, чтобы не «запихнуть» в него весь трафик мгновенно.
  • Ограничивайте одновременные соединения к upstream (через балансировку и архитектуру) и клиентские лимиты на фронте, чтобы не допустить распухание очереди.

Логирование и наблюдаемость ретраев

Nginx уже даёт всё необходимое для пост‑фактум анализа:

  • $upstream_status — список кодов ответов по попыткам (через запятую). По длине списка можно понять, были ли ретраи.
  • $upstream_addr — какие инстансы обслуживали попытки.
  • $upstream_connect_time, $upstream_response_time — тайминги по попыткам.
  • $request_id или собственный X-Request-ID — корреляция на стороне приложения и логов.

Пример расширенного формата лога, в котором видно, что происходило на ретраях:

log_format main '$remote_addr - $request [$time_local] '
                 '"$request" $status $body_bytes_sent '
                 'rt=$request_time uct=$upstream_connect_time '
                 'urt=$upstream_response_time us="$upstream_status" '
                 'ua="$upstream_addr" reqid="$request_id"';

По этим данным легко построить алерты: аномальный рост числа попыток, увеличившиеся connect_time, всплески http_502/504, распределение кодов после ретраев.

Логи Nginx с upstream_status и таймингами попыток

Когда ретраи противопоказаны

Запрещайте ретраи для:

  • финансовых операций без идемпотентных ключей;
  • заявок, создающих внешние эффекты (отправка писем, пушей, бронирования);
  • стриминга/длинных SSE и WebSocket (переподключение — задача клиента, а не proxy);
  • больших небуферизованных загрузок (proxy_request_buffering off), если клиент не поддерживает возобновление;
  • любой операции, где дубль опаснее единичного сбоя.

Специальные случаи: 429 и Retry‑After

Ретраить 429 имеет смысл, если лимит краткосрочный и следующая попытка может пройти. Учитывайте, что Nginx не умеет «подождать N секунд» между попытками на одном запросе. Поэтому:

  • держите proxy_next_upstream_tries маленьким (2–3);
  • ограничивайте proxy_next_upstream_timeout (сотни мс — единицы секунд);
  • по возможности используйте стратегию exponential backoff на стороне клиента;
  • на backend возвращайте валидный Retry-After для координации.

Альтернативы и дополнения к ретраям

Ретраи — не панацея. Ещё три направления повышения устойчивости:

  • Умная балансировка и экспоненциальный backoff на клиенте (SDK, фронтенд, мобильные приложения). Для ускорения первого байта полезно ознакомиться с обзором 103 Early Hints — см. материал «HTTP 103 Early Hints в Nginx и Apache» HTTP 103 Early Hints в Nginx и Apache.
  • Кэширование ответов (proxy‑cache, microcache) для снижения нагрузки при отказах части инстансов. В тему пригодится разбор кэша и диапазонных запросов — статья «HTTP Range, кэш и большие файлы» HTTP Range, кэш и большие файлы.
  • Разделение пишущего и читающего трафика на уровне маршрутизации, чтобы защитить критичные операции от повторов.

Чек‑лист безопасных ретраев

  • Определите, какие методы и эндпоинты действительно идемпотентны.
  • Настройте proxy_next_upstream только на временные ошибки и сетевые сбои.
  • Ограничьте попытки через proxy_next_upstream_tries и суммарное время через proxy_next_upstream_timeout.
  • Отдельно настройте таймауты proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout под ваш SLO.
  • Для запросов с телом включите proxy_request_buffering on, если нужны повторы без участия клиента.
  • Для неидемпотентных операций внедрите дедупликацию на стороне приложения (Idempotency‑Key, X-Request-ID).
  • Включите расширенное логирование ретраев и метрики.
  • Настройте пассивные health‑checks (max_fails, fail_timeout) и slow_start для мягкого возврата инстансов в пул.

Распространённые ошибки и как их избегать

  • «Ретраим всё подряд»: включили non_idempotent и добавили http_500 — получили дубли операций. Лечится методом‑гейтом и ключами идемпотентности.
  • «Бесконечные» попытки: не ограничили число и время. Лечится proxy_next_upstream_tries + proxy_next_upstream_timeout.
  • Неправильные таймауты: слишком большие — залипание очередей, слишком маленькие — фальш‑ретраи. Нужны метрики и перцентильная настройка.
  • Ретраи больших тел без буферизации: клиент уходит в таймауты. Включайте proxy_request_buffering там, где допустимо.
  • Игнорирование 429: без клиентского backoff вы усилите перегрузку. Дозируйте попытки и учите клиентов отступать.

Вывод

Безопасные ретраи в Nginx строятся вокруг простых принципов: ретраим только временные ошибки, только для идемпотентных операций, жёстко ограничиваем попытки и суммарное время, буферизуем тело, если нужны повторы без участия клиента, и наблюдаем за поведением через логи и метрики. При таком подходе «try‑next» помогает держать SLA и латентность под контролем, не превращаясь в катализатор инцидентов.

Поделиться статьей

Вам будет интересно

Как безопасно выполнить bootstrap MariaDB Galera после полного останова

Как безопасно выполнить bootstrap MariaDB Galera после полного останова

После одновременной остановки всех узлов Galera обычного запуска MariaDB недостаточно. Сначала найдите сервер с последней транзакц ...
CoreDNS в Kubernetes: исправляем CrashLoopBackOff, SERVFAIL и DNS-петлю

CoreDNS в Kubernetes: исправляем CrashLoopBackOff, SERVFAIL и DNS-петлю

Разберём, почему CoreDNS перезапускается или отвечает SERVFAIL, как обнаружить замкнутую пересылку DNS-запросов, проверить доступн ...
Apache Kafka KRaft на VDS: отдельные controller и broker

Apache Kafka KRaft на VDS: отдельные controller и broker

Соберём новый Kafka-кластер без ZooKeeper на шести Linux VDS: три узла controller образуют отказоустойчивый metadata quorum, а три ...