Контейнеризация Rust: минимальный Dockerfile, зависимости и размер образов без потерь

Контейнеризация Rust кажется простой до первого реального цикла: сборка занимает много времени, образы разрастаются за счёт toolchain и кешей, а попытки «ужать до минимума» иногда приводят к регрессиям (нестабильные бинарники, потеря динамических зависимостей, сломанные runtime-артефакты). В этой статье разберём практический подход к контейнеризации Rust-проектов без излишней сложности инфраструктуры.

Сфокусируемся на четырёх вещах:

• многостадийная сборка (чтобы в финальный образ не попадали компилятор и мусор);
• аккуратная работа с зависимостями Rust (чтобы кэш cargo работал максимально эффективно);
• оптимизация слоёв Docker (чтобы не пересобирать всё при каждом изменении);
• снижение размера без потерь: никаких «танцев» с unsafe, никакого ухудшения совместимости и производительности.

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

Почему Rust-образы часто оказываются большими

Классическая ошибка при упаковке Rust в Docker — собрать внутри «единственного» Docker-образа и затем просто запускать. На практике вы в финальный слой переносите:

• полный Rust toolchain (rustc, cargo, стандартную библиотеку, линковщик);
• зависимости сборки (pkg-config, openssl-dev, clang и т.п.);
• кеш сборки и промежуточные артефакты;
• иногда — исходники и временные файлы.

Для небольшого проекта итоговый образ может легко быть сотни мегабайт, а для проектов со сложными зависимостями — и больше гигабайта. При этом реальный runtime обычно требует только бинарник (и, возможно, несколько динамических библиотек).

Отсюда и ключ: использовать многостадийную сборку и разделить «build environment» и «runtime environment».

Базовая архитектура: multi-stage + разделение сборки и запуска

Мы хотим добиться результата:

1. В первом этапе используем официальный образ Rust, ставим зависимости и компилируем.
2. Во втором этапе берём минимальный базовый образ (scratch или slim) и копируем только бинарник и нужные runtime-зависимости.
3. В идеале слой с cargo registry и build cache должен пересобираться редко.

Сразу оговорим нюанс: статическая сборка (через musl) может сильно упростить runtime-образ (часто вплоть до scratch), но в некоторых случаях возникают проблемы совместимости (например, с определёнными библиотеками или особенностями DNS/SSL). Динамическая сборка с использованием debian slim — более «универсальный» компромисс без усложнения инфраструктуры.

Дальше покажу два рабочих пути: динамический (наиболее предсказуемый) и статический (когда вы готовы следовать требованиям musl).

Минимальный Dockerfile для динамически линкованных бинарников

Предположим, у нас есть стандартный Rust сервис. Основной binary называется myapp. Мы также предполагаем, что он зависит от OpenSSL (или аналогичных системных библиотек) — типичный случай. Если у вас зависимости иные, список системных пакетов адаптируется.

Пример: многостадийная сборка с кэшированием cargo

# syntax=docker/dockerfile:1.7

FROM rust:1.78-bullseye AS builder

WORKDIR /app

