Практическое руководство по пути сборки Torque: профили песочницы nsjail, топология сборщика BuildKit, границы аутентификации Docker, импорт/экспорт кэша S3, прогрев кэша, герметичный режим и режимы сбоев, которые важны, когда агентам разрешено собирать образы.

Большинство советов по сборке Docker заканчиваются на порядке слоёв: сначала копируйте манифесты зависимостей, запускайте менеджер пакетов, затем копируйте остальной исходный код. Это полезно, но недостаточно для инструмента релиза. Инструмент релиза должен отвечать на более сложные вопросы. Какой процесс имел право читать дерево исходного кода? Какие учётные данные достигли сборщика? Был ли сокет Docker предоставлен недоверенной команде? Кэш пришёл из предыдущей ветки, общего бакета или пустого локального сборщика? Может ли агент объяснить, почему сборка была быстрой, без парсинга логов BuildKit?

Torque рассматривает сборки образов как часть доказательства доставки, а не как побочный эффект перед Helm. Сборка может выполняться через BuildKit, записывать доказательства, сканировать утечки секретов, генерировать SBOM и доказательства происхождения, использовать локальный кэш или кэш S3 и при необходимости повторно выполняться внутри песочницы nsjail. Это делает путь сборки проверяемым так же, как и путь применения.

Сборщик — это граница доверия

Существует несколько способов собрать образ контейнера на рабочей станции или хосте сборки. Самый простой путь — локальный демон Docker. Более контролируемый путь — BuildKit через настроенный адрес сборщика. Самый изолированный производственный путь — обычно удалённый демон BuildKit или контейнерный сборщик Docker Buildx с учётными данными, привязанными к этому демону, а не передаваемыми через каждый вызов CLI.

Torque напрямую предоставляет эту топологию. --builder выбирает адрес BuildKit, --authfileуказывает на Docker config.json, --platform управляет мультиархитектурным выводом, а --push или --load решают, куда направить результат. Важное правило проектирования: учётные данные Docker должны иметь минимально возможную область действия. Сборка, которая только извлекает из приватного базового образа, не должна наследовать всю домашнюю директорию разработчика. Используйте --authfile или узкую привязку песочницы вместо --sandbox-bind-home, если вы не отлаживаете локальную настройку.

torque build . \
  --file Dockerfile \
  --tag ghcr.io/acme/api:dev \
  --builder docker-container://buildx_buildkit_torque0 \
  --authfile ./tmp/docker-config.json \
  --platform linux/amd64 \
  --push

Режим песочницы — это не просто один флаг

--sandbox означает, что сборка должна выполняться внутри настроенной песочницы или завершиться ошибкой. Это отличается от «попробовать песочницу, если доступна». Для сборок, чувствительных к безопасности, правильное поведение — завершаться ошибкой. Torque также предоставляет части, необходимые операторам, когда реальный хост сложен: --sandbox-config, --sandbox-bin, --sandbox-bind, --sandbox-workdir, --sandbox-probe-path и --sandbox-logs.

Репозиторий включает две полезные формы профилей. sandbox/linux-ci.cfg совместим с Linux-сборщиками в стиле CI и использует большие лимиты tmpfs. sandbox/linux-strict.cfg включает более строгий профиль пространств имён, убирает возможности, избегает sysfs и оставляет только монтажи совместимости, которые обычно нужны рабочей нагрузке Docker или BuildKit. Строгий профиль — это тот, с которого нужно начинать при уменьшении воздействия на хост. Профиль CI — это тот, который нужно использовать, когда пользовательские пространства имён или пространства имён cgroup недоступны на хосте сборки.

export TORQUE_SANDBOX_CONFIG="$(pwd)/sandbox/linux-strict.cfg"
torque build . \
  --tag ghcr.io/acme/api:secure \
  --sandbox \
  --sandbox-logs \
  --sandbox-probe-path /var/run/docker.sock \
  --authfile ./tmp/docker-config.json

torque build sandbox doctor — это быстрый путь для диагностики этой границы, прежде чем вы потратите время на полную сборку. Он проверяет, может ли среда выполнения песочницы запуститься и ведёт ли выбранный контекст себя так, как ожидает Torque. Используйте его после изменения nsjail, монтажей сокета Docker, CI-раннеров или настроек пользовательского пространства имён.

