Docker Buildx для многоархитектурных образов: как настроить удалённый Mac CI в 2026

Распределите роли между нативными узлами: удалённый Mac на Apple Silicon оставьте для сборки и проверки linux/arm64, а linux/amd64 передайте нативному AMD64-узлу или проверенному кросс-компилятору. Один Mac через QEMU способен собрать оба типа образов, но не должен автоматически становиться единственным исполнителем всех архитектур.

Это решение подходит, если вы публикуете контейнеры для ARM64 и AMD64, поддерживаете собственный CI или планируете использовать Mac как постоянно доступный Builder. Если вас уже ограничивают медленные эмулируемые компиляции, несовместимые зависимости или непредсказуемые сбои, ниже вы получите последовательность перехода к нативному разделению задач.

Архитектура узлов и границы эмуляции

Docker официально описывает три стратегии многоархитектурной сборки: эмуляция QEMU, несколько нативных узлов и кросс-компиляция. Это не три взаимозаменяемых названия одной функции. У каждой стратегии собственная граница ответственности, которую нужно сопоставить с вашим Dockerfile и зависимостями. Подробное сравнение подходов приведено в документации Docker по много­платформенной сборке.

Mac на Apple Silicon может участвовать в сборке linux/amd64, если Docker Desktop использует QEMU. Но здесь нужно различать четыре понятия:

• архитектура хоста — например, Apple Silicon;
• платформа узла Builder — то, что объявляет подключённый Docker daemon;
• целевая платформа образа — например, linux/arm64 или linux/amd64;
• архитектура процесса внутри контейнера во время RUN.

Именно последнее различие часто скрывает ошибку. Команда docker buildx build --platform linux/amd64 не означает, что AMD64-команды выполняются нативно на Mac. Если в Dockerfile есть компиляция, генерация кода, установка бинарных зависимостей или архивирование, каждый такой шаг нужно проверить отдельно.

Перед подключением Mac соберите из CI четыре вида доказательств:

1. какие платформы реально публикуются сейчас;
2. на каком шаге возникает ошибка или резкое падение cache hit;
3. какие команды требуют выполнения внутри целевой архитектуры;
4. можно ли передать компиляцию кросс-компилятору без потери тестовой достоверности.

Не добавляйте Mac только потому, что у вас есть ARM64-оборудование. Если текущая сборка полностью кросс-компилируется, новый узел может увеличить количество состояний, секретов и точек отказа, но не решить исходную проблему.

Важно: успешный код возврата buildx build ещё не доказывает, что опубликованный тег содержит обе архитектуры. Проверяйте Manifest отдельно и запускайте хотя бы минимальный контейнер на каждой целевой платформе.

Подготовка удалённого Mac и Builder

Сначала проверьте саму среду, а уже затем создавайте CI-интеграцию. На macOS Docker Desktop предоставляет Docker Engine и Buildx; актуальные требования и способ установки нужно сверять с официальной инструкцией Docker Desktop для Mac. Конкретные версии Docker Desktop, Buildx и BuildKit в этой статье намеренно не фиксируются: перед внедрением проверьте текущий официальный журнал выпусков Buildx.

Шаг 1. Отдельная учётная запись и канал управления

Создайте на Mac отдельную учётную запись для CI, не используйте личную интерактивную сессию разработчика и не храните токен Registry в shell history. Оставьте локальный или альтернативный канал управления до завершения проверки: ошибочная настройка SSH или Docker Context не должна лишить вас доступа к узлу.

Если CI подключается по SSH, ограничьте ключ назначенной учётной записью и разрешите только необходимые действия. Общие рекомендации по защите удалённого доступа к Docker собраны в документации Docker по SSH и защите доступа.

Шаг 2. Проверка CLI, Context и платформы

Используйте собственные значения вместо реальных имён:

export MAC_HOST="ci-user@<mac-host>"
export MAC_CONTEXT="<mac-context>"
export BUILDER_NAME="<builder-name>"

docker context create "$MAC_CONTEXT" --docker "host=ssh://${MAC_HOST}"
docker --context "$MAC_CONTEXT" info
docker --context "$MAC_CONTEXT" buildx version
docker --context "$MAC_CONTEXT" buildx ls

Наличие команды docker buildx не означает, что удалённый Builder готов принимать задания. Проверьте, что Docker daemon доступен, Context указывает на правильный хост, а Buildx видит платформу узла.

Шаг 3. Создание многонодового Builder

Для начального теста создайте Builder на удалённом Mac:

docker buildx create \
  --name "$BUILDER_NAME" \
  --driver docker-container \
  "$MAC_CONTEXT" \
  --use

docker buildx inspect --bootstrap

После этого добавьте нативный AMD64-узел:

docker buildx create \
  --name "$BUILDER_NAME" \
  --append \
  <amd64-context>

docker buildx inspect --bootstrap
docker buildx ls

Синтаксис создания и добавления узлов сверяйте с официальной документацией buildx create. Не копируйте в команду буквальные строки <mac-host>, <builder-name> или <amd64-context>: это намеренные заполнители, чтобы не закреплять в статье ваши реальные адреса и имена.

