Docker и деплой Node.js
На машине разработчика приложение запускается одной командой и живёт в знакомом окружении: файлы рядом, память хоста, Ctrl+C в терминале. В проде у процесса другие правила — cgroup-лимит вместо свободной памяти, SIGTERM вместо нажатия клавиши, read-only файловая система и прокси перед портом. Половина инцидентов при первом деплое связана не с кодом, а с этими различиями. Разберём, как собрать образ, корректно передать процессу управление и выкатить новую версию без оборванных запросов.
Содержание
- Что меняется в контейнере
- Dockerfile: multi-stage сборка
- Зависимости: lockfile и слои
- Non-root и файловая система
- PID 1 и сигналы
- Лимиты памяти и heap
- PM2, systemd и оркестратор
- Reverse proxy и TLS
- Health checks
- Zero-downtime деплой
- Секреты и конфигурация
- Практика: TaskFlow
- Частые ошибки
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Что меняется в контейнере
Контейнер — не «маленькая виртуалка», а процесс с ограничениями ядра. Отличия, которые ломают код, написанный под локальный запуск, удобно держать перед глазами:
| Дома | В контейнере | Что ломается |
|---|---|---|
| Память хоста | cgroup-лимит, OOM-killer | heap растёт выше лимита, процесс убивают без логов |
Ctrl+C → SIGINT | SIGTERM в PID 1, затем SIGKILL | сигнал не доходит до Node или игнорируется |
| Файлы проекта рядом | read-only rootfs, нет node_modules | запись в ./tmp, чтение dev-конфига |
localhost:3000 | 0.0.0.0, прокси и TLS снаружи | приложение слушает 127.0.0.1 и недоступно |
| Один процесс | несколько реплик, rolling update | состояние в памяти, миграции на каждом старте |
npm run dev с watch | node dist/server.js | dev-зависимости в рантайме, 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 не работает:
- Права на файлы.
COPY --chown=node:node— иначе приложение не прочитаетdist/иpackage.json.npm ci, выполненный от root, оставитnode_modulesс владельцем root; файлы должны быть доступны на чтение всем либо принадлежатьnode. - Никакой записи в
/app. Логи идут в stdout, временные файлы — вos.tmpdir()или в примонтированный том. Если приложение пишет загрузки в./uploads, при read-only rootfs оно упадёт, а в оркестраторе файл исчезнет вместе с подом. - Порт выше 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 start | npm | зависит от версии 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 |
| External | Buffer, 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 | не нужен, часто вреден |
| Одна VM | systemd | вручную или 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; без обработчикаSIGTERMNode завершается сразу, обрывая запросы. 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-бэкенда.
Полезные ссылки
- Docker: multi-stage builds — стадии, копирование артефактов, кеш слоёв
- Docker: build secrets — передача токенов без попадания в слои
- Docker:
docker run --init— запуск с init-процессом - Docker:
HEALTHCHECK— интервалы,start-period,retries - Node.js:
--max-old-space-size— лимит heap и поведение при исчерпании - Node.js:
server.close()— остановка сервера и ожидание соединений - npm ci — воспроизводимая установка из lockfile
- Express: behind proxies —
trust proxyиX-Forwarded-* - Fastify:
trustProxy— настройка доверия прокси - Kubernetes: probes — liveness, readiness и startup
- Kubernetes: pod termination —
terminationGracePeriodSecondsиpreStop - nginx:
ngx_http_proxy_module— таймауты, буферизация, keep-alive до апстрима - The Twelve-Factor App: Config — конфигурация в окружении
- Docker для фронтенда — multi-stage, nginx, compose и healthcheck на клиентской стороне
- Blue-Green, Canary и Feature Flags — стратегии выката, rollback и expand-contract
- Переменные окружения и секреты — build-time и runtime-конфигурация