К содержимому
Войти

Node.js Road Map

🚀 Конфиг, логи и готовность к проду

Сервис, который отвечает на запросы локально, ещё не готов к проду. Он должен брать конфиг из окружения и падать при старте, если конфиг кривой, писать JSON-логи с request id и без паролей, а по SIGTERM закрываться, не обрывая запросы. На собеседовании этими вопросами проверяют, работал ли человек с продом, и ответ «ну, console.log и process.exit()» проверку не проходит

🧠 Как это устроено

Конфиг живёт в окружении

Правило из 12-factor app: всё, что отличается между стендами, приходит из переменных окружения. Это адрес базы, ключи, уровень логов, порт. Один образ едет на стейдж и в прод, меняются только переменные. Конфиг в config.prod.json в репозитории значит, что смена пароля требует релиза, а сам пароль видит каждый, у кого есть доступ к git

Локально переменные держат в .env, и пакет dotenv для этого больше не нужен:

  • флаг node --env-file=.env app.js есть с v20.6.0, а экспериментальным он перестал быть в v24.10.0 и v22.21.0. Файлов можно передать несколько, следующий перекрывает предыдущий
  • --env-file-if-exists (с v22.9.0) делает то же, но не падает, если файла нет
  • process.loadEnvFile(path) загружает файл из кода, по умолчанию ./.env. Метод есть с v21.7.0 и v20.12.0, стабилен с тех же v24.10.0 и v22.21.0

Переменная, которая уже есть в окружении, важнее значения из файла, так что реальные переменные контейнера перекроют .env. Сам .env не коммитят, в репозиторий кладут .env.example с ключами и заглушками

Конфиг проверяют при старте

process.env — словарь строк, где любой ключ может отсутствовать. Если читать process.env.DATABASE_URL прямо в сервисе, опечатка в имени всплывёт на первом запросе к базе, иногда через час после деплоя или в ночном кроне. Правильно один раз при старте разобрать окружение схемой, привести типы и упасть с понятной ошибкой. Под не станет ready, деплой остановится, старая версия продолжит работать. Остальной код получает типизированный config, а не process.env. Схемы Zod и safeParse разобраны на странице про сужение типов в модуле «TypeScript»

Почему pino, а не console.log

У console.log в проде три проблемы. Он пишет текст, который сборщик логов не разберёт на поля. У него нет уровней, и debug не выключить без правки кода. И запись в stdout бывает синхронной: на Linux и macOS вывод в файл и в терминал блокирует цикл событий до конца записи. Уровни, структурные поля и сбор логов разобраны на странице «Логи» в модуле про Docker и Kubernetes, здесь только Node-часть

pino пишет одну JSON-строку на событие: level, time, pid, msg и всё, что передано объектом. В stdout он пишет через pino.destination, и с sync: false запись асинхронная: строки копятся в буфер и уходят крупными кусками. Цена названа в документации: при внезапном падении машины последние строки буфера теряются. pino-pretty и отправку логов в другие места pino выносит в транспорты, они работают в отдельном worker thread

Для HTTP вместо morgan берут pino-http. Он вешает на запрос дочерний логгер req.log и пишет одну строку request completed с методом, URL, статусом и responseTime. В Fastify pino встроен, в Nest его подключают через nestjs-pino

Секреты не попадают в логи

Опция redact в pino заменяет значения по путям на [Redacted]: req.headers.authorization, password, *.token. С remove: true ключ удаляется целиком. Пути без звёздочки стоят около 2% к сериализации, wildcard заметно дороже, поэтому ключи лучше перечислять явно. redact — страховка. Основная защита в том, чтобы не передавать в лог объект пользователя или тело запроса целиком

Request id без передачи аргументом

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

AsyncLocalStorage из node:async_hooks решает это. als.run(store, fn) запускает fn с контекстом, и als.getStore() вернёт этот store в любом коде, вызванном из fn, в том числе после await и в колбэках таймеров. Контекст привязан к асинхронной цепочке, поэтому параллельные запросы его не путают. API стабилен с v16.4.0. Метод enterWith до сих пор экспериментальный: его контекст живёт до конца текущего синхронного кода и может протечь в соседние обработчики, поэтому документация советует run. На ALS построены nestjs-cls и контекст трейсов в OpenTelemetry

