depot-container-builds

Depot 容器构建

Depot 在远程高性能构建器上运行 Docker 镜像构建（16 CPU、32 GB RAM、NVMe SSD 缓存）。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
--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 build cancel。通过 --token 或 DEPOT_TOKEN 提供组织 API 令牌；项目令牌、只读令牌、旧版登录令牌和 CI OIDC 凭据均无法取消构建。

depot build cancel <build-id> <another-build-id>
depot build cancel --all-running --project <project-id> --dry-run
depot build cancel --all-running --project <project-id> --yes --output json

选择指定的构建 ID，或使用 --all-running --project，不能两者同时使用。批量选择必须显式指定项目；depot.json 和 DEPOT_PROJECT_ID 不会提供该项目。使用 --dry-run 预览批量取消；仅在获准进行非交互式取消时使用 --yes。选择范围不包括之后启动的构建。

取消操作是异步的：成功表示请求已被接受，并不代表执行已停止。已完成的构建会作为成功的空操作处理。JSON 会报告每个构建的结果或错误；任何请求失败都会导致命令失败。

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 v1               # Save as v1-<target-name> in 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

未指定 target 参数时，depot bake 会构建 default 组。保存的标签使用 <build-id>-<target-name>；--save-tag v1 会添加 v1-<target-name>。使用 --save --push 可将镜像保存到 Depot Registry，并推送已配置的 target 标签。在 HCL target 中设置 project_id，即可选择其 Depot 项目。

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 核数	RAM	每分钟费用	分钟数倍率	套餐
默认	16	32 GB	$0.04	1x	全部
大型	32	64 GB	$0.08	2x	Startup+
超大型	64	128 GB	$0.16	4x	Startup+

按秒计费。大型和超大型构建器的每分钟费用更高，且会按倍率更快消耗套餐内的构建分钟数。

构建自动扩缩容

默认情况下，自动扩缩容处于禁用状态，因此 Depot 会将项目针对每种架构的构建路由到一个构建器。当并发构建需要使用不同的构建器时，请在项目设置中启用水平自动扩缩容。设置表单会预选每个实例 16 个构建；当并发构建达到配置的上限时，Depot 会启动另一个构建器。

每个构建器都有独立的缓存。大规模自动扩缩容可能会降低缓存效率，因此，如果单个构建需要更多 CPU 或内存，请先尝试使用更大的构建器。所有套餐均可使用自动扩缩容，且无需额外付费。

一次 depot bake 调用在自动扩缩容中计为一次构建，无论其目标数量是多少。不同的项目 ID 会创建不同的构建请求。

使用组织 API 令牌通过 CLI 配置自动扩缩容：

depot projects update <project-id> --max-concurrent-builds 3
depot projects update <project-id> --disable-autoscaling

此正数上限适用于每个构建器实例。两个更新标志互斥；省略两者会保留当前设置。depot projects create <name> --max-concurrent-builds 3 可为新项目启用自动扩缩容；创建项目时不带此标志则会禁用自动扩缩容。

Depot 注册表

这是一个兼容 OCI 的注册表，既可作为轻量级临时存储来保存构建输出，也可作为所有镜像（包括非 Depot 构建的镜像）的完整主注册表。每个组织都会获得自己的子域名 {orgId}.registry.depot.dev，由全球 CDN 提供支持，可存储最大 50 GB 的镜像和 OCI 工件（Helm chart、AI 模型）。在控制面板的注册表浏览器中查看存储库、标签和证明。

# 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 project 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 1-hour read-only token for the project's registry paths
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>

# List saved images as JSON
depot image list --project <id> --output json

# Delete selected image tags only when requested
depot image rm --project <id> app:old app:staging

# Docker auth for Depot Registry (each org has its own subdomain)
docker login {orgId}.registry.depot.dev -u x-token
# Enter a scoped registry access token at the password prompt.
# 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 天，但可在注册表浏览器中按存储库配置：按时间（1、7、14 或 30 天）或按标签数量（5、10、25、50 或 100 个标签）。

要使用自定义镜像名称，请使用注册表访问令牌。组织所有者可在 Registry Settings → Registry access tokens 中创建令牌。选择 Pull 或 Push 权限；Push 包含拉取权限。令牌范围可以限定为精确路径（frontend）、一级路径（team/*）、任意深度（team/**）或所有存储库（**）。范围中不要包含注册表主机名和镜像标签。

对已保存的项目构建和标签使用 depot pull，对自定义或拉取缓存存储库使用 docker pull。CLI 拉取令牌仅适用于 <project-id> 及其后代路径。其他名称请使用具有 Pull 权限的注册表访问令牌。

**拉取缓存：**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 和自定义注册表。必须在创建存储库时设置拉取缓存，无法为现有存储库添加此设置。

每次拉取时，都不会从上游刷新 latest 等可变标签的缓存。请使用新的不可变标签或摘要来选择更新后的内容。缺失或已回收的内容仍需从上游注册表获取，因此缓存无法保证上游服务中断时内容仍然可用。

特殊输出格式

# 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。