Dockerfile для продакшна: паттерны сборки, кэш слоёв и безопасный запуск | AdminWiki

Dockerfile для продакшна: паттерны сборки, кэш слоёв и безопасный запуск

18 ноября 2026 13 мин. чтения

Зачем вообще переписывать Dockerfile перед продакшном

Один и тот же сервис упаковывается в образ двумя способами. В первом внутри лежат компилятор, исходники, dev-зависимости и кэш пакетного менеджера. Во втором остаются артефакт сборки, рантайм и пользователь без прав root. Разница видна на каждом деплое: в скорости выкатки, в объёме registry и в том, что получит атакующий при компрометации процесса.

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

Порядок разбора:

  • multi-stage сборка и граница между builder и runtime;
  • порядок инструкций и работа кэша слоёв;
  • выбор базового образа и фиксация версий;
  • контекст сборки и .dockerignore;
  • запуск от non-root и HEALTHCHECK;
  • антипаттерны с заменой каждого;
  • проверка размера, слоёв и метаданных через docker history и docker image inspect;
  • чек-лист перед деплоем.

Тонкости синтаксиса docker build и разбор флагов -t, -f, --build-arg, --no-cache вынесены в отдельный материал по команде docker build и её ключевым параметрам.

Multi-stage сборка: как оставить в образе только рантайм

Идея простая: сборка и запуск живут в разных стадиях одного Dockerfile. В стадии builder стоят компиляторы, заголовочные файлы и dev-зависимости, в стадии runtime копируется только результат. Инструкция COPY --from=builder забирает файлы из промежуточной стадии, всё остальное в финальный образ не попадает.

Для интерпретируемых языков приём тоже работает: зависимости ставятся в отдельной стадии, а в финальную копируется уже готовый набор пакетов или собранный артефакт. Разбор шаблонов для Python, Node.js и Go с graceful shutdown есть в материале про безопасные образы и многоэтапную сборку.

Шаблон multi-stage Dockerfile

Каркас ниже универсален. Угловые скобки замените на актуальные теги и пути для своего стека.

# стадия сборки
FROM <базовый-образ-с-компилятором>:<версия> AS builder
WORKDIR /src
COPY <файл-манифеста-зависимостей> ./
RUN <установка-зависимостей>
COPY . .
RUN <команда-сборки>

# стадия рантайма
FROM <минимальный-базовый-образ>:<версия> AS runtime
WORKDIR /app
COPY --from=builder /src/<путь-к-артефакту> /app/
USER <пользователь>
EXPOSE <порт>
HEALTHCHECK --interval=30s --timeout=3s --start-period=15s --retries=3 \
  CMD <команда-проверки>
ENTRYPOINT ["<исполняемый-файл>"]

Почему так, по строкам:

  • AS builder и AS runtime дают стадиям имена, чтобы ссылаться на них в COPY --from.
  • WORKDIR задаёт каталог для последующих инструкций и создаёт его при отсутствии.
  • COPY манифеста зависимостей отдельным шагом нужен для кэша, об этом ниже.
  • USER до ENTRYPOINT переключает процесс на непривилегированного пользователя.
  • ENTRYPOINT в exec-форме (JSON-массив) запускает процесс как PID 1 напрямую, без промежуточного shell. Тогда SIGTERM от docker stop доходит до приложения, и оно успевает корректно завершиться.

Shell-форма (ENTRYPOINT команда аргумент) оборачивает запуск в /bin/sh -c. Сигналы в этом случае часто достаются shell, а не приложению, и контейнер приходится добивать по таймауту.

Что остаётся в builder-стадии и почему это важно

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

Поверхность атаки сокращается механически: меньше бинарников и утилит внутри контейнера, меньше чем можно воспользоваться после эксплойта. Компилятор, git и curl, оставленные в рантайм-образе «на всякий случай», эту работу делают за атакующего.

Multi-stage не заменяет .dockerignore и не отменяет фиксацию версий. Контекст сборки всё равно отправляется в демон, а тег без версии всё равно даст разный образ в разное время.

Порядок слоёв и кэширование: почему сборки становятся медленными

Каждая инструкция Dockerfile создаёт слой. Docker переиспользует слой из кэша, пока не изменилась сама инструкция и её входные данные. Изменение раннего слоя инвалидирует все последующие, и они собираются заново.

Отсюда правило: сначала редко меняющееся (базовый образ, системные пакеты, манифесты зависимостей), потом часто меняющееся (исходный код). Нарушение порядка даёт знакомый эффект: поправили одну строку в обработчике, а сборка заново скачала и поставила все зависимости.

