Зачем вообще переписывать 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.
Выбор базового образа и фиксация версий
Критерии выбора для продакшна: официальный образ и поддерживаемый тег, размер, совместимость бинарников, наличие утилит для проверки здоровья, наличие процесса обновлений безопасности.
| Базовый образ | Что внутри | Плюсы | Ограничения |
|---|---|---|---|
| alpine | musl libc, пакетный менеджер apk | маленький размер, быстрая загрузка | другая libc: готовые бинарники под glibc могут не запуститься или потребуют пакета совместимости |
| debian slim | glibc, 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 с реальной конфигурацией и нагрузкой остаётся обязательным шагом перед выкаткой в продакшн.