Навигация

Docker и деплой Node.js

На машине разработчика приложение запускается одной командой и живёт в знакомом окружении: файлы рядом, память хоста, Ctrl+C в терминале. В проде у процесса другие правила — cgroup-лимит вместо свободной памяти, SIGTERM вместо нажатия клавиши, read-only файловая система и прокси перед портом. Половина инцидентов при первом деплое связана не с кодом, а с этими различиями. Разберём, как собрать образ, корректно передать процессу управление и выкатить новую версию без оборванных запросов.

Содержание

  1. Что меняется в контейнере
  2. Dockerfile: multi-stage сборка
  3. Зависимости: lockfile и слои
  4. Non-root и файловая система
  5. PID 1 и сигналы
  6. Лимиты памяти и heap
  7. PM2, systemd и оркестратор
  8. Reverse proxy и TLS
  9. Health checks
  10. Zero-downtime деплой
  11. Секреты и конфигурация
  12. Практика: TaskFlow
  13. Частые ошибки
  14. Ключевые тезисы для интервью
  15. Заключение
  16. Полезные ссылки

Что меняется в контейнере

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

ДомаВ контейнереЧто ломается
Память хостаcgroup-лимит, OOM-killerheap растёт выше лимита, процесс убивают без логов
Ctrl+C → SIGINTSIGTERM в PID 1, затем SIGKILLсигнал не доходит до Node или игнорируется
Файлы проекта рядомread-only rootfs, нет node_modulesзапись в ./tmp, чтение dev-конфига
localhost:30000.0.0.0, прокси и TLS снаружиприложение слушает 127.0.0.1 и недоступно
Один процесснесколько реплик, rolling updateсостояние в памяти, миграции на каждом старте
npm run dev с watchnode dist/server.jsdev-зависимости в рантайме, NODE_ENV не задан

Дальше — три вещи, за которые отвечает приложение: образ (что и с чем собрано), процесс (как получает сигналы и сколько памяти ему можно) и окружение (прокси, проверки, порядок выката). Деплой-платформа и стратегии релизов в целом разобраны в разделе «Сборка и деплой», здесь — только серверная часть на Node.


Dockerfile: multi-stage сборка

Сборка TypeScript-проекта требует компилятора, тестов и линтеров, а рантайму нужен только node и production-зависимости. Один образ на оба этапа означает, что в прод уедет весь инструментарий сборки: сотни мегабайт, лишние CVE и нативные модули, собранные под другим окружением.

Multi-stage решает это разделением на стадии: инструменты остаются в промежуточных слоях, в финальный образ копируется только результат.

# syntax=docker/dockerfile:1.7

# 1. Зависимости для сборки — вместе с devDependencies
FROM node:22-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci

# 2. Сборка: TypeScript, бандлер, генерация клиента
FROM deps AS build
COPY . .
RUN npm run build

# 3. Только production-зависимости, отдельно от dev-стадии
FROM node:22-bookworm-slim AS prod-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev

# 4. Рантайм
FROM node:22-bookworm-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
COPY --chown=node:node package.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

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

База зафиксирована тегом, а в идеале дайджестом. node:22-bookworm-slim даёт LTS-ветку без компиляторов и документации. Плавающий node:latest означает, что два билда одного коммита могут дать разные образы, а откат «на вчерашний» перестаёт быть воспроизводимым.

COPY package*.json до копирования исходников. Docker кеширует слои по содержимому: пока не изменился lockfile, npm ci берётся из кеша, и правка одного файла в src/ не переустанавливает зависимости.

--mount=type=cache для npm. Кеш пакетов живёт между сборками, но не попадает в образ. Без него каждая сборка заново скачивает реестр, а с COPY ~/.npm кеш разработчика утекает в слои.

CMD в exec-форме. CMD ["node", "dist/server.js"] запускает Node напрямую, без sh -c и без npm. Об этом подробнее в разделе про PID 1: именно форма CMD определяет, дойдёт ли SIGTERM.

EXPOSE — документация, а не публикация. Порт открывает -p/ports при запуске. Приложение при этом должно слушать 0.0.0.0, иначе снаружи контейнера порт недоступен — это частая причина «локально работает, в контейнере нет».

Рядом с Dockerfile обязателен .dockerignore. Без него в контекст сборки попадут node_modules, .git, coverage, dist и .env, а COPY . . перезапишет установленные зависимости локальной копией с другой платформой:

node_modules
dist
coverage
.git
.env*
*.log
test
docs

