Многоэтапный Multi-Stage Dockerfile: слои кэширования pnpm, non-root юзер и Distroless

Архитектурная база#

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

Технология Multi-Stage Build (многоэтапная сборка) кардинально меняет эту парадигму. Она разделяет жизненный цикл контейнера на четыре строго детерминированные стадии:

1. base: общая базовая конфигурация операционной системы, установка стабильной версии Node.js и глобальная инициализация пакетного менеджера pnpm.
2. deps: выделенный слой для установки внешних модулей. Исходный код проекта сюда намеренно не копируется, чтобы слой кэшировался Docker демоном до тех пор, пока не изменится pnpm-lock.yaml.
3. builder: сборочный контекст, где запускается компиляция pnpm build. На этом этапе генерируется изолированный артефакт output: 'standalone' и компилируется клиентская статика.
4. runner: финальный минималистичный контейнер, содержащий исключительно среду исполнения Node.js, непривилегированного пользователя и скомпилированные артефакты. Все сборочные цепочки и свыше 90% зависимостей физически исчезают из итогового образа.

[Multi-Stage Конвейер сборки]

  ┌───────────────┐
  │  Stage: base  │ ──► node:22-alpine / glibc-compat / pnpm setup
  └───────┬───────┘
          │
          ├──────────────────────────────────┐
          ▼                                  ▼
  ┌───────────────┐                  ┌───────────────┐
  │  Stage: deps  │                  │ Stage: runner │
  │               │                  │               │
  │ • package.json│                  │ • non-root    │
  │ • lockfile    │                  │   nextjs:1001 │
  │ • pnpm cache  │                  │ • Distroless  │
  └───────┬───────┘                  │   или Alpine  │
          │ node_modules             └───────▲───────┘
          ▼                                  │
  ┌───────────────┐                          │ Копирование
  │Stage: builder │                          │ артефактов
  │               │                          │
  │ • Исходники   │                          │
  │ • pnpm build  │ ─────────────────────────┘
  │ • standalone  │ ──► .next/standalone + static + public
  └───────────────┘

В сочетании с подсистемой Docker BuildKit многоэтапные сборки открывают доступ к технологии Cache Mounts (--mount=type=cache). Она позволяет монтировать глобальный кэш пакетов pnpm store напрямую с хост-машины или CI-раннера без его сохранения в постоянных слоях контейнера, ускоряя повторные сборки в CI/CD в 5–10 раз.

Ментальная модель#

Ментальная модель высокоэффективного контейнера строится вокруг принципа наименьших привилегий (Principle of Least Privilege) и минимизации поверхности атаки (Attack Surface Reduction).

Контейнер не является виртуальной машиной — это изолированный процесс на хостовом ядре Linux, ограниченный механизмами cgroups и namespaces. Если внутри контейнера процесс запущен под пользователем root (UID 0), любая уязвимость выхода за пределы контейнера (Container Breakout) или опасное монтирование томов (-v /var/run/docker.sock) дает злоумышленнику абсолютные root-права над физическим сервером.

Для обеспечения бескомпромиссной безопасности в рантайме применяются две технологии:

1. Непривилегированный пользователь (Non-root user): принудительное создание пользователя с фиксированными UID=1001 и GID=1001 (nextjs:nodejs), лишенного прав доступа к системным конфигурациям ОС и возможности повышать привилегии (no-new-privileges).
2. Контейнеры Distroless: специализированные образы от Google (gcr.io/distroless/nodejs22), содержащие исключительно бинарный файл рантайма Node.js и критически важные системные библиотеки (glibc, libssl). В образе Distroless полностью отсутствуют:
   • Командные интерпретаторы (/bin/sh, /bin/bash).
   • Системные менеджеры пакетов (apt, apk).
   • Утилиты для работы с сетью (curl, wget, nc).

[Сравнение структуры традиционного образа и Distroless]

Традиционный образ (node:22 / Ubuntu / Alpine):
┌─────────────────────────────────────────────────────────────┐
│ Приложение (server.js, node_modules)                        │
├─────────────────────────────────────────────────────────────┤
│ Node.js Runtime (V8, libuv)                                 │
├─────────────────────────────────────────────────────────────┤
│ Системные утилиты: sh, bash, apk, curl, tar, find, coreutils│ ◄── Вектор для RCE
├─────────────────────────────────────────────────────────────┤
│ Системные библиотеки: glibc/musl, libcrypto, ca-certs       │
└─────────────────────────────────────────────────────────────┘