torque build sandbox doctor --context .
torque build . --sandbox --sandbox-config sandbox/linux-ci.cfg --sandbox-logs

Утечки секретов — это режим сбоя сборки

Песочница ограничивает то, к чему может прикасаться процесс сборки. Обнаружение утечек секретов проверяет, что сборка пытается пронести вперёд. Защитный механизм --secrets Torque имеет три режима: warn, block и off. По умолчанию — warn, который позволяет локальной итерации продолжаться, всё ещё записывая находки. Релизные сборки обычно должны использовать block, чтобы значения, похожие на секреты, в Dockerfile, аргументах сборки, скопированных файлах, логах, метаданных кэша или сгенерированных доказательствах, останавливали сборку до публикации образа.

torque build . \
  --tag ghcr.io/acme/api:release \
  --sandbox \
  --secrets block \
  --secrets-config security/secrets-rules.yaml \
  --secrets-report dist/torque-secrets-report.json \
  --capture dist/build.sqlite \
  --push

--secrets-config указывает на конфигурацию правил для специфичных для проекта паттернов и белых списков. --secrets-report записывает машиночитаемый отчёт, который можно приложить к доказательствам. Для настройки репозитория torque init --secrets-provider vault --secrets-file ./secrets.dev.yaml сохраняет ссылки на секреты явными, не обучая Dockerfile или агентов сырым значениям.

Кэш — это функция корректности

Быстрый кэш, которому никто не доверяет, отключают. Доверенный кэш нуждается в именах, области и доказательствах. Torque принимает сырые спецификации кэша BuildKit с --cache-from и --cache-to, а также предоставляет первоклассные флаги S3 для общего случая общего кэша: --s3-cache, --s3-cache-region, --s3-cache-name, --s3-cache-mode, --s3-cache-endpoint-url и --s3-cache-path-style.

mode=min экспортирует достаточно метаданных для повторного использования финального образа. mode=max экспортирует более глубокий граф и обычно лучше для CI-ферм, где ветки пересобирают связанные слои. Имя кэша имеет значение. Если каждая ветка записывает одно и то же имя манифеста, вы получаете больше повторного использования, но больше риска шумной инвалидации. Если каждый коммит записывает уникальное имя, вы получаете более чистое происхождение, но меньше попаданий. Практический стандарт по умолчанию — один префикс кэша на репозиторий и одно имя манифеста на сервис или основную ветку.

torque build . \
  --tag ghcr.io/acme/api:dev \
  --s3-cache s3://acme-build-cache/torque/main \
  --s3-cache-region us-east-1 \
  --s3-cache-name api-main \
  --s3-cache-mode max

Учётные данные S3 должны принадлежать демону BuildKit, роли экземпляра, роли веб-идентичности или одноразовому контейнеру сборщика. Не помещайте ключи AWS в аргументы сборки, ENV Dockerfile или видимые в чате инструкции агента. Torque переносит ссылку на кэш и регион; базовый сборщик должен владеть разрешением учётных данных.

Агентам нужны инструменты кэша, а не парсинг логов

Люди могут прочитать лог BuildKit и сделать вывод, что go mod download был пересобран, потому что изменился go.sum. Агенты не должны гадать. Инструменты MCP кэша Torque разделяют работу на явные операции чтения и записи. torque.cache.inspect нормализует конфигурацию кэша. torque.cache.planклассифицирует изменённые пути и возвращает цели прогрева. torque.cache.warm выполняет мутирующий экспорт кэша только когда это разрешено.

printf '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"torque.cache.plan","arguments":{"contextDir":".","dockerfile":"Dockerfile","tags":["ghcr.io/acme/api:dev"],"changedPaths":["go.mod","go.sum"],"s3Cache":"s3://acme-build-cache/torque/main","s3CacheRegion":"us-east-1","s3CacheName":"api-main"}}}\n' |
  torque-mcp --stdio

Это разница между автоматизацией и shell-транскриптом. Агент получает структурированное состояние кэша, влияние изменённых путей и точную цель прогрева для запроса. Рецензент может увидеть, только ли агент инспектировал кэш или фактически записывал в него.

Форма Dockerfile всё ещё имеет значение

Torque не делает плохой Dockerfile хорошим. Он делает поведение кэша наблюдаемым достаточно, чтобы вы могли это исправить. Держите контекст сборки маленьким с .dockerignore. Копируйте манифесты зависимостей перед полным деревом исходного кода. Используйте монтажи секретов BuildKit для учётных данных вместо ARG или ENV. Фиксируйте базовые образы по дайджесту при использовании герметичного режима. Избегайте записи кэшей менеджеров пакетов в финальные слои времени выполнения. Разделяйте стадии инструментария от стадий времени выполнения, чтобы изменение зависимостей не инвалидировало образ, который пользователи фактически запускают.

# syntax=docker/dockerfile:1.7
FROM golang:1.25@sha256:... AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build go build -o /out/api ./cmd/api

FROM gcr.io/distroless/base-debian12@sha256:...
COPY --from=build /out/api /api
USER 65532:65532
ENTRYPOINT ["/api"]

Герметичность и песочница — это разные контроли

--sandbox контролирует, где процесс клиента сборки выполняется на хосте. --hermeticконтролирует, от чего сборке разрешено зависеть. Песочница всё ещё может говорить с сетью, если профиль позволяет. Герметичная сборка всё ещё может выполняться вне песочницы, если вы это выберете. Используйте оба, когда релиз нуждается в сильной истории: песочница для уменьшения воздействия на хост, герметичный режим для требования фиксированных баз и ограничения сетевой зависимости, если --allow-network явно не присутствует.

torque build . \
  --secure \
  --tag ghcr.io/acme/api:release \
  --attest-dir dist/attest \
  --capture dist/build.sqlite \
  --s3-cache s3://acme-build-cache/torque/main \
  --s3-cache-region us-east-1

Практические рекомендации

Используйте --no-cache редкоОн полезен для доказательства чистой пересборки, но также скрывает проблемы структуры Dockerfile. Предпочитайте матрицу кэша, которая изменяет один вход за раз.

Не кэшируйте секретыИспользуйте монтажи секретов BuildKit и сканирование секретов Torque. Изменённый секрет не должен становиться дайджестом слоя, ключом кэша или артефактом доказательства.

Держите записи кэша ограниченнымиИспользуйте специфичные для ветки или сервиса имена кэша S3. Позвольте CI записывать общие кэши; позвольте pull request'ам импортировать их, если политика разрешает экспорт.

Захватывайте сборку--capture, SBOM, provenance и ссылки графа доказательств превращают быструю сборку в артефакт релиза, который кто-то может аудировать позже.

Практический рецепт релизной сборки

Производственный путь должен быть скучным: диагностировать песочницу, инспектировать кэш, собрать с доказательствами, затем прикрепить результат к доказательству релиза. Команда ниже намеренно держит учётные данные вне Dockerfile и ссылки на кэш, записывает аттестации, захватывает поток сборки и завершается ошибкой, если песочница не может выполниться.

torque build sandbox doctor --context .

torque build . \
  --file Dockerfile \
  --tag ghcr.io/acme/api:v1.2.3 \
  --platform linux/amd64 \
  --sandbox \
  --sandbox-config sandbox/linux-strict.cfg \
  --authfile ./tmp/docker-config.json \
  --s3-cache s3://acme-build-cache/torque/main \
  --s3-cache-region us-east-1 \
  --s3-cache-name api-main \
  --s3-cache-mode max \
  --sbom --provenance \
  --attest-dir dist/attest \
  --capture dist/build.sqlite \
  --push

Причина, по которой это важно — не просто скорость или безопасность по отдельности. Это операционная память. Через шесть месяцев вы должны иметь возможность ответить, почему сборка имела промах кэша, какой сборщик записал кэш, какой профиль песочницы был активен, какой дайджест был произведён и какой релиз его потребил. Путь сборки Torque спроектирован так, что этот ответ находится в артефактах, а не заперт в прокрутке терминала.

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

Безопасный Docker с torque