Graceful shutdown

Оркестратор шлёт контейнеру SIGTERM, ждёт и, если процесс не вышел, добивает его SIGKILL. Graceful shutdown — то, что сервис успевает сделать между двумя сигналами. Без обработчика Node на SIGTERM сразу выходит с кодом 143 (128 + 15), и запросы в работе обрываются. С обработчиком поведение по умолчанию отключается, и выйти процесс должен сам. Порядок такой:

  1. Перестать быть ready. Readiness-эндпоинт начинает отвечать 503, балансировщик убирает под из ротации и не шлёт новые запросы
  2. Вызвать server.close(). Сервер больше не принимает соединения, а с v19 сразу закрывает простаивающие keep-alive соединения. Запросы в работе дорабатывают, колбэк close сработает, когда закроется последнее соединение
  3. Остановить потребление из брокера и дождаться обработки взятых сообщений, остановить фоновые таймеры и кроны
  4. Закрыть пул базы, соединения с брокером и Redis. Именно в таком порядке: сначала уходят те, кто пишет в базу, потом сама база
  5. Выйти с кодом 0. Если не уложились в таймаут, вызвать server.closeAllConnections() и выйти с кодом 1

Без таймаута один зависший запрос держит процесс до SIGKILL. Таймаут ставят меньше, чем ждёт оркестратор, в Kubernetes это terminationGracePeriodSeconds. Как это выглядит со стороны Kubernetes, разобрано на странице «Пробы, ресурсы и деплой без простоя». В Nest те же шаги делают хуки закрытия после app.enableShutdownHooks(), подробнее — на странице про путь запроса в NestJS

Почему SIGTERM не доходит

Первая причина — лишнее звено. С CMD npm start первым процессом становится npm, с shell-формой CMD node app.js — sh. Сигнал получает обёртка, и до Node он может не дойти, поэтому best practices официального образа Node советуют запускать node в CMD напрямую. Вторая причина в самом PID 1: ядро не применяет к нему действия сигналов по умолчанию, а Node не рассчитан работать первым процессом. Помогает docker run --init или tini в образе. Как это собрать, разберём на странице «Node.js в контейнере»

Health-эндпоинты со стороны Node

/livez отвечает «процесс жив» и не ходит во внешние зависимости: если liveness проверяет базу, её падение перезапустит все поды разом, и это ничего не исправит. /readyz отвечает «можно слать трафик»: пул базы поднят, сервис не останавливается. Оба дешёвые, без авторизации и без лога на каждый вызов, в pino-http для этого есть autoLogging.ignore

Зависимости и Permission Model

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

  • package-lock.json в репозитории и npm ci в CI и Dockerfile вместо npm install. npm ci ставит строго по lockfile, падает при расхождении с package.json и никогда не переписывает lockfile
  • npm audit --audit-level=high в CI. Флаг задаёт порог ненулевого кода выхода, отчёт остаётся полным. npm audit fix --force ставит мажорные версии, вслепую его не запускают
  • ignore-scripts=true в .npmrc отключает postinstall и другие скрипты пакетов, которые иначе выполняются на машине разработчика и в CI прямо при установке. Пакетам с нативной сборкой их разрешают точечно
  • npm audit signatures проверяет подписи реестра и provenance скачанных пакетов

Permission Model ограничивает процесс в рантайме. С --permission закрыты файловая система, дочерние процессы, worker threads и нативные аддоны, а открывают их явно: --allow-fs-read=/app, --allow-fs-write=/tmp, --allow-child-process. Запрещённая операция бросает ERR_ACCESS_DENIED, из кода право проверяет process.permission.has('fs.write'). Модель стабильна с v23.5.0 и v22.13.0. Флаг --allow-net появился только в v25.0.0, на Node 22 сеть под --permission открыта. Документация называет модель ремнём безопасности для доверенного кода: от вредоносного пакета она не защищает, а симлинки и открытые файловые дескрипторы её обходят

🛠️ На практике

Конфиг: схема при старте

// config.mjs
import { z } from 'zod'

const Env = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']),
  PORT: z.coerce.number().int().default(8080),
  DATABASE_URL: z.url(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
})