Образ Distroless (gcr.io/distroless/nodejs22):
┌─────────────────────────────────────────────────────────────┐
│ Приложение (server.js, node_modules)                        │
├─────────────────────────────────────────────────────────────┤
│ Node.js Runtime (V8, libuv)                                 │
├─────────────────────────────────────────────────────────────┤
│ Системные библиотеки: glibc, libssl, ca-certificates        │
└─────────────────────────────────────────────────────────────┘
  (Командные оболочки и бинарники ОС физически удалены)

При попытке эксплуатации уязвимости типа Remote Code Execution (RCE) через инъекцию команд операционной системы атака мгновенно терпит неудачу: ядро Linux возвращает ошибку exec: "sh": executable file not found in $PATH.

• BuildKit Cache Mount (--mount=type=cache)
• Distroless Image
• UID/GID Mapping

На практике применяется#

1. Финтех и платежные шлюзы (PCI-DSS & SOC2 Compliance)#

Аудит безопасности по стандартам PCI-DSS запрещает присутствие компиляторов (GCC, Python, Make) и менеджеров пакетов в продакшен-среде. Использование Distroless в связке с non-root пользователем сводит отчеты сканеров Trivy к нулю открытых уязвимостей (0 Critical, 0 High), гарантируя прохождение автоматических проверок безопасности перед деплоем.

2. Масштабируемые e-commerce платформы с частыми релизами#

В условиях, когда команда инженеров делает по 40–60 релизов в день, BuildKit Cache Mounts сокращает время выполнения этапа pnpm install с 2.5 минут до 4 секунд. Кэш пакетов сохраняется на сборочном раннере и инвалидируется только при реальном обновлении хеша в pnpm-lock.yaml.

3. Edge-ноды и распределенные микро-серверы с лимитом дискового пространства#

При развертывании Next.js на граничных шлюзах с лимитированным объемом SSD сжатие финального образа до 70–90 МБ снижает нагрузку на дисковую подсистему и минимизирует сетевой оверхед при раздаче слоев через корпоративный Docker Registry.

Как это работает#

Для реализации максимальной скорости сборки и надежной защиты сборочный конвейер проектируется по строгому стандарту:

1. Архитектура эффективного кэширования pnpm в BuildKit#

Менеджер пакетов pnpm хранит все файлы зависимостей в едином дедуплицированном контентно-адресуемом хранилище (store-dir). Чтобы использовать это преимущество внутри Docker, необходимо:

1. Задать переменную окружения PNPM_HOME="/pnpm".
2. Настроить монтирование кэша --mount=type=cache,id=pnpm,target=/pnpm/store.
3. Указать pnpm config set store-dir /pnpm/store.

При таком подходе при сборке новых коммитов скачиваются только изменившиеся пакеты, а не все дерево заново.

# syntax=docker/dockerfile:1.7

# ==============================================================================
# 1. СТАДИЯ: BASE
# Единый базовый слой ОС, настройка переменных окружения и пакетного менеджера
# ==============================================================================
FROM node:22-alpine AS base

# Настройка системного окружения Node.js и pnpm
ENV NODE_ENV=production \
    PNPM_HOME="/pnpm" \
    PATH="$PNPM_HOME:$PATH" \
    COREPACK_ENABLE_DOWNLOAD_PROMPT=0

WORKDIR /app

# Установка libc6-compat для корректной компиляции нативных аддонов (Sharp, SWC)
RUN apk add --no-cache libc6-compat && \
    corepack enable pnpm

# ==============================================================================
# 2. СТАДИЯ: DEPS
# Установка зависимостей с изоляцией от исходного кода и монтированием кэша
# ==============================================================================
FROM base AS deps
WORKDIR /app

# Копируем ИСКЛЮЧИТЕЛЬНО манифесты пакетов для сохранения кэша слоя
COPY package.json pnpm-lock.yaml* ./