# 1) Устанавливаем системные зависимости сборки (по необходимости)
#    Важно: если вам не нужен OpenSSL, уберите эти пакеты.
RUN apt-get update && apt-get install -y --no-install-recommends \
    pkg-config \
    libssl-dev \
    ca-certificates \
 && rm -rf /var/lib/apt/lists/*

# 2) Кэшируем зависимости Rust отдельно от кода.
#    Сначала копируем manifest'ы, чтобы слой с cargo registry
#    не инвалидировался при каждом изменении исходников.
COPY Cargo.toml Cargo.lock ./

# Если есть рабочие пространства (workspace), обычно нужно копировать и подпапки с Cargo.toml:
# COPY crates/*/Cargo.toml crates/*/Cargo.toml
# Тогда cargo сможет резолвить dependency graph заранее.

# Подготавливаем "псевдо-сборку" чтобы скачать зависимости.
# --locked гарантирует консистентность Cargo.lock.
RUN mkdir -p src && echo 'fn main() { }' > src/main.rs \
 && cargo build --release --locked \
 && rm -rf src

# 3) Теперь копируем исходники и собираем финально
COPY . .

# 4) Компилируем релизный бинарник
#    Принято использовать --locked и --release.
#    Если у вас есть feature flags — добавьте их через --features / --no-default-features.
RUN cargo build --release --locked

# 5) Финальный runtime-образ
FROM debian:bullseye-slim AS runtime

# CA для TLS (часто нужно для reqwest/https)
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Важно: путь к бинарнику зависит от проекта.
# Обычно это target/release/<name>.
# Узнать name можно из Cargo.toml (package.name).
COPY --from=builder /app/target/release/myapp /app/myapp

# Если приложение слушает порт — задекларируйте:
EXPOSE 8080

USER 10001:10001

ENTRYPOINT ["/app/myapp"]

Почему этот Dockerfile «не раздувается»

• Cargo.toml/Cargo.lock копируются отдельно: слой с загрузкой зависимостей cargo переиспользуется, если вы меняли только код.
• Сборочный образ builder и runtime образ runtime разделены. В финальный образ попадает только бинарник.
• В runtime образ мы ставим минимум: обычно ca-certificates, если приложение ходит по HTTPS.

Где обычно ошибаются

1. Скопировали весь проект до cargo build
   Тогда каждый чих в исходниках инвалидирует кэш зависимостей, и вы получаете долгие сборки.

2. Игнорировали Cargo.lock
   Без --locked Docker может начинать тянуть другие версии зависимостей, а затем слои становятся нестабильными, и воспроизводимость падает.

3. Сборка под glibc без проверки runtime библиотек
   Если ваша зависимость требует специфические системные .so (например, через openssl-sys), runtime образ должен содержать соответствующие библиотеки. В примере мы ориентировались на OpenSSL через libssl-dev в builder, но в runtime нужна уже runtime-часть (libssl...), которая в Debian base может быть уже установлена транзитивно. Лучше явно проверить бинарник (см. раздел про ldd).

Проверка динамических зависимостей: ldd как страховка от сюрпризов

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

ldd target/release/myapp

Пример типичного вывода (упрощённо):

• libssl.so.3 => /lib/...
• libcrypto.so.3 => /lib/...
• libgcc_s.so.1 => ...

Если вы выбираете debian:bullseye-slim, часть библиотек может не оказаться по умолчанию. Тогда runtime-образ надо дополнить нужными пакетами (например, libssl3).

В Dockerfile это выглядит так:

RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    libssl3 \
 && rm -rf /var/lib/apt/lists/*

Да, это добавляет несколько мегабайт, но это всё равно сильно меньше, чем таскать toolchain.

Оптимизация слоёв: используем BuildKit кеши (опционально, но эффективно)

Даже при правильной структуре Dockerfile cargo может пересобирать больше, чем нужно, потому что кеши могут не сохраняться между сборками (зависит от вашей инфраструктуры CI).

С BuildKit можно подключить кеш директории cargo:

• ~/.cargo/registry
• ~/.cargo/git
• target (иногда аккуратно, чтобы не ломать инкрементальность)

В Dockerfile можно включить mount cache для run-этапов:

# syntax=docker/dockerfile:1.7
FROM rust:1.78-bullseye AS builder
WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    pkg-config libssl-dev ca-certificates \
 && rm -rf /var/lib/apt/lists/*

COPY Cargo.toml Cargo.lock ./

# Скачиваем зависимости с кэшированием cargo
RUN --mount=type=cache,target=/usr/local/cargo/registry \
    --mount=type=cache,target=/usr/local/cargo/git \
    mkdir -p src && echo 'fn main() { }' > src/main.rs \
 && cargo build --release --locked \
 && rm -rf src

COPY . .
RUN --mount=type=cache,target=/usr/local/cargo/registry \
    --mount=type=cache,target=/usr/local/cargo/git \
    cargo build --release --locked

Тут важный нюанс: путь кеша зависит от того, где Cargo хранит registry/git. В официальном образе Rust это часто подхватывает /usr/local/cargo, но лучше проверить фактические пути в вашем окружении.

Если вы в CI используете GitHub Actions/ GitLab, часто есть нативные механизмы кеширования слоёв. Но даже если нет — mount cache в Dockerfile помогает.

Снижение размера: что реально даёт статическая сборка на musl

Для максимального уменьшения образа обычно выбирают статическую линковку (musl). Тогда runtime-образ может быть scratch или почти пустым.

Плюсы:

• минимальный размер финального образа;
• меньше шансов на проблемы с отсутствующими динамическими библиотеками.

Минусы:

• нужен дополнительный setup для musl target;
• некоторые crate могут требовать патчей/особых флагов;
• поведение DNS/SSL может отличаться в деталях, особенно в отношении сертификатов и системных хуков.

Пример: multi-stage с musl и scratch

# syntax=docker/dockerfile:1.7

FROM rust:1.78-bullseye AS builder
WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    musl-tools pkg-config ca-certificates \
 && rm -rf /var/lib/apt/lists/*

# Добавляем target musl
RUN rustup target add x86_64-unknown-linux-musl

COPY Cargo.toml Cargo.lock ./

# Кэш зависимостей
RUN mkdir -p src && echo 'fn main() { }' > src/main.rs \
 && cargo build --release --locked --target x86_64-unknown-linux-musl \
 && rm -rf src

COPY . .

# Собираем статически линкуемый бинарник
RUN cargo build --release --locked --target x86_64-unknown-linux-musl

# Финальный образ
FROM scratch AS runtime
WORKDIR /app

# Если используете HTTPS, нужно положить CA сертификаты.
# Для scratch это отдельный слой.
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt

COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/myapp /app/myapp

USER 10001:10001
ENTRYPOINT ["/app/myapp"]

Тонкость с CA сертификатами

В статике scratch у вас нет файловой системы с сертификатами. Если приложение делает исходящие TLS-запросы (reqwest, hyper, awc), без ca-certificates.crt оно начнёт падать с ошибками верификации сертификата. Поэтому мы копируем CA bundle из builder.

Как понять, что вы реально линковали статически

Проверьте:

• file target/.../myapp — увидите statically linked (часто);
• ldd для статически линкованного бинарника может не дать полезного результата (он может сказать not a dynamic executable).

Минимизация «лишнего» в Rust: Cargo и сборочный профиль

С точки зрения Docker, размер финального образа зависит от бинарника. Но размер бинарника — это уже отдельная тема, где есть легальные способы уменьшать footprint без деградации функциональности.

Настройка релизного профиля

В Cargo.toml можно добавить:

[profile.release]
opt-level = "z"
lto = true
codegen-units = 1
panic = "abort"
strip = true

Это может существенно уменьшить размер, но будьте внимательны:

• panic = "abort" изменяет поведение паник. В большинстве сервисов это приемлемо (процесс аварийно завершится), но если у вас сценарии, где panic пытаются «перехватывать», проверьте.
• LTO и codegen-units = 1 повышают время сборки. Для CI это может быть нормально, для локальной разработки — нет.
• strip = true может усложнить отладку в проде. Обычно это компенсируется сборкой debug symbols в отдельном артефакте/реестре.

Подводные камни с strip/debug

Если вы собираете контейнер для продакшена, часто полезно:

• хранить символы в отдельном хранилище (например, для addr2line/обратной трассировки);
• включать debug в другой стадии или собирать symbols в CI, не помещая их в образ.

На практике это не всегда нужно, но зависит от зрелости вашего процесса инцидентов.

Упрощаем инфраструктуру: один порт, один процесс, адекватные сигналы

Dockerfile — это не только размер. Это ещё и корректная работа процесса в контейнере.

Не ломаем shutdown

Если ваш сервис использует async runtime (tokio/actix), убедитесь, что он нормально реагирует на SIGTERM. Kubernetes и многие orchestration-системы посылают SIGTERM, дают grace period, затем SIGKILL.

На уровне Dockerfile обычно достаточно:

• не использовать оболочку (sh -c) без необходимости;
• оставить ENTRYPOINT ["/app/myapp"].

А дальше — правильная обработка сигналов внутри приложения.

Пользователь с правами ниже root

В примерах я добавил USER 10001:10001. Это не обязательно, но снижает риск. Однако если вы используете слои/файлы, требующие записи (логи в файловую систему, временные файлы), учтите права. Для простых сервисов лучше писать логи в stdout/stderr.

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

Ниже — «рабочая формула», которую можно применять почти всегда.

1) Multi-stage Dockerfile

• builder: rust + зависимости сборки
• runtime: slim или scratch

2) Кэш dependencies

• копируйте Cargo.toml и Cargo.lock отдельно
• делайте первичную сборку «пустого main» чтобы cargo скачал граф зависимостей
• затем копируйте исходники и собирайте релиз

3) Проверяйте ldd для динамики

• если runtime не содержит .so, приложение не стартует
• добавляйте нужные runtime-пакеты в debian slim

4) Сжимайте бинарник безопасно

• рассмотрите profile.release с strip, LTO и экономным opt-level
• не делайте panic=abort, не проверив поведение

5) Не копируйте лишнее в runtime

• только бинарник и то, что реально необходимо (ca-certificates)

Чек-лист типичных ошибок

1. В runtime образ попал весь /app/target

   • симптом: гигантский размер
   • решение: копируйте только конкретный бинарник

2. Неправильный путь к бинарнику

   • симптом: build успешен, но COPY падает
   • решение: сверить имя пакета и target path: target/release/<name> или target/<target>/release/<name>

3. Сбои из-за features

   • симптом: бинарник собирается, но зависимость динамически требует другой режим
   • решение: фиксировать фичи в Dockerfile через --features ... и хранить их в CI/конфигурации

4. CA certificates отсутствуют (для scratch)

   • симптом: ошибки TLS в рантайме
   • решение: копировать /etc/ssl/certs/ca-certificates.crt

5. Сборка musl без понимания ограничений crate

   • симптом: компиляция падает или поведение отличается
   • решение: поэтапно: сначала динамика, затем musl; проверяйте зависимые crate

Вывод: «минимальный Dockerfile» — это дисциплина, а не магия

Контейнеризация Rust — это не про то, чтобы «впихнуть проект в Docker любой ценой». Качество тут измеряется тремя параметрами: воспроизводимостью сборки, скоростью CI и размером финального образа.

Если подытожить:

• Многостадийная сборка — базовая необходимость: вы отделяете build environment от runtime и почти всегда получаете резкое уменьшение размера.
• Кэширование cargo по Cargo.toml/Cargo.lock — ключ к адекватной скорости сборок без бесконечных пересборок графа зависимостей.
• Для динамических образов обязательно проверяйте ldd, а для statically-linked musl —