Как работают 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-apiservices:
api:
init: trueRUN 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 apiservices:
api:
stop_grace_period: 30s
stop_signal: SIGTERMNginx, например, корректно завершается по 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.