Шаг 4. Проверка драйвера

Посмотрите, какой драйвер назначен каждому узлу. Драйвер влияет на изоляцию BuildKit, доступные функции и поведение вывода. Документация Docker о драйверах Builder объясняет, почему docker и docker-container нельзя считать полностью равными вариантами.

Практическое правило такое: не меняйте драйвер ради формального совпадения с примером. Сначала зафиксируйте текущую схему, затем убедитесь, что выбранный драйвер поддерживает нужный вам экспорт образа и кэша. Если Builder не проходит inspect --bootstrap, о подключении к CI говорить рано.

Первые сборки и проверка платформ

Не начинайте с большого проекта. Сначала создайте минимальный Dockerfile с предсказуемым базовым образом:

FROM --platform=$BUILDPLATFORM alpine:latest
ARG TARGETOS
ARG TARGETARCH
RUN printf 'target=%s/%s\n' "$TARGETOS" "$TARGETARCH"

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

docker buildx build \
  --builder "$BUILDER_NAME" \
  --platform linux/arm64 \
  --tag <registry>/<repository>:<arm64-test> \
  --push .

docker buildx build \
  --builder "$BUILDER_NAME" \
  --platform linux/amd64 \
  --tag <registry>/<repository>:<amd64-test> \
  --push .

На этом этапе проверяются не скорость и не размер слоя, а четыре факта:

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

После минимального теста подключите реальный Dockerfile. Отдельно пометьте шаги, где происходит компиляция, установка нативного пакета, генерация артефактов или запуск тестов. Если AMD64 выполняется через QEMU, запишите это явно в CI-логе. Нельзя называть такой результат нативным AMD64-тестом только потому, что целевой тег имеет правильное имя.

Для проверки итогового Manifest используйте:

docker buildx imagetools inspect \
  <registry>/<repository>:<release-tag>

Команда и формат проверки описаны в официальной документации imagetools inspect. В выводе должны присутствовать ожидаемые платформы. Проверяйте именно опубликованный тег, а не только локальный cache или промежуточный digest.

Кэш, публикация и маршрутизация CI

Кэш сборки, конечный образ и Manifest — разные сущности. Их нельзя бездумно складывать под одной ссылкой. Для Registry-кэша задайте отдельное имя:

docker buildx build \
  --builder "$BUILDER_NAME" \
  --platform linux/arm64 \
  --cache-from type=registry,ref=<registry>/<repository>:<cache-arm64> \
  --cache-to type=registry,ref=<registry>/<repository>:<cache-arm64>,mode=max \
  --tag <registry>/<repository>:<arm64-sha> \
  --push .

Конкретные backend и параметры нужно сопоставить с возможностями вашего драйвера и Registry; перечень вариантов приведён в документации Docker о кэше сборки. Для ARM64 и AMD64 разумно использовать разные ссылки кэша, если слои зависят от платформы. Это уменьшает риск ложного совпадения, когда слой выглядит одинаково по шагу Dockerfile, но содержит бинарный результат другой архитектуры.

В CI разделите задания по платформам. ARM64 отправляйте на Runner или Context удалённого Mac, AMD64 — на нативный AMD64-узел, если он есть. Не запускайте параллельные задачи в одной рабочей директории и не рассчитывайте, что общий локальный Docker cache безопасно обслужит несколько независимых процессов.

После успешной публикации обоих образов объедините их:

docker buildx imagetools create \
  --tag <registry>/<repository>:<release-tag> \
  <registry>/<repository>:<arm64-sha> \
  <registry>/<repository>:<amd64-sha>

Синтаксис и ограничения команды описаны в документации imagetools create. Финальный шаг должен выполняться только после того, как обе платформы прошли собственные проверки. Если один job завершился ошибкой, CI должен остановить публикацию общего Manifest, а не оставить частичный тег с неясным содержимым.

Минимальные права Registry-токена должны включать только необходимые операции чтения и записи. Секреты передавайте через хранилище CI, а не через аргументы Dockerfile. Затем запустите процесс из чистого клона: это выявит зависимость от локального ~/.docker, интерактивной авторизации, незаписанного Context или случайно сохранённого cache.

FAQ для внедрения

Может ли Apple Silicon собирать AMD64

Да, но только через эмуляцию или кросс-компиляцию, если проект это допускает. Нативным будет лишь выполнение на ARM64-узле для linux/arm64. Поэтому Apple Silicon полезен как постоянный ARM64 Builder и валидатор, но не должен автоматически заменять AMD64-инфраструктуру для всех компиляционных задач.

QEMU или нативный ARM64 Builder

Для короткого smoke-теста QEMU уменьшает количество инфраструктуры. Для регулярного удалённого Mac CI нативный ARM64-узел даёт более честную проверку ARM-зависимостей и не маскирует ошибки, возникающие только на целевой платформе. AMD64-часть при этом всё равно нужно выполнять нативно или обоснованно кросс-компилировать.