Механика слоёв и инвалидации кэша подробно разобрана в статье про кэширование слоёв в Dockerfile.

Правильный порядок инструкций на примере

Плохой порядок: сначала копируется весь проект, потом ставятся зависимости.

COPY . .
RUN <установка-зависимостей>
RUN <команда-сборки>

Любая правка в исходниках меняет входные данные COPY . ., слой инвалидируется, и установка зависимостей выполняется заново.

Хороший порядок: сначала только манифест зависимостей, затем установка, затем остальной код.

COPY <файл-манифеста-зависимостей> ./
RUN <установка-зависимостей>
COPY . .
RUN <команда-сборки>

Файл манифеста зависит от стека: package.json и lock-файл для Node.js, requirements.txt или pyproject.toml для Python, go.mod и go.sum для Go. Меняется он редко, поэтому слой с установкой зависимостей остаётся в кэше при правках кода.

Как проверить, что кэш работает

Соберите образ дважды подряд без изменений в проекте:

docker build -t <образ>:<тег> .
docker build -t <образ>:<тег> .

Во второй сборке шаги установки зависимостей и копирования манифеста помечаются CACHED, пересобираются только слои после изменённого файла. Тайминги зависят от окружения, ориентируйтесь на метки CACHED, а не на секунды.

Если нужно убедиться, что образ собирается с нуля (например, перед релизом), используйте docker build --no-cache. Этот флаг отключает кэш для всех шагов, поэтому сборка будет дольше.

Для пакетных менеджеров существует BuildKit cache mount: постоянный кэш, который используется во время сборки и накапливается между сборками. При пересборке слоя скачиваются только новые или изменённые пакеты, а неизменённые берутся из cache mount. Подключается он флагом --mount у инструкции RUN; синтаксис зависит от версии frontend, поэтому сверяйтесь с документацией Docker по оптимизации кэша сборки, прежде чем переносить приём в CI.

Выбор базового образа и фиксация версий

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

Базовый образЧто внутриПлюсыОграничения
alpinemusl libc, пакетный менеджер apkмаленький размер, быстрая загрузкадругая libc: готовые бинарники под glibc могут не запуститься или потребуют пакета совместимости
debian slimglibc, aptпривычная совместимость, есть shell и утилитыбольше размер, больше пакетов внутри
distrolessтолько рантайм и приложение, без shell и пакетного менеджераминимальная поверхность атакисложнее отладка, проверку здоровья обычно выносят в оркестратор
scratchпустой слойминимально возможный образподходит только для статически слинкованных бинарников, нет ничего для диагностики

Тег, версия или digest: что фиксировать

latest плавающий: под тем же именем в разное время приходит разный образ, и сборка перестаёт быть воспроизводимой. Версионный тег предсказуемее, но в некоторых registry теги перезаписываемы, поэтому гарантии иммутабельности без проверки политики registry нет.

Digest вида образ@sha256:... фиксирует точные байты образа. Это максимальная воспроизводимость и одновременно обязательство: обновления безопасности сами не приедут, нужен процесс регулярного обновления digest в Dockerfile.

Практическое правило: версионный тег как минимум, digest там, где важна строгая воспроизводимость сборки между средами и машинами.

Контекст сборки и .dockerignore

docker build отправляет в демон весь контекст сборки, то есть каталог, указанный в конце команды. Файл .dockerignore вычитает из него лишнее: уменьшает объём передачи и страхует от случайного COPY . ., который затащит в образ мусор.

Минимальный набор для .dockerignore:

  • .git и служебные каталоги IDE;
  • node_modules и другие локально установленные зависимости;
  • .env и файлы с локальными секретами;
  • логи, дампы, локальные артефакты сборки;
  • docker-compose файлы и локальные скрипты, не нужные в образе.

.dockerignore работает как страховка, а не как замена аккуратному COPY. Надёжнее копировать конкретные пути вместо всего каталога. Разницу между COPY и ADD, в том числе поведение --chown и влияние на кэш, разбираем в материале про COPY и ADD в Dockerfile.

Проверить, что в контекст не попадает лишнее, можно сборкой с docker build --progress=plain . и просмотром вывода, либо явным перечислением путей в COPY.

Запуск от непривилегированного пользователя

По умолчанию процесс в контейнере работает от root. Компрометация приложения в этом случае даёт root внутри контейнера, а вместе с ним и лишние возможности при выходе за его пределы.

FROM <базовый-образ>:<версия> AS runtime
WORKDIR /app