# Монтируем постоянный кэш хоста в хранилище pnpm store.
# Кэш не попадает в итоговый образ, но сохраняется между сборками!
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
    pnpm config set store-dir /pnpm/store && \
    pnpm install --frozen-lockfile --prod=false

# ==============================================================================
# 3. СТАДИЯ: BUILDER
# Компиляция Next.js приложения и генерация standalone-среза
# ==============================================================================
FROM base AS builder
WORKDIR /app

# Копируем установленные модули из стадии deps
COPY --from=deps /app/node_modules ./node_modules
# Копируем исходный код приложения
COPY . .

# Переменные сборки: отключаем сбор телеметрии Next.js
ENV NEXT_TELEMETRY_DISABLED=1 \
    NODE_ENV=production

# Монтируем кэш компилятора .next/cache для инкрементальной пересборки в CI
RUN --mount=type=cache,id=nextcache,target=/app/.next/cache \
    pnpm build

# ==============================================================================
# 4. СТАДИЯ: RUNNER (Вариант A: Защищенный Alpine Linux)
# Минимальный рантайм, non-root пользователь и копирование артефактов
# ==============================================================================
FROM node:22-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production \
    PORT=3000 \
    HOSTNAME="0.0.0.0" \
    NEXT_TELEMETRY_DISABLED=1

# Создание системной группы и пользователя с фиксированными UID/GID 1001
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

# Подготовка директории для инкрементального ISR-кэша с правами для nextjs
RUN mkdir -p .next/cache && \
    chown -R nextjs:nodejs /app

# 1. Копирование публичной статики
COPY --from=builder --chown=nextjs:nodejs /app/public ./public

# 2. Копирование скомпилированного автономного сервера
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./

# 3. Копирование клиентских хэшированных бандлов
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

# Сброс привилегий: переход в контекст непривилегированного пользователя
USER nextjs

EXPOSE 3000

# Запуск изолированного сервера Node.js
CMD ["node", "server.js"]

# ==============================================================================
# АЛЬТЕРНАТИВА: RUNNER DISTROLESS (Максимальная безопасность без шелла)
# Для сборки укажите: docker build --target=runner-distroless -t app:distroless .
# ==============================================================================
FROM gcr.io/distroless/nodejs22-debian12:nonroot AS runner-distroless
WORKDIR /app

ENV NODE_ENV=production \
    PORT=3000 \
    HOSTNAME="0.0.0.0" \
    NEXT_TELEMETRY_DISABLED=1

# В Distroless nonroot пользователь (UID 65532) уже встроен по умолчанию
COPY --from=builder --chown=nonroot:nonroot /app/public ./public
COPY --from=builder --chown=nonroot:nonroot /app/.next/standalone ./
COPY --from=builder --chown=nonroot:nonroot /app/.next/static ./.next/static

USER nonroot
EXPOSE 3000

# В Distroless оболочка /bin/sh отсутствует, точка входа задается строго в exec-форме:
CMD ["server.js"]

Распространённые ошибки#

# ❌ АНТИПАТТЕРН: Копирование всех файлов проекта перед установкой пакетов
COPY . .
RUN pnpm install

# ✅ ПРАВИЛЬНО: Изоляция манифеста пакетов в отдельный кэшируемый слой
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .

# ❌ УЯЗВИМОСТЬ: Процесс исполняется от root
CMD ["node", "server.js"]

# ✅ ПРАВИЛЬНО: Создание системного пользователя и явный переход
RUN addgroup -S -g 1001 nodejs && adduser -S -u 1001 nextjs
USER nextjs
CMD ["node", "server.js"]

# ❌ ОШИБКА: Shell-форма требует /bin/sh
CMD node server.js

# ✅ ПРАВИЛЬНО: Строгая Exec-форма JSON-массива
CMD ["server.js"]

# ❌ ОШИБКА: Папка создана root, у nextjs нет прав на запись кэша
USER nextjs
CMD ["node", "server.js"]

# ✅ ПРАВИЛЬНО: Предварительное создание папки кэша и назначение прав
RUN mkdir -p .next/cache && chown -R nextjs:nodejs /app/.next
USER nextjs
CMD ["node", "server.js"]

Вопросы к собеседованию#