const parsed = Env.safeParse(process.env)
if (!parsed.success) {
  console.error('Конфиг невалиден:\n' + z.prettifyError(parsed.error))
  process.exit(1)
}
export const config = Object.freeze(parsed.data)
$ node --env-file=.env config.mjs        # в .env NODE_ENV=production
$ NODE_ENV=prod node --env-file=.env config.mjs
Конфиг невалиден:
✖ Invalid option: expected one of "development"|"test"|"production"
  → at NODE_ENV

Во втором запуске NODE_ENV=prod из окружения перекрыл файл, и сервис упал с кодом 1 до первого запроса. В Nest то же делает ConfigModule.forRoot({ validationSchema }) или validate: при ошибке приложение не стартует. validationSchema принимает Standard Schema (Zod, Valibot, ArkType) или Joi, читать значения удобно через configService.getOrThrow()

Request id через AsyncLocalStorage

import { AsyncLocalStorage } from 'node:async_hooks'

const als = new AsyncLocalStorage()

function log(msg) {
  console.log(JSON.stringify({ reqId: als.getStore()?.reqId, msg }))
}

async function loadUser(ms) {
  await new Promise((r) => setTimeout(r, ms)) // «поход в базу»
  log('user loaded')
}

function handle(reqId, ms) {
  return als.run({ reqId }, async () => {
    log('start')
    await loadUser(ms)
  })
}

await Promise.all([handle('a1', 30), handle('b2', 10)])
log('outside')
// {"reqId":"a1","msg":"start"}
// {"reqId":"b2","msg":"start"}
// {"reqId":"b2","msg":"user loaded"}
// {"reqId":"a1","msg":"user loaded"}
// {"msg":"outside"}

b2 закончил раньше, но каждый лог получил свой reqId, хотя loadUser о нём не знает. Вне run контекста нет, и getStore() вернул undefined

JavaScript · pino-http, redact и reqId из ALS в каждой строке

const http = require('node:http')
const { randomUUID } = require('node:crypto')
const { AsyncLocalStorage } = require('node:async_hooks')
const pino = require('pino')
const pinoHttp = require('pino-http')

const als = new AsyncLocalStorage()
const logger = pino({
  redact: ['req.headers.authorization', 'req.headers.cookie'],
  mixin: () => ({ reqId: als.getStore()?.reqId }),
})
const httpLogger = pinoHttp({
  logger,
  genReqId: (req, res) => {
    const id = req.headers['x-request-id'] ?? randomUUID()
    res.setHeader('x-request-id', id)
    return id
  },
})

async function getOrders() {
  await new Promise((r) => setTimeout(r, 5))
  logger.info('orders loaded') // reqId подставит mixin
}

http.createServer((req, res) => {
  httpLogger(req, res)
  als.run({ reqId: req.id }, async () => {
    await getOrders()
    res.end('ok')
  })
}).listen(3000)
// {"level":30,...,"reqId":"req-42","msg":"orders loaded"}
// {"level":30,...,"req":{"id":"req-42",...,"authorization":"[Redacted]"},
//  "res":{"statusCode":200,...},"responseTime":6,"msg":"request completed"}

По умолчанию pino-http нумерует запросы числами и x-request-id не читает, поэтому genReqId свой. Id в ответе поможет поддержке найти все строки запроса

Graceful shutdown на голом node:http

import http from 'node:http'

let ready = true
const server = http.createServer(async (req, res) => {
  if (req.url === '/readyz') {
    res.statusCode = ready ? 200 : 503
    return res.end()
  }
  await new Promise((r) => setTimeout(r, 300)) // медленный запрос
  res.end('done')
})
const db = { end: async () => console.log('пул БД закрыт') } // вместо pg.Pool

async function shutdown(signal) {
  console.log(`получен ${signal}`)
  ready = false
  const timer = setTimeout(() => {
    server.closeAllConnections()
    process.exit(1)
  }, 10_000)
  timer.unref() // таймер не держит процесс

  server.close(async (err) => {
    console.log('сервер закрыт, запросы дождались')
    await db.end()
    process.exit(err ? 1 : 0)
  })
  server.closeIdleConnections()
}

process.once('SIGTERM', shutdown)
process.once('SIGINT', shutdown)