# Debian/Ubuntu: для Alpine используются addgroup/adduser
RUN groupadd --gid 10001 app \
    && useradd --uid 10001 --gid app --create-home app

COPY --from=builder --chown=app:app /src/<артефакт> /app/

USER app
ENTRYPOINT ["<исполняемый-файл>"]

Порядок важен: пользователь создаётся и владелец файлов меняется до USER. Если сменить пользователя раньше, chown и установка пакетов внутри образа упадут по правам. Флаг --chown у COPY удобнее отдельного RUN chown -R: он не создаёт дополнительный слой.

Некоторые базовые образы, включая варианты distroless, уже содержат пользователя nonroot. Уточняйте его имя и uid в документации конкретного образа, иначе USER с несуществующим пользователем даст ошибку запуска.

Проверка:

docker run --rm <образ> id

Ожидаемый результат: uid, отличный от 0. Если вывод содержит uid=0(root), переключение не сработало.

Что даёт такой запуск в общей модели защиты, разбираем в статье про цели аудита безопасности Docker. Флаги --privileged и отключение защитных механизмов к этой задаче отношения не имеют: они расширяют права, а не сужают.

HEALTHCHECK: как дать Docker и оркестратору понять, что сервис жив

Инструкция HEALTHCHECK задаёт команду, которую демон периодически выполняет внутри контейнера. Ненулевой код возврата переводит контейнер в статус unhealthy. В одном Dockerfile может быть только одна инструкция HEALTHCHECK — это зафиксировано в справочнике по Dockerfile.

HEALTHCHECK --interval=30s --timeout=3s --start-period=15s --retries=3 \
  CMD curl -fsS http://127.0.0.1:<порт>/<путь-проверки> || exit 1

Параметры: --interval задаёт период между проверками, --timeout ограничивает время одной проверки, --retries определяет число подряд неудачных попыток до перевода в unhealthy, --start-period даёт приложению время на старт, в течение которого неудачи не считаются. Значения в примере выше — рабочий ориентир, а не жёсткий стандарт: подбирайте их под время старта и отклик своего сервиса. Отдельно есть опция --start-interval: она задаёт время между проверками в течение start period и требует Docker Engine версии 25.0 или новее.

Команда проверки должна существовать внутри образа. В slim-образах curl может отсутствовать, в Alpine есть wget, в distroless нет ни того, ни другого. Варианты два: поставить утилиту в рантайм-образ осознанно или перенести проверку на уровень оркестратора.

Kubernetes не опирается на HEALTHCHECK из Dockerfile: состояние контейнеров он отслеживает собственными пробами, которые выполняет kubelet. Liveness-проба нужна, чтобы обнаружить зависший процесс и перезапустить контейнер, readiness-проба определяет готовность принимать трафик, startup-проба отмечает момент, когда приложение запустилось. Это описано в документации Kubernetes по liveness, readiness и startup пробам. В такой связке HEALTHCHECK полезен для локального запуска и для сред, где контейнером управляет сам Docker, а в кластере проверки задаются в манифесте Pod.

Проверка статуса:

docker ps
docker inspect --format '{{.State.Health.Status}}' <контейнер>

В колонке STATUS у docker ps появится пометка (healthy) или (unhealthy). Вторая команда вернёт значение starting, healthy или unhealthy.

Антипаттерны: что чаще всего ломает продакшн-образ

