re:re:actable
Урок 063 минуты чтения

Как работают PID 1, сигналы и graceful shutdown

На этой странице
Кратко

Процесс из CMD/ENTRYPOINT становится в контейнере PID 1. docker stop посылает ему SIGTERM и через 10 секунд — SIGKILL. У PID 1 в Linux особые правила: ядро не применяет к нему действия сигналов по умолчанию, поэтому без явного обработчика SIGTERM он не завершается, а ещё PID 1 должен «подбирать» завершившихся потомков (zombie). Отсюда правила: exec-форма CMD ["node", "app.js"], запуск node напрямую, а не через npm, обработчик SIGTERM в коде и --init (tini) при необходимости.

Вопрос

Почему важно, какой процесс является PID 1 в контейнере, и как реализовать graceful shutdown?

Что происходит при остановке

docker stop / деплой новой версии / масштабирование вниз
        │
        ▼
SIGTERM → PID 1 ──(до 10 с, настраивается)──▶ SIGKILL

Если приложение за это время не завершилось, оно умирает посреди запросов: клиенты получают 502, транзакции обрываются, сообщения из очереди теряются.

Три типовые проблемы

1. Shell-форма. CMD node dist/main.js → PID 1 = /bin/sh -c. Оболочка не пересылает SIGTERM потомку, Node.js сигнал не получает.

2. npm как PID 1. CMD ["npm", "start"] → PID 1 = npm, Node.js — дочерний процесс. Пересылка сигналов ненадёжна, лишний процесс в памяти.

3. Нет обработчика. Даже если Node.js — PID 1, без process.on("SIGTERM") действие по умолчанию к нему не применяется, и процесс просто игнорирует сигнал до SIGKILL.

Признак любой из проблем — docker stop всегда занимает ровно 10 секунд.

Правильный запуск

CMD ["node", "dist/main.js"]

Или с лёгким init-процессом, который пересылает сигналы и собирает zombie-процессы:

docker run --init my-api
services:
  api:
    init: true
RUN apk add --no-cache tini
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "dist/main.js"]

init особенно полезен, если приложение запускает дочерние процессы (Puppeteer с Chromium, child_process).

Graceful shutdown в Node.js

const server = app.listen(3000, "0.0.0.0");
 
let shuttingDown = false;
 
async function shutdown(signal: string) {
  if (shuttingDown) return;
  shuttingDown = true;
  console.log(`${signal} received, shutting down`);
 
  // 1. перестать принимать новые соединения, дождаться текущих запросов
  server.close(async () => {
    // 2. закрыть ресурсы
    await db.$disconnect();
    await redis.quit();
    process.exit(0);
  });
 
  // 3. страховка: выйти раньше, чем придёт SIGKILL
  setTimeout(() => process.exit(1), 8_000).unref();
}
 
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));

В NestJS то же самое включает app.enableShutdownHooks() и хуки onModuleDestroy/beforeApplicationShutdown.

Keep-alive соединения могут держать server.close() долго — в Node.js 18.2+ есть server.closeIdleConnections(), а таймаут-страховка не даёт зависнуть.

Readiness при остановке

В оркестраторах балансировщик узнаёт об остановке с задержкой. Поэтому при SIGTERM приложение сначала начинает отвечать «не готов» на readiness-проверку, несколько секунд продолжает обслуживать запросы и только потом закрывает сервер.

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

docker stop -t 30 api
services:
  api:
    stop_grace_period: 30s
    stop_signal: SIGTERM

Nginx, например, корректно завершается по SIGQUIT — поэтому в его образе задан STOPSIGNAL SIGQUIT.

Частые ошибки

  • Shell-форма CMD и ENTRYPOINT.
  • npm start как команда production-контейнера.
  • Отсутствие обработчика SIGTERM.
  • Entrypoint-скрипт без exec "$@".
  • Таймаут завершения в коде больше, чем stop_grace_period.

Что важно помнить

  • PID 1 без обработчика игнорирует SIGTERM — это особенность Linux, а не Docker.
  • Exec-форма плюс прямой запуск node решают большинство проблем.
  • Graceful shutdown: перестать принимать → дождаться текущих → закрыть ресурсы → выйти.

Мини-шпаргалка

  • stop = SIGTERM → 10 с → SIGKILL.
  • CMD ["node", "dist/main.js"], не npm start.
  • init: true / --init / tini.
  • process.on("SIGTERM") + server.close() + таймаут.
  • stop_grace_period — время на завершение.

Документация

Docker: docker container run --init, Docker: Dockerfile STOPSIGNAL, Node.js: Docker best practices — Handling kernel signals.

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

Поиск

Поиск по урокам