server.listen(3000, async () => {
  const pending = fetch('http://localhost:3000/slow').then((r) => r.text())
  setTimeout(() => process.kill(process.pid, 'SIGTERM'), 50)
  console.log('ответ на медленный запрос:', await pending)
})
// получен SIGTERM
// ответ на медленный запрос: done
// сервер закрыт, запросы дождались
// пул БД закрыт
// exit code 0

SIGTERM пришёл через 50 мс, запрос шёл 300 мс, и клиент всё равно получил ответ, а пул закрылся после. На Node 19+ closeIdleConnections() дублирует close(), но страхует старые версии. unref() не даёт таймеру держать процесс лишние 10 секунд. В Fastify и Nest вместо server.close() вызывают app.close()

⚠️ Где ошибаются

process.exit() прямо в обработчике SIGTERM. Процесс выходит мгновенно, запросы в работе получают обрыв соединения, а асинхронный буфер логов не успевает записаться. Выходить надо из колбэка server.close() после закрытия ресурсов

Обработчик без таймаута. Зависший запрос к внешнему API держит server.close() вечно. Процесс сидит до SIGKILL, пул базы не закрывается, а деплой каждый раз ждёт полный grace period

Чтение process.env по всему коду. Строка 'false' в if даёт true, порт приходит строкой, опечатку в имени замечают на инциденте. Один модуль конфига со схемой убирает всё сразу

Секрет в логе через объект целиком. logger.info({ user }) или тело запроса в логе ошибки отправляют хеши паролей и токены туда, где их читает больше людей, чем имеет доступ к базе. Логируй id и нужные поля

🎯 Вопросы с собеседований

Что такое graceful shutdown и как сделать его в Node?

Это остановка между SIGTERM и SIGKILL без потерянных запросов. В process.on('SIGTERM') сервис переключает readiness в 503, вызывает server.close() и ждёт текущие запросы. Потом останавливает потребителей очередей, закрывает пул базы и брокер и выходит с кодом 0. Таймаут меньше grace period оркестратора вызывает closeAllConnections() и process.exit(1). И сигнал должен дойти: node запускают напрямую, без npm start, с init-процессом вроде tini

Как хранить секреты и конфиг?

Из переменных окружения, которые задаёт оркестратор или CI: Kubernetes Secrets, Vault, переменные GitLab. В репозитории только .env.example, настоящий .env в .gitignore, локально его читает node --env-file=.env. При старте окружение проверяется схемой, и сервис падает, если чего-то не хватает. В логах секретов нет: объекты целиком не логируются, а redact страхует

Как защититься от уязвимых зависимостей?

Зафиксировать дерево lockfile и ставить через npm ci, чтобы в прод ехало то, что прошло тесты. В CI запускать npm audit --audit-level=high, обновления катить ботом вроде Renovate или Dependabot небольшими пачками. Отключить install-скрипты через ignore-scripts: postinstall чужого пакета выполняется прямо при установке. Подписи проверяет npm audit signatures. Permission Model сужает права в рантайме, но защищает от ошибок, а не от вредоносного пакета

Как прокинуть request id через весь запрос без передачи аргументом?

Через AsyncLocalStorage из node:async_hooks. Middleware берёт id из x-request-id или генерирует UUID и вызывает als.run({ reqId }, next). Любой код в этой асинхронной цепочке достаёт id через als.getStore(), в том числе после await. Параллельные запросы не путаются, потому что контекст привязан к цепочке, а не к глобальной переменной. Логгер подставляет id через mixin, в Nest есть nestjs-cls и nestjs-pino

Почему console.log плохо подходит для прод-логов?

Он пишет текст, а не структуру, и в системе логов не поискать по reqId. Уровней нет, debug не выключить без правки кода. Запись в stdout в файл или терминал синхронная и под нагрузкой блокирует цикл событий. Скрывать секреты он не умеет. pino пишет JSON с уровнем и контекстом, асинхронно и с redact

Что вернёт Node на SIGTERM, если обработчика нет, и что изменится, если он есть?

Без обработчика Node выходит с кодом 128 + номер сигнала, для SIGTERM это 143. С обработчиком поведение по умолчанию снимается, и процесс сам не выйдет. Забыл process.exit или не закрыл сервер и пул — сервис живёт до SIGKILL. Поэтому в обработчике всегда есть путь к выходу и таймаут

📚 Что почитать