Два практических нюанса выбора базы:

БазаРазмерКогда брать
bookworm-slim (glibc)~75 МБпо умолчанию: нативные модули работают из коробки
alpine (musl)~50 МБнужен минимальный образ и нет проблемных нативных зависимостей
distroless~60 МБнужен минимум пакетов и shell не требуется для отладки

Alpine экономит два десятка мегабайт, но sharp, bcrypt и подобные модули требуют пересборки под musl, а иногда и установки python3/make. Для сервиса, который деплоится часто, предсказуемость важнее размера.


Зависимости: lockfile и слои

npm ci — не «то же самое, но короче». Он ставит зависимости строго из package-lock.json, не меняя его, удаляет node_modules перед установкой и падает, если lockfile расходится с package.json. Именно это нужно в CI: сборка либо воспроизводит проверенный набор версий, либо останавливается.

КомандаЧто делаетГде использовать
npm installобновляет lockfile под semver-диапазонылокально, при добавлении зависимости
npm ciставит ровно из lockfile, падает при расхожденииCI и Docker
npm ci --omit=devто же без devDependenciesрантайм-стадия
npm prune --omit=devудаляет dev-пакеты из готового дереваальтернатива, если жалко времени на вторую установку

Почему node_modules не копируют из dev-стадии, хотя это экономит минуту сборки:

  • в дереве остаются typescript, vitest, eslint, @types/* — десятки мегабайт и лишние уязвимости в сканере;
  • нативные модули собраны в контексте, где есть компилятор, а в рантайм-образе его нет — при несовпадении glibc/musl или архитектуры они падают с invalid ELF header;
  • npm prune удаляет пакеты, но оставляет следы: пустые директории, кеш, .bin-ссылки. Чистая установка из lockfile даёт ровно то, что объявлено в dependencies.

Второй npm ci --omit=dev в отдельной стадии не так дорог, как кажется: с --mount=type=cache пакеты берутся из локального кеша, а не из сети. Если время сборки критично, стадию prod-deps можно запустить параллельно с build — они не зависят друг от друга.

Отдельная ловушка — сборка под другую архитектуру. На Apple Silicon (arm64) образ по умолчанию соберётся под arm64, а кластер может быть amd64. Нативные optional-зависимости при этом выберутся неверно. Решение — собирать в CI под целевую платформу (docker buildx build --platform linux/amd64) или явно указывать платформу для npm:

npm ci --omit=dev --os=linux --cpu=x64 --libc=glibc

NODE_ENV=production выставляется только в рантайм-стадии. Если задать его раньше, npm ci в стадии deps молча пропустит devDependencies, и сборка упадёт на отсутствующем typescript — ошибка, которую легко искать полдня.


Non-root и файловая система

По умолчанию процесс в контейнере работает от root. Внутри контейнера это ограничено пространством имён, но ограничение не absolитное: ошибка в mount, доступ к Docker socket, ядро с известной уязвимостью — и root в контейнере становится root на узле. Поэтому в образе node уже есть пользователь node, и финальная стадия переключается на него.

Три вещи, без которых USER node не работает:

  1. Права на файлы. COPY --chown=node:node — иначе приложение не прочитает dist/ и package.json. npm ci, выполненный от root, оставит node_modules с владельцем root; файлы должны быть доступны на чтение всем либо принадлежать node.
  2. Никакой записи в /app. Логи идут в stdout, временные файлы — в os.tmpdir() или в примонтированный том. Если приложение пишет загрузки в ./uploads, при read-only rootfs оно упадёт, а в оркестраторе файл исчезнет вместе с подом.
  3. Порт выше 1024. Непривилегированные пользователи не могут слушать порты ниже 1024, поэтому приложение слушает 3000, а 80/443 занимает прокси.

Усиление в оркестраторе продолжает ту же линию:

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop: ["ALL"]

readOnlyRootFilesystem: true почти всегда требует emptyDir для /tmp: Node пишет туда временные файлы, а некоторые библиотеки — кеш. Это нормально; ненормально — писать в директорию приложения.

Отдельно про образ: установка системных пакетов (apt-get install) требует root, поэтому её делают в промежуточной стадии или в самом начале финальной, до USER. sudo внутри контейнера не нужен никогда.


PID 1 и сигналы

docker stop отправляет SIGTERM процессу с PID 1 в контейнере, ждёт stop_grace_period (по умолчанию 10 секунд) и при неудаче присылает SIGKILL. В Kubernetes то же самое делает kubelet с terminationGracePeriodSeconds.

Отсюда две классические поломки.

Первая: сигнал получает не Node, а обёртка. Ядро применяет действие сигнала по умолчанию только к обычным процессам. Для PID 1 действует особое правило: если обработчик не установлен, сигнал игнорируется — так сделано, чтобы контейнер нельзя было убить случайным сигналом. Если в CMD стоит npm start, PID 1 — это npm, а Node — его дочерний процесс. npm не является полноценным init и не всегда пересылает сигнал вниз.

Форма запускаКто PID 1Дойдёт ли SIGTERM до Node
CMD ["node", "dist/server.js"]Nodeда, напрямую
CMD npm startnpmзависит от версии npm, обычно нет
CMD ["sh", "-c", "node dist/server.js"]shнет, без exec
ENTRYPOINT ["./docker-entrypoint.sh"]скрипттолько если скрипт делает exec node ...

Правило простое: exec-форма и exec в скриптах. Если entrypoint-скрипт подготавливает окружение, последняя строка должна быть exec "$@" или exec node dist/server.js — exec заменяет процесс оболочки на Node, и сигнал попадает по адресу.

Вторая: приложение не умеет останавливаться. Даже с правильным PID 1 Node по умолчанию завершится сразу, оборвав активные запросы. Нужен обработчик, который выполняет дренаж: перестаёт принимать трафик, доигрывает запросы, закрывает пулы и только потом выходит.

// src/lifecycle.js — сокращённая версия, полная в статье про надёжность
process.on('SIGTERM', async () => {
  logger.info('shutdown started');
  app.locals.draining = true;          // readiness начнёт отдавать 503
  await sleep(DRAIN_MS);               // балансировщику нужно время
  await new Promise((resolve) => server.close(resolve));
  server.closeIdleConnections();
  await pool.end();
  await redis.quit();
  logger.info('shutdown complete');
  process.exit(0);
});

Порядок шагов, бюджет времени и обработка второго сигнала разобраны в статье «Таймауты, ретраи и graceful shutdown». Здесь важно, что бюджет остановки должен быть меньше grace period: если код ждёт 30 секунд, а stop_grace_period равен 10, SIGKILL придёт раньше, чем закроются пулы.

Init-процесс. Кроме передачи сигналов, PID 1 отвечает за «сбор» зомби-процессов. Node, который запускает дочерние процессы (child_process.spawn), оставляет зомби, если родитель не вызывает wait. tini решает обе задачи — пересылку сигналов и reap:

docker run --init -p 3000:3000 taskflow:1.4.0

В Compose это init: true, в Kubernetes — ENTRYPOINT ["/sbin/tini", "--"] в образе, потому что своего init kubelet не добавляет. В образе tini ставится пакетом в финальной стадии (или берётся с tini-базы) и весит около 30 КБ.

Проверять это надо не рассуждением, а тестом: запустить контейнер, отправить запрос, который отвечает через секунду, сделать docker stop и убедиться, что клиент получил 200, а в логах есть shutdown complete, а не SIGKILL.


Лимиты памяти и heap

В контейнере память ограничена cgroup: docker run --memory=512m, resources.limits.memory в Kubernetes. При превышении срабатывает OOM-killer, процесс получает SIGKILL и код выхода 137. В логах приложения при этом пусто — оно не успело ничего записать, а в kubectl describe pod виден OOMKilled.

Проблема в том, что V8 не обязан знать про cgroup. Граница heap по умолчанию вычисляется от доступной памяти, и в контейнере на 512 МБ она может оказаться заметно выше. Heap спокойно растёт, RSS переходит лимит, и убивает процесс не V8 с понятным сообщением, а ядро.

Поэтому лимит heap задают явно — в CMD или через NODE_OPTIONS:

CMD ["node", "--max-old-space-size=384", "dist/server.js"]

Ориентир — 70–80% лимита контейнера. Остальное нужно не «на всякий случай», а на то, что в heap не входит:

ОбластьЧто тамУчитывает ли --max-old-space-size
Old spaceдолгоживущие объекты, кешида
Young spaceмолодые объекты, semi-spaceнет, отдельный --max-semi-space-size
ExternalBuffer, ArrayBuffer, нативные структурынет
Код и stackскомпилированный JS, стек потоковнет
libuvбуферы сокетов, файловые операциинет

Практический вывод: сервис, который держит в памяти большие Buffer (стримы, файлы, изображения), может умереть от OOM при heapUsed в 100 МБ. Как читать эти метрики и искать утечки — в статье «Производительность и память».

Что даёт явный лимит:

  • ошибка становится диагностируемой: FATAL ERROR: JavaScript heap out of memory, код 134, стек и последние логи на месте;
  • сборка мусора начинает работать раньше, и пила RSS не доходит до лимита cgroup;
  • размер heap перестаёт зависеть от машины, на которой запущен контейнер: одинаковый образ ведёт себя одинаково в CI, на ноутбуке и в проде.

Дополнительно полезны два флага. --heapsnapshot-near-heap-limit=3 сохраняет дампы при приближении к лимиту — потом их можно открыть в Chrome DevTools и найти, что держит память. --max-semi-space-size увеличивают только при доказанной проблеме с молодыми объектами: это ускоряет аллокации, но съедает память.

Не стоит ставить лимит «с запасом», надеясь на горизонтальное масштабирование: при лимите 2 ГБ и утечке в 10 МБ/час процесс проживёт дольше, но рестарт всё равно случится, а стоимость реплики вырастет вчетверо. Лимит — это часть контракта с оркестратором, а не настройка «чтобы не падало».


PM2, systemd и оркестратор

Вопрос «чем запускать Node» решается не вкусом, а тем, кто уже отвечает за жизненный цикл процесса.

ОкружениеКто перезапускаетКто масштабируетРоль PM2
Kubernetes, ECS, Nomadоркестраторреплики и HPAне нужен, часто вреден
Одна VMsystemdвручную или PM2 clusterоправдан
PaaS (Fly.io, Railway, Render)платформаплатформане нужен

В контейнере менеджер процессов дублирует оркестратор. Он перезапускает упавший процесс внутри пода, из-за чего оркестратор не видит проблему и не заменяет под; он не всегда пробрасывает SIGTERM, из-за чего graceful shutdown не срабатывает; он занимает PID 1 и добавляет ещё один слой, в котором может потеряться сигнал. Если PM2 всё же нужен (например, для cluster-режима в контейнере без оркестратора), берут pm2-runtime — он создан для контейнеров и пересылает сигналы.

На VM без оркестратора systemd делает ровно то, что нужно: держит процесс живым, собирает логи в journald, ограничивает ресурсы и корректно останавливает.

# /etc/systemd/system/taskflow.service
[Unit]
Description=TaskFlow API
After=network-online.target

[Service]
Type=simple
User=taskflow
WorkingDirectory=/srv/taskflow
EnvironmentFile=/etc/taskflow/env
ExecStart=/usr/bin/node --max-old-space-size=512 dist/server.js
Restart=always
RestartSec=2
KillSignal=SIGTERM
TimeoutStopSec=30
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/srv/taskflow/tmp
PrivateTmp=true

[Install]
WantedBy=multi-user.target

TimeoutStopSec должен быть больше бюджета graceful shutdown: systemd пришлёт SIGKILL по его истечении. Restart=always без ограничения по частоте превращает падающий на старте сервис в бесконечный цикл рестартов — systemd сам применяет backoff, но логи стоит смотреть сразу.

PM2 на VM оправдан, когда нужен cluster-режим — несколько процессов на одном порту с балансировкой на уровне ядра:

pm2 start dist/server.js -i max --name taskflow
pm2 save && pm2 startup systemd

Но у cluster-режима есть та же цена, что у cluster-модуля Node: sticky-сессии, общее состояние в памяти и сложность с WebSocket. В контейнере вместо этого масштабируют реплики — оркестратор распределяет трафик и не требует общего порта. Подробнее о выборе между процессами и потоками — в статье «Worker Threads и cluster».


Reverse proxy и TLS

Node умеет HTTPS, но ставить его прямо в приложение в проде почти никогда не стоит. Причины не в производительности, а в обязанностях, которые удобнее отдать одному слою:

  • терминация TLS и автоматическое продление сертификатов;
  • HTTP/2 и сжатие;
  • ограничение размера тела и таймауты на медленных клиентов (slowloris);
  • статика и кеширование;
  • маршрутизация нескольких сервисов по путям и доменам;
  • единая точка для логов доступа и rate limit.

Типовая конфигурация nginx перед Node:

upstream taskflow {
    server 127.0.0.1:3000;
    keepalive 32;
}

server {
    listen 443 ssl;
    http2 on;
    server_name api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    client_max_body_size 10m;
    client_header_timeout 10s;
    client_body_timeout 15s;

    location / {
        proxy_pass http://taskflow;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 2s;
        proxy_read_timeout 30s;
    }

    # SSE и стриминг нельзя буферизовать
    location /events {
        proxy_pass http://taskflow;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Несколько деталей, которые чаще всего забывают:

proxy_set_header Connection "" и keepalive 32. Без этого nginx открывает новое соединение на каждый запрос, и весь смысл keep-alive теряется. С ним — переиспользует пул, что заметно снижает задержку и число TIME_WAIT-сокетов.

Таймауты должны быть согласованы. keepAliveTimeout в Node делают больше, чем idle-таймаут прокси, иначе возникает гонка: nginx переиспользует соединение ровно в тот момент, когда Node его закрывает, и клиент получает 502. Классическая настройка — Node keepAliveTimeout: 65_000, headersTimeout: 66_000, nginx keepalive_timeout 60s.

X-Forwarded-* без trust proxy бесполезны. Приложение видит IP прокси и схему http. В Express это лечится одной строкой:

app.set('trust proxy', 1); // доверяем ровно одному хопу
const app = Fastify({ trustProxy: true });

Важно именно число хопов, а не true. С trust proxy: true приложение верит заголовку от любого клиента, и X-Forwarded-For: 1.2.3.4 позволяет обойти rate limit по IP и подделать адрес в логах. Без этой настройки ломаются req.ip, req.protocol, редиректы http → https и secure-cookie: браузер не поставит cookie, потому что приложение считает соединение небезопасным.

proxy_buffering off для SSE и стриминга. По умолчанию nginx копит ответ и отдаёт его целиком; для text/event-stream это означает, что события не доходят до клиента. Та же логика — для WebSocket: нужны Upgrade и Connection, иначе handshake не пройдёт. Подробности — в статье «WebSocket и SSE на сервере».

TLS снаружи, доверие внутри. Между прокси и приложением трафик идёт по приватной сети; если сеть не доверенная (несколько хостов, облако), добавляют mTLS или подпись. HSTS включают только после того, как весь трафик гарантированно переведён на HTTPS.


Health checks

Проверки нужны разным потребителям: оркестратору — чтобы перезапускать и балансировать, прокси — чтобы не слать трафик в мёртвый инстанс, человеку — чтобы понять, что происходит. Один эндпоинт на всё не работает, поэтому проверок три.

ПроверкаВопросЧто проверяетРеакция при провале
startupприложение уже поднялось?инициализация, миграции, прогревне запускать liveness, ждать
livenessпроцесс жив и не завис?event loop отвечаетперезапустить контейнер
readinessможно ли слать трафик?зависимости, draining-флагубрать из балансировки

Главное правило: liveness не проверяет зависимости. Если liveness ходит в базу, то короткий сбой базы провалит проверку у всех реплик одновременно, оркестратор перезапустит их все, и деградация превратится в полный отказ — при том, что база уже восстановилась. Liveness проверяет только сам процесс: event loop не заблокирован, HTTP-сервер принимает соединения.

// src/routes/health.js
export function healthRoutes(app, deps) {
  app.get('/health/live', (req, res) => {
    res.status(200).json({ status: 'ok' });
  });

  app.get('/health/ready', async (req, res) => {
    if (deps.isDraining()) {
      return res.status(503).json({ status: 'draining' });
    }

    try {
      await deps.pingDb();      // таймаут 500 мс
      await deps.pingRedis();   // таймаут 300 мс
      return res.status(200).json({ status: 'ready' });
    } catch (err) {
      return res.status(503).json({ status: 'not ready', reason: err.code });
    }
  });
}

Требования к эндпоинтам: без аутентификации (иначе проверка не пройдёт из kubelet), без записи в базу, с жёстким таймаутом на каждую зависимость, с кешированием результата на 1–5 секунд. Если readiness ходит в базу на каждый вызов, а проверка выполняется каждые две секунды на двадцати репликах, база получает лишние 10 RPS служебного трафика — и это в момент, когда ей и так тяжело.

Docker-проверка в slim-образе не может использовать curl (его там нет), поэтому проверяют самим Node:

HEALTHCHECK --interval=10s --timeout=2s --start-period=20s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:3000/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"

HEALTHCHECK помечает контейнер unhealthy, но Docker сам его не перезапускает — это делает Swarm или внешний супервизор. В Compose статус используют через depends_on: condition: service_healthy, чтобы API не стартовал раньше базы.

В Kubernetes probes задаются отдельно и с разными порогами:

startupProbe:
  httpGet: { path: /health/live, port: 3000 }
  periodSeconds: 2
  failureThreshold: 30      # до 60 секунд на старт
livenessProbe:
  httpGet: { path: /health/live, port: 3000 }
  periodSeconds: 10
  timeoutSeconds: 2
  failureThreshold: 3
readinessProbe:
  httpGet: { path: /health/ready, port: 3000 }
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 2

startupProbe спасает медленный старт: пока она не прошла, liveness не выполняется, и контейнер не убивают на прогреве кеша или применении миграций. Как связать проверки с метриками и логами — в статье «Логирование и наблюдаемость».


Zero-downtime деплой

Zero-downtime — это не «деплой без паузы», а набор условий, при которых старая версия уходит только после того, как новая готова принимать трафик, а начатые запросы не обрываются.

Последовательность rolling update:

1. поднимается новая реплика, проходит startup и readiness
2. балансировщик добавляет её в ротацию, трафик распределяется
3. старой реплике: readiness → 503
4. пауза 3–10 с, пока балансировщик исключит её из ротации
5. SIGTERM → дренаж активных запросов → закрытие пулов
6. по истечении grace period — SIGKILL, если процесс не успел

Шаг 3 и 4 — то, что пропускают чаще всего. Балансировщик не узнаёт о завершении мгновенно: kube-proxy обновляет правила, ingress-контроллер перечитывает endpoints, а открытые keep-alive-соединения живут своей жизнью. Если сразу после SIGTERM закрыть сервер, часть запросов придёт в уже закрытый сокет.

Условия, без которых zero-downtime не получится:

УсловиеПочемуГде разобрано
Приложение statelessиначе новая реплика не сможет обслужить сессию«Аутентификация в API»
Graceful shutdownиначе запросы обрываются на середине«Таймауты, ретраи и graceful shutdown»
Readiness отдельно от livenessиначе трафик идёт в непрогретый инстансраздел выше
Обратная совместимость схемыстарая и новая версии работают одновременно«Доступ к базам данных»
Нет локального состоянияфайлы и кеш в памяти исчезнут с подом«Redis и фоновые задачи»

Миграции — отдельный шаг, а не строчка в старте приложения. Если каждый под при старте применяет миграции, двадцать реплик одновременно попытаются взять блокировку и изменят схему; часть упадёт, часть подождёт, а деплой превратится в лотерею. Миграции запускают отдельной задачей (Job, шаг CI) до раскатки, а схема должна быть совместима с обеими версиями кода — паттерн expand-contract разобран в статье «Blue-Green, Canary и Feature Flags».

expand:   добавить колонку/таблицу, которую знает только новый код
migrate:  перенести данные, старый код продолжает работать
contract: удалить старое поле, когда старый код выведен из эксплуатации

Теги образов — иммутабельные. latest и stable не дают откатиться на конкретную версию: через час под тем же тегом лежит другой образ. Тег — git sha или semver, а latest — только указатель для удобства.

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

Параметры раскатки. maxUnavailable: 0, maxSurge: 1 дают запас по ёмкости и отсутствие просадки, но требуют свободных ресурсов в кластере. maxUnavailable: 1 дешевле, но на это время ёмкость падает — для сервиса у края пропускной способности это заметно.

Отдельно про WebSocket: соединения живут часами, и под с ними не завершится, если ждать их закрытия. Раскатка с долгими соединениями требует либо дренажа с уведомлением клиента, либо sticky-маршрутизации, либо выноса сокетов в отдельный шлюз — об этом в статье «WebSocket и SSE на сервере».


Секреты и конфигурация

Образ должен быть одинаковым во всех окружениях, а различаться — только конфигурация. Это принцип 12-factor, и в контейнере он работает буквально: один и тот же digest образа запускается в staging и проде с разными переменными окружения.

Что не попадает в образ:

  • .env и любые файлы с секретами — они в .dockerignore, а не в слоях;
  • URL окружений и ключи внешних сервисов — передаются при запуске;
  • NODE_ENV=development — рантайм всегда production;
  • токены приватного npm-реестра — для них есть build secrets.

Приватный реестр нужен на этапе сборки, и ARG NPM_TOKEN — плохое решение: значение остаётся в истории слоёв и в docker history. BuildKit передаёт секрет только на время шага:

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci --omit=dev
docker build --secret id=npmrc,src="$HOME/.npmrc" -t taskflow:1.4.0 .

В рантайме секреты приходят из secret store платформы: Kubernetes Secret, Vault, AWS Secrets Manager, Docker secrets. Платформа подставляет их в окружение или в файл при старте контейнера, а ротация происходит без пересборки образа.

Конфигурацию валидируют на старте и падают, если она неполная или противоречивая. Сервис, который поднялся с пустым DATABASE_URL и упал на первом запросе, уже прошёл readiness и получил трафик — то есть ошибка вышла в прод вместо CI. Схема конфига и fail-fast разобраны в статье «Конфигурация и валидация».

Две частые ошибки вокруг конфигурации:

  • Секрет в переменной окружения и в логах. Дамп process.env при старте — утечка. Логируйте только имена переменных и явно помечайте секреты в логгере.
  • Секрет, запечённый в образ «на время». Он останется в слое навсегда, даже если следующий слой удалит файл: слои неизменяемы, а образ уже разошёлся по registry.

Практика: TaskFlow

Соберём деплой для TaskFlow из предыдущих статей: Express + PostgreSQL + Redis + воркер BullMQ.

1. Dockerfile. Стадии deps → build → prod-deps → runtime из раздела выше. В CMD — node --max-old-space-size=384 dist/server.js, USER node, init: true в Compose или tini в entrypoint.

2. Compose для локальной проверки. Порт публикуется только у API; база и Redis доступны по внутренней сети.

services:
  api:
    build: .
    init: true
    ports: ["3000:3000"]
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://taskflow:secret@db:5432/taskflow
      REDIS_URL: redis://cache:6379
    depends_on:
      db: { condition: service_healthy }
      cache: { condition: service_started }
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health/ready').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 10s
      timeout: 2s
      retries: 3
      start_period: 20s
    deploy:
      resources:
        limits: { memory: 512M }

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: taskflow
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: taskflow
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U taskflow"]
      interval: 5s

  cache:
    image: redis:7

3. Проверки. /health/live отвечает мгновенно и не трогает зависимости. /health/ready проверяет базу и Redis с таймаутами 500 и 300 мс и отдаёт 503, пока draining = true.

4. Прокси. nginx с TLS, client_max_body_size 10m, proxy_buffering off для /events, keepalive 32 до апстрима. В приложении — trust proxy: 1.

5. Память. --max-old-space-size=384 при лимите 512 МБ. Проверяем, что при утечке процесс падает с heap out of memory (код 134), а не OOMKilled (код 137) без логов.

6. Остановка. installShutdown из статьи про надёжность: draining → 5 секунд паузы → server.close() → дренаж до 20 секунд → воркер → пулы → выход. terminationGracePeriodSeconds: 30, stop_grace_period: 25s.

7. Проверка деплоя. Три сценария в CI:

# старт и healthcheck
docker compose up -d --wait

# запрос, который отвечает через секунду, и остановка под нагрузкой
docker compose stop -t 25 api
docker compose logs api | tail -5   # ожидаем "shutdown complete"
docker inspect -f '{{.State.ExitCode}}' $(docker compose ps -q api)  # 0
  • docker stop под нагрузкой: ни один начатый запрос не оборван, процесс выходит с кодом 0 до истечения grace period.
  • Контейнер с лимитом 512 МБ и утечкой: падение с внятным сообщением V8 и дампом heap, а не 137.
  • Новая реплика при непрогретом кеше: readiness держит 503, трафик на неё не идёт.

Что закрыто: образ содержит только рантайм и production-зависимости, процесс работает не от root, сигналы доходят до Node, память ограничена предсказуемо, прокси и проверки настроены, деплой не обрывает запросы.

Что добавляют в проде: сканирование образа (trivy, grype), подпись образов (cosign), политики admission control, автоматический откат по метрикам, отдельный Job для миграций, алерты на OOMKilled и на превышение времени остановки.


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

  • CMD npm start. PID 1 — npm, сигнал до Node не доходит, контейнер умирает по SIGKILL.
  • Нет обработчика SIGTERM. Node завершается сразу, активные запросы получают обрыв.
  • sh -c без exec. Оболочка съедает сигнал; в entrypoint нужен exec.
  • Нет --init/tini при дочерних процессах. Зомби накапливаются, сигналы не пересылаются.
  • stop_grace_period меньше времени остановки. SIGKILL приходит раньше, чем закрылись пулы.
  • USER node без --chown. Приложение падает на чтении dist/ или node_modules.
  • Запись в /app. С read-only rootfs процесс падает, без него — файлы исчезают с подом.
  • node_modules из dev-стадии. Инструменты сборки в проде, нативные модули под чужую платформу, раздутый образ.
  • NODE_ENV=production в стадии deps. npm ci пропускает devDependencies, сборка падает на отсутствующем typescript.
  • Нет .dockerignore. В контекст попадают .git, node_modules и .env; сборка медленная, секреты в слоях.
  • latest в проде. Невозможно откатиться на конкретную версию, кеш отдаёт непредсказуемый образ.
  • Нет --max-old-space-size. cgroup убивает процесс по OOM без логов и дампа.
  • --max-old-space-size равен лимиту контейнера. RSS = heap + external + код, процессу не хватает памяти на буферы.
  • Сборка под чужую архитектуру. Optional-зависимости выбраны под хост, а не под кластер: invalid ELF header.
  • Liveness проверяет базу. Сбой зависимости перезапускает все реплики и превращает деградацию в отказ.
  • Readiness без draining-флага. Балансировщик шлёт трафик в закрывающийся процесс.
  • Миграции на старте каждой реплики. Гонка за блокировку, падения, непредсказуемый деплой.
  • Приложение слушает 127.0.0.1. В контейнере порт недоступен снаружи.
  • Нет trust proxy. Rate limit по IP считает всех клиентов одним адресом, secure-cookie не ставится.
  • trust proxy: true. Клиент подделывает X-Forwarded-For и обходит ограничения.
  • keepAliveTimeout меньше, чем у прокси. Гонка при переиспользовании соединения и случайные 502.
  • proxy_buffering on для SSE. События копятся в nginx и не доходят до клиента.
  • PM2 в Kubernetes. Дублирует перезапуски, ломает SIGTERM и занимает PID 1.
  • Секрет через ARG. Значение остаётся в истории слоёв; нужен --mount=type=secret на время шага.

Ключевые тезисы для интервью

  • Multi-stage разделяет сборку и рантайм: инструменты и dev-зависимости остаются в промежуточных стадиях, а финальный образ содержит только dist и production-зависимости, поставленные npm ci --omit=dev из lockfile.
  • В контейнере сигнал получает PID 1, поэтому нужны exec-форма CMD, exec в entrypoint-скриптах и tini/--init; без обработчика SIGTERM Node завершается сразу, обрывая запросы.
  • USER node вместе с --chown, read-only rootfs и сброшенными capabilities убирает root из контейнера, но требует, чтобы приложение не писало в свою директорию и слушало порт выше 1024.
  • Лимит heap задают явно на 70–80% лимита контейнера: V8 не обязан видеть cgroup, а Buffer и код живут вне old space, поэтому без запаса приходит OOM-killer с кодом 137 вместо диагностируемого heap out of memory.
  • Liveness проверяет только живость процесса, readiness — готовность принимать трафик, startup — завершение инициализации; проверка зависимостей в liveness превращает сбой базы в перезапуск всех реплик.
  • Zero-downtime складывается из draining-флага, паузы на распространение, graceful shutdown и обратно совместимых миграций: без любого из звеньев часть запросов теряется.
  • Reverse proxy берёт на себя TLS, лимиты и keep-alive, а приложению нужен trust proxy с числом хопов, иначе req.ip, secure-cookie и rate limit работают неправильно.

Заключение

Деплой Node-сервиса — это несколько явных решений, принятых в Dockerfile и в коде жизненного цикла. Образ собирается в стадиях: инструменты сборки не попадают в рантайм, зависимости ставятся из lockfile, процесс работает от непривилегированного пользователя, а память ограничена явно — V8 и cgroup не договариваются сами.

Процесс получает сигналы только тогда, когда запущен напрямую или через init, а останавливаться умеет только тогда, когда это написано в коде: draining, пауза, закрытие соединений и пулов. Проверки разделены по смыслу, иначе один сбой базы каскадом перезапускает весь сервис. Прокси закрывает TLS и лимиты, но требует от приложения корректных trust proxy и согласованных таймаутов.

Zero-downtime — не свойство платформы, а сумма условий: stateless-приложение, readiness, graceful shutdown, совместимые миграции и иммутабельные теги. Дальше логично перейти к тому, как эти слои складываются в структуру кода, — к архитектуре Node-бэкенда.

Полезные ссылки