🚀 Конфиг, логи и готовность к проду
Сервис, который отвечает на запросы локально, ещё не готов к проду. Он должен брать конфиг из окружения и падать при старте, если конфиг кривой, писать 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), и запросы в работе обрываются. С обработчиком поведение по умолчанию отключается, и выйти процесс должен сам. Порядок такой:
- Перестать быть ready. Readiness-эндпоинт начинает отвечать 503, балансировщик убирает под из ротации и не шлёт новые запросы
- Вызвать
server.close(). Сервер больше не принимает соединения, а с v19 сразу закрывает простаивающие keep-alive соединения. Запросы в работе дорабатывают, колбэкcloseсработает, когда закроется последнее соединение - Остановить потребление из брокера и дождаться обработки взятых сообщений, остановить фоновые таймеры и кроны
- Закрыть пул базы, соединения с брокером и Redis. Именно в таком порядке: сначала уходят те, кто пишет в базу, потом сама база
- Выйти с кодом 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и никогда не переписывает lockfilenpm 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 0SIGTERM пришёл через 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. Поэтому в обработчике всегда есть путь к выходу и таймаут
📚 Что почитать
- Command-line API:
--env-file— формат файла, порядок нескольких файлов и приоритет окружения - Asynchronous context tracking —
AsyncLocalStorage, почемуrunлучшеenterWith - Pino: Redaction и Asynchronous logging — синтаксис путей, цена wildcard, что теряется при падении
- Docker and Node.js Best Practices — PID 1,
--initи почему неnpm start - Permission Model — флаги, ограничения и почему это не песочница