Контейнеризация Node: PID 1, сигналы и тонкие образы

PID 1 особенный, а Node под него не рассчитан

Внутри Linux-контейнера первый запущенный процесс — это PID 1, и ядро относится к PID 1 не так, как к любому другому процессу. Два правила бьют именно по Node. Первое: у PID 1 нет обработчиков сигналов по умолчанию — для обычного процесса ядро ставит действие по умолчанию для SIGTERM (завершиться), но для PID 1 действия по умолчанию нет, так что SIGTERM без явного обработчика просто игнорируется. Второе: PID 1 обязан реапить зомби: когда дочерний процесс завершается, родитель должен сделать wait(), а осиротевшие потомки переусыновляются к PID 1. Если PID 1 не реапит, мёртвые потомки копятся в таблице процессов как зомби.

Node ставит свой путь слушателя SIGTERM, только если ты сам его добавишь, — но смертельный вариант это запуск Node косвенно. CMD npm start делает PID 1 именно npm; npm порождает node дочерним и не пробрасывает ему сигналы. Так что SIGTERM оркестратора попадает в npm (который игнорирует его как PID 1) и никогда не доходит до приложения. Контейнер будто зависает на остановке.

# ❌ npm — это PID 1; SIGTERM умирает в npm, node его не слышит
CMD npm start

# ❌ shell-форма: /bin/sh -c "node server.js" → PID 1 это sh, проброса тоже нет
CMD node server.js

# ✅ exec-форма: PID 1 это node, твой in-app обработчик SIGTERM сработает
CMD ["node", "server.js"]

Shell-форма CMD node server.js — та же ловушка в другой шляпе: Docker оборачивает её как /bin/sh -c "node server.js", так что PID 1 становится sh, а node — его дочерним; сигналы застревают в шелле. Всегда используй exec-форму (JSON-массив) для сервера, чтобы node был PID 1 напрямую.

Обрабатывай SIGTERM или ставь init впереди

Есть два взаимодополняющих фикса, и production-Node обычно хочет оба.

Первый — запускать node напрямую (exec-форма) и обрабатывать SIGTERM в приложении ради graceful shutdown: перестать принимать новые соединения, дотянуть запросы в полёте, закрыть пул БД, затем выйти. Именно это превращает жёсткий kill в чистый дренаж.

const server = app.listen(3000);

process.on("SIGTERM", () => {
  // прекращаем брать новую работу, дотягиваем открытое, затем выходим чисто
  server.close(() => {
    pool.end().then(() => process.exit(0));
  });
});

Второй — запускать init как PID 1, чтобы кто-то реапил зомби и пробрасывал сигналы, даже если твой код забудет. У Docker такой есть: docker run --init подсовывает tini как PID 1, который пробрасывает SIGTERM дочернему node и реапит сирот. Можно и запечь tini/dumb-init в образ как ENTRYPOINT. Init важнее всего, когда твой процесс порождает потомков (сборочный инструмент, child_process, скрипт-обёртка) — без него эти сироты становятся зомби.

Multi-stage сборка и тонкая non-root база

Одностадийный образ запекает твой компилятор, dev-зависимости и весь тулчейн в то, что ты отгружаешь. Multi-stage сборка разделяет это: стадия builder запускает npm ci и сборку, а тонкая runtime-стадия копирует только нужные ей артефакты.

# ---- builder ----
FROM node:22 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci                      # полные зависимости для сборки
COPY . .
RUN npm run build               # → /app/dist

# ---- runtime ----
FROM node:22-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev           # только прод-зависимости
COPY --from=builder /app/dist ./dist
USER node                       # официальный образ несёт non-root пользователя 'node'
CMD ["node", "dist/server.js"]

Две детали окупают себя. Копируй package*.json и запускай npm ci до копирования исходников. Docker кэширует каждый слой по его входам; если входы слоя зависимостей (lock-файл) не меняются, весь слой npm ci переиспользуется из кэша, и медленный install пропускается — только изменение исходников инвалидирует дешёвый COPY . . под ним. (Кэширование слоёв детально разбирается в треке про деплой; здесь Node-специфичный пойнт — lock-файл раньше исходников.) И выбирай тонкую базу: полный образ node — примерно 1 ГБ, тогда как node:slim это несколько сотен МБ, а distroless runtime для Node — это десятки МБ: меньший образ быстрее тянется и открывает куда меньшую CVE-поверхность, потому что в нём нет шелла или пакетного менеджера для атаки.

Харденинг: non-root, healthcheck и .dockerignore

Три дешёвых хода отделяют игрушечный образ от production. Беги от non-root: официальный образ node уже несёт непривилегированного пользователя node, так что одна строка USER node означает, что баг с исполнением кода не сможет тривиально завладеть контейнером. Добавь healthcheck, чтобы оркестратор знал, когда процесс реально обслуживает: Docker HEALTHCHECK, дёргающий роут /health, или в Kubernetes livenessProbe/readinessProbe, бьющие в /health и /ready; без него зависший процесс остаётся в ротации балансировщика. Добавь .dockerignore со списком node_modules, .git и .env: он держит build-контекст маленьким (быстрее сборки) и, что критично, не даёт закоммиченному .env попасть в слой образа, где секрет живёт вечно и достаётся любым, кто запуллит образ.

# .dockerignore
node_modules
.git
.env
*.log

В Kubernetes числа упираются в PID 1: при удалении пода kubelet шлёт SIGTERM, ждёт terminationGracePeriodSeconds (по умолчанию 30с) и только потом шлёт SIGKILL. Если node не получает SIGTERM (npm/shell как PID 1) или не имеет обработчика, каждый деплой сжигает все 30 секунд и затем жёстко убивает работу в полёте — ровно медленная и теряющая запросы выкатка из хука.