АнтипаттернРискКак правильно
apt-get update отдельной инструкциейв слое фиксируется устаревший индекс пакетов, установка может упасть или поставить старую версию из кэшаupdate и install в одном RUN с очисткой /var/lib/apt/lists/*
установка без --no-install-recommendsприезжают рекомендованные пакеты, которых никто не просилставить только нужные пакеты с этим флагом
COPY .env или ключей в образсекрет остаётся в слое и в registryсекреты в рантайме через переменные окружения или secrets оркестратора
запуск от rootкомпрометация процесса даёт root в контейнереUSER с непривилегированным пользователем
тег latestсборки невоспроизводимы, откат неочевиденверсионный тег или digest
COPY . . без .dockerignoreв образ попадают .git, локальные зависимости, логи.dockerignore плюс копирование конкретных путей
dev-зависимости в финальном образелишний размер и уязвимостиразделить стадии builder и runtime

apt-get без очистки кэша и другие ошибки установки пакетов

Правильный паттерн для Debian и Ubuntu: одна инструкция RUN, внутри обновление индекса, установка и удаление списков пакетов.

RUN apt-get update \
    && apt-get install -y --no-install-recommends <пакет1> <пакет2> \
    && rm -rf /var/lib/apt/lists/*

Если разделить update и install на два RUN, индекс скачивается в одном слое и остаётся там навсегда. При следующей пересборке этот слой берётся из кэша, индекс оказывается устаревшим, и install либо падает, либо ставит устаревшую версию пакета из кэша. Поэтому update и install идут вместе — это и есть cache busting: изменение списка пакетов меняет инструкцию и заставляет индекс обновиться. Такой подход описан в рекомендациях Docker по сборке образов. Списки удаляются в том же RUN: очистка в следующем слое размер не уменьшает, файлы остаются в предыдущем.

Для Alpine используется свой синтаксис: RUN apk add --no-cache <пакет>. Флаг --no-cache не даёт индексу осесть в слое.

Секреты в образе: .env, токены, ключи

Секреты нужно держать вне слоёв образа и внедрять во время выполнения. Удаление файла следующей инструкцией не делает образ безопасным: содержимое остаётся в предыдущем слое, а значит, доступно тому, кто получит образ из registry.

Рабочие варианты: передавать секреты в рантайме переменными окружения или secrets оркестратора, а на этапе сборки использовать BuildKit secrets. Mount типа secret даёт сборочному контейнеру доступ к токенам или приватным ключам, не запекая их в образ — это описано в справочнике BuildKit по Dockerfile. Синтаксис зависит от версии BuildKit, проверяйте его в документации своей версии Docker. И .env обязательно добавляется в .dockerignore.

Проверка истории на подозрительные копирования:

docker history --no-trunc <образ>

Флаг --no-trunc показывает полный текст команд, без него длинные строки обрезаны. В примерах и конфигах используйте заглушки вида <токен>, реальные значения в репозиторий не попадают.

Проверка результата: размер, слои и метаданные образа

Набор команд для аудита собранного образа:

docker images <образ>
docker history --no-trunc <образ>
docker image inspect <образ> --format '{{.Config.User}}'
docker image inspect <образ> --format '{{json .Config.Healthcheck}}'
docker image inspect <образ> --format '{{len .RootFS.Layers}}'
docker run --rm <образ> id

docker images показывает колонки REPOSITORY, TAG, идентификатор образа, CREATED и SIZE. Размер здесь грубый ориентир: общие базовые слои хранятся один раз, а в выводе учитываются целиком.

Для non-root ожидается uid, отличный от 0. Для HEALTHCHECK ожидается непустой JSON с командой и параметрами, иначе инструкция не попала в образ.

docker history и docker image inspect: что смотреть

В docker history колонки IMAGE, CREATED, CREATED BY, SIZE и COMMENT. Смотрите на два признака: слои с заметно большим SIZE и команды, копирующие лишнее (например, COPY . . без ограничений). Крупный слой в начале цепочки, скорее всего, базовый образ, крупный слой в конце почти всегда ваши файлы.

docker history показывает слои, а не итоговый размер на диске: часть слоёв общая с другими образами и физически не дублируется.

В docker image inspect полезны конкретные поля. Config.User показывает пользователя запуска, пустое значение означает root. Config.Healthcheck подтверждает наличие проверки и её параметры. Config.Env проверяется на секреты: токенов и паролей там быть не должно. RootFS.Layers даёт число слоёв, и десятки слоёв на простое приложение повод разобрать Dockerfile.

Значения в выводе зависят от образа, ориентируйтесь на структуру полей и на отсутствие неожиданных данных, а не на конкретные цифры из примеров.

Чек-лист перед деплоем

  • Базовый образ зафиксирован: версионный тег или digest, не latest.
  • Multi-stage: в финальной стадии только артефакт и рантайм, без компилятора и dev-зависимостей.
  • Порядок слоёв: манифест зависимостей и их установка до копирования исходников.
  • Повторная сборка даёт CACHED на шаге установки зависимостей.
  • .dockerignore содержит .git, .env, локальные зависимости и логи.
  • USER задан до ENTRYPOINT, docker run --rm <образ> id показывает не 0.
  • HEALTHCHECK задан в образе или осознанно перенесён на probes оркестратора.
  • Системные пакеты ставятся одним RUN с --no-install-recommends и очисткой кэша.
  • docker history --no-trunc не показывает копирования секретов и лишних каталогов.
  • ENTRYPOINT в exec-форме, процесс получает SIGTERM и завершается корректно.
  • Размер и число слоёв проверены, крупные слои объяснимы.

Чек-лист проверяет Dockerfile, а не работу сервиса. Прогон в staging с реальной конфигурацией и нагрузкой остаётся обязательным шагом перед выкаткой в продакшн.

Поделиться: