Что такое…

Что такое graceful shutdown — почему при каждой выкатке кто-то теряет свой запрос

Иллюстрация: табличка «закрыто», а последний гость ещё доедает

Ты выкатываешь обновление. Красиво, зелёная галочка, ноль ошибок в логах.

А в этот момент у трёх человек оборвался запрос на середине. Один из них как раз оплачивал.

Ты этого не увидел — сервер уже умер и не успел ничего записать. Разберёмся, как приложение должно умирать правильно.

Что вообще происходит при выкатке

Новая версия не появляется поверх старой. Старую сначала выключают.

Выключение выглядит так: системе даётся сигнал SIGTERM — это вежливое «заканчивай». Дальше ждут какое-то время. Не закончил — прилетает SIGKILL, а это уже не просьба, а выдёргивание вилки из розетки.

В Kubernetes окно ожидания по умолчанию — 30 секунд (terminationGracePeriodSeconds). У docker stop по умолчанию 10. Смысл один: у тебя есть эти секунды, чтобы доделать начатое.

Graceful shutdown («мягкое выключение») — это и есть умение приложения ими воспользоваться.

Что должно произойти за эти секунды

Порядок важнее скорости. Правильная последовательность такая:

  1. Перестать принимать новые запросы. Закрыть приём соединений, но не рубить открытые.
  2. Дождаться, пока доработают текущие. Человек, который в этот момент отправлял форму, должен получить ответ.
  3. Закрыть, что открыто. Соединения с базой, файлы, очереди фоновых задач.
  4. Выйти самому, не дожидаясь SIGKILL.

В коде это одна подписка на сигнал. В Node.js — буквально process.on('SIGTERM', ...), внутри server.close() и закрытие базы. Без неё процесс просто умирает мгновенно, обрывая всё на полуслове.

Ловушка: сигнал вообще не дошёл

Вот тут самое неожиданное.

Ты написал обработчик, проверил локально — работает. В контейнере не работает вообще, будто кода нет.

Причина в том, как записана команда запуска в Dockerfile. Есть две формы:

  • CMD npm start — так называемая shell-форма;
  • CMD ["npm", "start"] — exec-форма.

В первой Docker запускает не твою программу, а /bin/sh -c — и уже оболочка запускает программу как дочерний процесс. Документация Docker пишет об этом дословно: оболочка «не передаёт сигналы», приложение не является PID 1 «и не получит Unix-сигналы». И дальше прямым текстом: твоя программа не получит SIGTERM от docker stop.

То есть обработчик написан, но его никто не зовёт. Контейнер молча висит все 10 секунд и умирает от SIGKILL.

Лечение — квадратные скобки. Пиши exec-форму, и сигнал придёт туда, куда надо.

Порядок с балансировщиком: сначала уйди из строя

Второй подвох — тонкий и живучий.

Допустим, ты всё сделал правильно и доделываешь текущие запросы. Но балансировщик об этом не знает и продолжает слать тебе новых людей — а ты их уже не принимаешь. Они получают ошибку.

Поэтому в Kubernetes машину убирают из списка живых примерно тогда же, когда шлют SIGTERM, — но эта новость расходится по системе не мгновенно.

Практический вывод простой: сначала скажи «я больше не готов», подожди пару секунд, и только потом начинай закрываться. Эти две секунды выглядят как ничего не делание, а на деле именно они убирают ошибки при каждой выкатке.

Где ты это встретишь

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

Пока у тебя один пет-проект и три пользователя, оборванный запрос никто не заметит. Как только появляются оплаты, загрузки файлов и фоновые задачи — мягкое выключение перестаёт быть теорией.

Как проверить, что оно работает

Проверяется за две минуты, и это стоит сделать до того, как выкатишь платежи.

  1. Запусти приложение локально и узнай номер его процесса — ps или вывод самой программы.
  2. Сделай запрос, который заведомо идёт долго. Подойдёт любая ручка с искусственной задержкой в 5 секунд.
  3. Пока запрос висит, отправь процессу тот же самый сигнал: kill -TERM и номер процесса. Именно -TERM, не -9 — девятка это SIGKILL, её никто перехватить не может.
  4. Смотри на две вещи: дождался ли висевший запрос ответа и появилась ли в консоли твоя строка про закрытие.

Дождался и появилась — всё в порядке. Оборвался мгновенно — обработчика нет либо сигнал до него не доходит.

Тот же трюк с контейнером: docker stop и секундомер. Контейнер, который честно умирает за секунду, и контейнер, который стабильно висит ровно 10 секунд, — это два разных диагноза. Второй означает SIGKILL по таймауту.

Мне хватит просто увеличить время ожидания?

Нет. Если приложение не слушает сигнал, оно не станет закрываться аккуратнее оттого, что ему дали не 30 секунд, а 120. Оно просто провисит дольше и всё равно умрёт жёстко. Время ожидания настраивают уже после того, как обработчик написан.

Что если запрос идёт дольше отпущенного времени?

Значит, его всё равно оборвут. Долгие операции — отчёт на пять минут, обработка видео — не должны жить внутри запроса. Их выносят в фоновую задачу, чтобы перезапуск сервера их не убивал.

А если у меня хостинг без Docker?

Механика та же. Любая платформа перед перезапуском шлёт процессу сигнал завершения и ждёт. Меняются только имена настроек и длина окна — обработчик нужен одинаково.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →