depot-container-builds

Depot 容器构建

在向 CI 提出变更之前，请先查看 已经尝试过的事项 中是否已有该想法。它记录了哪些内容已经过测量，以及为什么一些听起来不错的变更被回滚或拒绝。

Depot 在远程高性能构建器（16 CPU、32 GB RAM、NVMe SSD 缓存）上运行 Docker 镜像构建。depot build 可直接替代 docker build / docker buildx build。depot bake 替代 docker buildx bake。

多组织用户的项目选择

容器构建命令针对的是特定项目，而不是组织。如果预期的项目不可见，或者构建意外提示选择项目，则当前默认组织可能有误：

depot org show              # Current org ID
depot org list              # Orgs the user belongs to
depot org switch <org-id>   # Optional: set default org

关键概念

• 构建在临时的 EC2 实例上远程运行 —— 默认情况下镜像保留在远程缓存中
• 使用 --load 下载到本地 Docker，使用 --push 推送到镜像仓库，使用 --save 存储到 Depot 的临时镜像仓库
• 缓存在持久化 NVMe SSD 上 完全自动 —— 无需手动配置缓存
• 多平台构建使用 原生 CPU 构建器（无 QEMU 模拟）同时处理 amd64 和 arm64
• 同一项目上的所有团队成员共享同一层缓存

depot build —— 基本模式

# Build remotely (image stays in remote cache)
depot build -t repo/image:tag .

# Build + download to local Docker daemon
depot build -t repo/image:tag . --load

# Build + push directly to registry (fast — doesn't route through local network)
depot build -t repo/image:tag . --push

# Multi-platform build (native CPUs, no emulation)
depot build --platform linux/amd64,linux/arm64 -t repo/image:tag . --push

# Save to Depot ephemeral registry (7-day default, configurable per repository)
depot build --save .
depot build --save --save-tag my-tag .

# Suppress provenance metadata (fixes "unknown/unknown" platform in registries)
depot build -t repo/image:tag --push --provenance=false .

# Lint Dockerfile before building
depot build -t repo/image:tag . --lint

# Build with secrets
depot build --secret id=mysecret,src=./secret.txt -t repo/image:tag .

# Build with SSH forwarding
depot build --ssh default -t repo/image:tag .

# Specify a Depot project explicitly
depot build --project <project-id> -t repo/image:tag .

关键参数

参数	描述
--load	将镜像下载到本地 Docker 守护进程
--push	推送到镜像仓库
--save	保存到 Depot 临时镜像仓库
--save-tag	为 Depot Registry 自定义标签
--platform	目标平台：linux/amd64、linux/arm64（原生，无模拟），以及 linux/arm/v6、linux/arm/v7、linux/386
--build-platform	强制构建在特定架构上运行（默认为 dynamic）
--project	Depot 项目 ID
--token	Depot API 令牌
--lint	构建前对 Dockerfile 进行 lint
--provenance	控制来源证明（设置为 false 以修复 unknown/unknown）
--sbom	生成 SBOM 证明（--attest type=sbom 的简写）
--sbom-dir	存储 SBOM 证明的目录
--attest	证明参数（例如 type=sbom,generator=image）
--no-cache	为此构建禁用缓存
-f / --file	Dockerfile 路径
-t / --tag	镜像名称和标签
--target	构建特定阶段
--build-arg	设置构建时变量
--secret	暴露密钥（id=name[,src=path]）
--ssh	暴露 SSH agent
--output / -o	自定义输出（type=local,dest=path）

depot bake — 多镜像构建

可直接替代 docker buildx bake。并行构建多个镜像。

depot bake                                    # Default file lookup
depot bake -f docker-bake.hcl                 # Specific HCL file
depot bake -f docker-compose.yml --load       # Build compose services + load locally
depot bake --save --save-tag myrepo/app:v1    # Save to Depot Registry
depot bake --print                            # Print resolved config without building

默认文件查找顺序： compose.yaml → compose.yml → docker-compose.yml → docker-compose.yaml → docker-bake.json → docker-bake.hcl → docker-bake.override.json → docker-bake.override.hcl

HCL Bake 文件示例

variable "TAG" {
  default = "latest"
}

group "default" {
  targets = ["app", "worker"]
}

target "app" {
  dockerfile = "Dockerfile"
  platforms  = ["linux/amd64", "linux/arm64"]
  tags       = ["myrepo/app:${TAG}"]
  args = { NODE_VERSION = "20" }
}

target "worker" {
  dockerfile = "Dockerfile.worker"
  tags       = ["myrepo/worker:${TAG}"]
  contexts   = { app = "target:app" }  # Share base between targets
}

覆盖变量：TAG=v2.0 depot bake

带每服务项目 ID 的 Docker Compose

services:
  api:
    build:
      dockerfile: ./Dockerfile.api
      x-depot:
        project-id: abc123
  web:
    build:
      dockerfile: ./Dockerfile.web
      x-depot:
        project-id: def456

Docker Compose 集成

# Preferred: build all services in parallel, then load
depot bake -f docker-compose.yml --load
docker compose up

# Alternative: zero code change (less efficient, each service = separate build)
depot configure-docker
docker compose build

从 Docker 迁移

# docker build → depot build (same flags, one-line swap)
depot build -t my-image .