Подключение Mac к многонодовому Builder

Используйте отдельный SSH Docker Context, затем создайте Builder с этим Context и добавьте остальные узлы через --append. После каждого изменения выполняйте docker buildx inspect --bootstrap и проверяйте платформы в docker buildx ls. Такой порядок позволяет отделить проблему SSH от проблемы BuildKit или неправильного выбора драйвера.

Общий кэш и Manifest

Кэш должен иметь отдельные, понятные ссылки, а финальные образы — собственные теги, привязанные к commit или digest. Manifest объединяет уже опубликованные результаты, но не заменяет проверку запуска. После imagetools create снова выполните imagetools inspect и сохраните вывод в артефакты CI.

Долговременная эксплуатация и восстановление

После первой успешной публикации проверьте не только рабочий путь, но и отказовые сценарии.

1. Запустите сборку и разорвите SSH-сессию. Убедитесь, что процессом управляет CI или удалённый Builder, а не ваш локальный терминал.
2. Перезапустите Mac в согласованное окно обслуживания. После загрузки проверьте Docker Desktop, доступность daemon и состояние Docker Context.
3. Повторно выполните docker buildx inspect --bootstrap. Если Builder создаётся заново, определите, где хранятся его настройки и как CI получает актуальное имя.
4. Отключите Registry-кэш и запустите тестовую сборку. Она должна либо корректно перейти к чистому построению, либо завершиться понятной ошибкой, а не опубликовать неполный результат.
5. Имитируйте ошибку ARM64 или AMD64 job. Финальный Manifest не должен появиться, пока отсутствует одна из обязательных платформ.
6. Обновите Docker Desktop, Buildx или BuildKit сначала на изолированном узле и прогоните представительный Dockerfile. После этого сравните логи, digest и результаты запуска.

Не используйте наличие старого Builder как гарантию восстановления. После перезапуска нужно подтвердить весь путь: daemon, Context, узлы, кэш, публикацию и проверку Manifest.

Сохраните в эксплуатационной документации владельца каждого узла, допустимые платформы, обязательные stop-условия и процедуру отката. Если Mac недоступен, CI должен либо переключиться на заранее проверенный ARM64-узел, либо остановить релиз. Молчаливое исключение одной платформы опаснее явного сбоя, потому что потребитель получит тег, который не соответствует заявленной поддержке.

Чек-лист выхода в рабочий CI

• [ ] В CI зафиксированы целевые платформы каждого образа.
• [ ] В Dockerfile отмечены компиляционные и платформозависимые шаги.
• [ ] Для удалённого Mac создан отдельный CI-пользователь.
• [ ] SSH-ключ и права Registry выданы по принципу минимальных полномочий.
• [ ] Docker Context указывает на проверенный хост.
• [ ] Builder прошёл inspect --bootstrap.
• [ ] В docker buildx ls видны ожидаемые платформы узлов.
• [ ] ARM64 собран и проверен на Apple Silicon без QEMU.
• [ ] AMD64 собран нативно или отдельно отмечен как эмулируемый.
• [ ] Кэш ARM64 и AMD64 имеют разные ссылки.
• [ ] Теги платформенных образов отделены от ссылки кэша.
• [ ] Manifest создаётся только после успешных job обеих платформ.
• [ ] imagetools inspect подтверждает полный список платформ.
• [ ] Чистый клон проходит авторизацию и сборку без интерактивной сессии.
• [ ] Разрыв SSH не прерывает управляемую CI-задачу.
• [ ] После перезапуска Mac Builder и Docker Context восстанавливаются.
• [ ] Описаны действия при недоступности узла, Registry-кэша или одной платформы.

Итоговая схема выбора

Если проект содержит простые образы и сборки происходят редко, начните с QEMU как диагностического варианта, но не называйте его нативной проверкой. Если основная нагрузка — ARM64 и вам нужен постоянно доступный узел, удалённый Mac на Apple Silicon оправдан как основной ARM64 Builder. Если публикация AMD64 обязательна и Dockerfile выполняет тяжёлую компиляцию, добавьте нативный AMD64-узел либо докажите кросс-компиляцией, что целевая среда не теряется.

Такой подход лучше, чем заставлять один Mac одновременно эмулировать все платформы: единичный узел создаёт общий отказ, QEMU усложняет диагностику компиляции, а общий кэш может скрыть различия между архитектурами. Перенос сборок на случайный Linux-сервер тоже не решает ARM64-валидацию и часто приводит к разрыву между CI и средой, где образ запускается.

Если вам не хватает именно долгосрочно доступного нативного ARM64-узла, разумно начать с небольшой аренды Apple Silicon Mac в VPSMAC — например, сравнить доступные варианты удалённых Mac-узлов и узлы Apple Silicon в Гонконге, подключить собственный Dockerfile и сначала проверить сборку, публикацию и восстановление после перезапуска. После этой проверки вы сможете без догадок решить, оставлять ли Mac в постоянном пуле, добавлять ли AMD64-узел или вернуться к кросс-компиляции.