Слои образа и кэш сборки: порядок решает всё

Однострочная правка CSS запускает четырёхминутную CI-сборку. Каждый пуш — то же самое: npm install бежит с нуля, тянет 1200 пакетов по сети, хотя package.json не менялся. Кто-то написал COPY . . перед RUN npm install, поэтому правка любого файла инвалидирует слой установки. Команда платила ~3 минуты за пуш месяцами — кэш, который ни разу не попадал, потому что Dockerfile задавал ему неправильный вопрос первым.

Слой — это diff, а ключ кэша — содержимое

Docker-образ — это не один blob. Это стек read-only слоёв, показанный через union-файловую систему (overlay2 на Linux): запущенный контейнер видит одно слитое дерево, но хранилище — цепочка diff’ов. Каждый RUN, COPY и ADD в Dockerfile порождает один слой — изменения файловой системы, которые сделал этот шаг, и не более.

Кэш сборки ключует каждый слой по двум вещам: по самой строке инструкции и по содержимому, от которого она зависит. Для COPY и ADD Docker считает чек-сумму копируемых файлов; меняется байт — меняется чек-сумма, и кэш промахивается. Для RUN ключ кэша — это буквальный текст команды; Docker не смотрит, что команда реально делает, — отдельная ловушка (ниже). Правило беспощадно: в тот момент, когда ключ одного слоя меняется, этот слой и каждый слой после него пересобираются. Кэш — это совпадение по префиксу. Ты держишь его только до первого промаха.

Этот единственный факт двигает каждую оптимизацию в уроке. Твоя задача как автора Dockerfile — расставить инструкции так, чтобы шаги, которые редко меняются, шли в начале (глубоко в префиксе кэша), а шаги, которые меняются на каждый коммит — твой исходный код — шли в конце.

Кардинальное правило: от редко- к часто-меняющимся

Вот баг из хука и его фикс.

В хорошем порядке COPY package.json package-lock.json ./ меняет свою чек-сумму, только когда меняется манифест зависимостей. Правишь компонент — шаги 1 и 2 остаются в кэше; пересобирается лишь финальный COPY . . и то, что следует. Это самое высокорычажное изменение, которое ты можешь внести в Dockerfile: команды регулярно сообщают о падении времени CI-сборки на 70% от одного только кэширования слоёв, потому что многоминутная установка зависимостей превращается в попадание в кэш за доли секунды на подавляющем большинстве коммитов.

Тот же принцип обобщается. Пинни базовый образ и ставь OS-пакеты рано; они меняются максимум раз в месяц. Дальше копируй lock-файлы и ставь зависимости. Исходники и сборку — последними. Градиент частоты — редко-меняющееся внизу, каждый-коммит наверху — это вся игра.

Multi-stage: компилируй жирно, отгружай тонко

Твоему тулчейну сборки — компиляторам, dev-зависимостям, node_modules, набитому build-time пакетами, кэшам apt — нечего делать в образе, который ты гоняешь в проде. Он раздувает образ, расширяет поверхность атаки и замедляет каждый pull и деплой. Multi-stage сборки решают это: ты пишешь несколько FROM-стейджей в одном Dockerfile, делаешь тяжёлую работу в жирном builder-стейдже, потом через COPY --from=builder переносишь только готовые артефакты в тонкий runtime-стейдж. Опубликованным образом становится только последний стейдж; builder отбрасывается.

# syntax=docker/dockerfile:1
FROM node:22 AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM gcr.io/distroless/nodejs22-debian12
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["dist/server.js"]

Числа драматичны. Single-stage Node-сборка обычно весит около 380MB+ (полная база node:22 — ~1.1GB до твоего приложения); multi-stage версия на slim- или distroless-базе падает примерно до 60MB. Для Go-бинарника контраст резче — single-stage сборка около 180MB схлопывается до образа ~3–12MB на scratch или distroless/static, потому что скомпилированному бинарнику вообще не нужен runtime. Один широко цитируемый пример ужал образ с 843MB до 12.1MB — сокращение на 98.6%.

Distroless vs alpine: трейдофф runtime-базы

Когда у тебя есть тонкий runtime-стейдж, выбор базы — реальное решение. Alpine крошечный, потому что использует musl libc и BusyBox, и поставляет пакетный менеджер — удобно, когда надо добавить инструмент. Подвох: musl отличается от glibc достаточно тонко, чтобы ломать нативные модули и иногда удивлять DNS или производительностью. Distroless поставляет только твоё приложение и его прямые runtime-зависимости — ни шелла, ни пакетного менеджера, ни apt — что отлично для поверхности атаки, но означает, что ты не можешь docker exec шелл внутрь для отладки, и обязан занести каждую runtime-зависимость через COPY.

.dockerignore и секрет, который никогда не умирает

Картину завершают два провала. Первый — build-контекст: когда ты запускаешь docker build ., вся директория упаковывается в tar и шлётся демону. Без .dockerignore туда попадают .git, node_modules, вывод сборки и .env-файлы — замедляя загрузку и рискуя тем, что COPY . . сгребёт секреты и мусор в слой. .dockerignore, перечисляющий node_modules, .git, *.log и .env, держит контекст лёгким, а копирование — чистым.

Второй — ловушка, которая бьёт команды сильнее всего: секрет, добавленный в одном слое и удалённый в более позднем, всё равно живёт в истории образа. Слои — это неизменяемые diff’ы. Если ты COPY id_rsa (или впишешь токен в файл), а потом RUN rm id_rsa через две строки, удаление — это просто новый diff сверху; исходный файл всё ещё восстановим из раннего слоя через docker history или извлечением образа. Удаление — театр. Правильные инструменты — BuildKit secret mounts: RUN --mount=type=secret,id=token ... делает секрет доступным для одной инструкции и пишет его в ноль слоёв, — или, если иначе никак, multi-stage сборка, где секрет живёт только в отбрасываемом builder-стейдже. Никогда не делай rm секрета в надежде, что он исчез.