Многостадийные сборки: жирный билдер, тонкий runtime и как COPY --from схлопывает 1.2 ГБ в 28 МБ

Две задачи, две стадии

Спроси себя: нужен ли работающему контейнеру компилятор, которым он был собран? Почти никогда — но одностадийные сборки шлют обе среды в одних слоях. Одностадийная сборка смешивает две разные файловые системы: ту, что нужна чтобы собрать артефакт (компиляторы, пакетные менеджеры, заголовки, исходники, кеши модулей), и ту, что нужна чтобы запустить его (бинарь плюс его реальные runtime-зависимости). Многостадийность их разделяет. Вы пишете несколько стадий FROM в одном Dockerfile; последняя — образ, который вы шлёте, а ранние стадии существуют лишь чтобы произвести входы, которые финальная стадия копирует.

# syntax=docker/dockerfile:1
FROM golang:1.23 AS build           # ~840 МБ: компилятор, git, кеш модулей
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

FROM gcr.io/distroless/static:nonroot AS runtime   # база ~2 МБ
COPY --from=build /app /app          # копируем ТОЛЬКО бинарь
USER nonroot
ENTRYPOINT ["/app"]

COPY --from=build /app /app — это шарнир. Он заходит в финальную ФС стадии build и копирует лишь /app в runtime-стадию. Компилятор, 400-МБ кеш модулей, дерево исходников, git — ничто не пересекает границу. Поставляемый образ — это distroless-база плюс один слой бинаря на 18 МБ: 28 МБ всего, против 1.2-ГБ одностадийного. Тот же бинарь, в 40 раз меньше, и весь тулчейн сборки — каждый CVE-несущий dev-пакет — просто отсутствует в слоях, которые тянет клиент.

Собирается только целевая стадия (и её зависимости)

Второе свойство, которое упускают: docker build собирает финальную целевую стадию и только стадии, от которых она транзитивно зависит. Неиспользуемые стадии вырезаются из графа LLB и не выполняются. Так что можно держать стадию test и стадию lint в том же Dockerfile, а обычный docker build (с целью runtime-стадии) пропустит их полностью, если только что-то не сделает COPY --from их выхода. Можно также собрать конкретную стадию через --target build, чтобы получить debug-образ с полным тулчейном, или --target test в CI, чтобы прогнать тесты внутри графа. Один Dockerfile, несколько выходов, и прод-сборка не платит ни за одну стадию, которую не ссылает.

Ловушка кеша при COPY из стадии

Многостадийность взаимодействует с кешированием так, что кусает людей. Вершина COPY --from=build /app runtime-стадии ключуется на дайджесте /app, как его произвела стадия build. Так что если компиляция в стадии build — попадание в кеш и даёт идентичный бинарь, то COPY --from тоже попадает, и runtime-слой переиспользуется. Но если сборка недетерминирована — встраивает таймстамп, случайный build ID, или Go-сборка варьируется — дайджест /app меняется каждую сборку, COPY --from промахивается всегда, и вы пушите новый runtime-слой в реестр каждый раз, даже когда ничего значимого не менялось. Та же контентная адресация, что делает кеш рабочим, делает невоспроизводимые сборки дорогими: воспроизводимая компиляция даёт финальному слою стабильное попадание — ровно об этом следующий урок о воспроизводимых сборках. Дисциплина: упорядочьте стадию build как любую другую (manifest до исходников) и держите артефакт детерминированным, чтобы межстадийное копирование могло кешироваться.