# docker buildx bake → depot bake
depot bake -f docker-bake.hcl

# Zero code change via Docker plugin
depot configure-docker
docker build .  # Routes through Depot (look for [depot] prefix in logs)

迁移时，请移除以下参数 —— Depot 会自动处理缓存：

• --cache-from type=gha —— 会导致 "services aren't available" 错误
• --cache-to type=gha —— 同样的问题
• 任何手动配置的 BuildKit 缓存

常见错误

错误	修复
使用 --cache-from type=gha 或 --cache-to type=gha	移除它们。Depot 会自动在 NVMe SSD 上缓存。
多平台镜像显示 unknown/unknown 平台	添加 --provenance=false
期望 depot build 后在本地得到镜像	添加 --load 以下载，或添加 --push 以推送到镜像仓库
构建上下文中缺少 .git 目录	添加 --build-arg BUILDKIT_CONTEXT_KEEP_GIT_DIR=1
构建卡住或出现 "failed to mount" 错误	在项目设置中重置缓存，或通过 depot cache reset 重置
拉取基础镜像时出现 "401 Unauthorized"	Docker Hub 速率限制 —— 使用 docker login 进行身份验证，或使用 public.ecr.aws/docker/library/ 镜像源
--load 失败并提示 "client version 1.43 is too old"	Docker Engine v29 将最低 API 版本提升至 1.44 —— 在构建命令前加上 DOCKER_API_VERSION=1.52 depot build --load .
"Keep alive ping failed" / OOM	在项目设置中扩大构建器规格或启用自动扩缩容

构建器规格

规格	CPU	内存	每分钟费用	分钟倍率	套餐
默认	16	32 GB	$0.04	1x	全部
大	32	64 GB	$0.08	2x	Startup+
超大	64	128 GB	$0.16	4x	Startup+

按秒计费。大和超大构建器除了每分钟费用更高之外，还会通过倍率更快地消耗你包含的构建分钟数。

Depot Registry

一个兼容 OCI 的镜像仓库，既可作为构建产物的轻量级临时存储，也可作为所有镜像（包括非 Depot 构建的镜像）的完整主仓库。每个组织都有自己的子域名 {orgId}.registry.depot.dev，由全球 CDN 提供支持，并存储最大 50 GB 的镜像和 OCI 制品（Helm charts、AI models）。可在仪表板的 Registry Explorer 中浏览仓库、标签和证明。

# Save a Depot build's output to the registry (project-scoped, no tagging step)
depot build --save -t myapp .

# Push any image to Depot Registry as a primary registry
docker push {orgId}.registry.depot.dev/your/app:v1

# Pull a saved image (by build ID or by tag)
depot pull --project <id> <build-id>
depot pull --project <id> my-image:tag
depot pull --project <id> --platform linux/arm64 <build-id>   # pull a specific platform

# Generate a short-lived (1-hour) read-only token to pull from the Depot Registry
depot pull-token --project <id>
depot pull-token --project <id> <build-id>                    # scoped to a specific build

# Push saved image to another registry
depot push --project <id> -t registry/image:tag <build-id>

# Docker auth for Depot Registry (each org has its own subdomain)
docker login {orgId}.registry.depot.dev -u x-token -p <depot-token>
# Registry URL: {orgId}.registry.depot.dev/your/app:tag
# (the legacy registry.depot.dev/<project-id>:<build-id> form still works for existing usage)

镜像保留期默认为 7 天，但可在 Registry Explorer 中按仓库配置，可按时间（1、7、14 或 30 天）或按标签数量（5、10、25、50 或 100 个标签）配置。

直通缓存： Depot Registry 可以代理外部镜像仓库，并将其层缓存在 CDN 上，这样重复拉取时会跳过上游跳转（更快的 CI 拉取、全球分发、对 Google Artifact Registry 等镜像仓库更简单的身份验证）。在 Registry Settings 中配置上游；支持的提供商包括 Docker Hub、GitHub Container Registry、GitLab Container Registry、Quay.io、AWS ECR、Google Artifact Registry、Azure Container Registry 和自定义镜像仓库。直通必须在创建仓库时设置，无法添加到现有仓库。

特殊输出格式

# estargz (lazy-pulling for faster container startup)
depot build --output "type=image,name=repo/image:tag,push=true,compression=estargz,oci-mediatypes=true,force-compression=true" .

# zstd compression (faster Fargate/K8s startup)
depot build --output type=image,name=repo/image:tag,oci-mediatypes=true,compression=zstd,compression-level=3,force-compression=true,push=true .

# SOCI v2 (lazy-loading for faster startup of large images, for example CUDA/PyTorch)
depot build -t repo/image:tag --push --output type=image,soci=true,compression=gzip,force-compression=true,oci-mediatypes=true .

SOCI 仅索引 gzip 层，因此需要 compression=gzip，而 force-compression=true 确保每个层（包括基础镜像层）都被索引。索引与未更改的层一起写入注册表，因此没有单独的推送后步骤；默认情况下会跳过小于 10 MB 的层（可通过 soci-min-layer-size 更改）。要获得启动优势，拉取平台必须使用 SOCI snapshotter：AWS Fargate 会自动执行此操作，而 Amazon EKS/EC2 或您自己的主机需要在 containerd 中启用 soci-snapshotter。