从 Dockerfile 到可固定的沙箱 Kit：用 OCI 镜像封装 AI Agent 运行边界

2026-09-25 33 预计阅读时间: 1 分钟
来源: docker.com AI 摘要 Original link

Disclaimer: This article is an AI-assisted summary. Read it together with the original source when precision matters. The summary may omit context, version differences, or edge cases and is not official documentation.

预计阅读时间：9 分钟

Docker Sandbox Kit Specification v3 带来的关键变化，是把 AI Agent 的网络规则、凭证配置和卷声明打包成普通 OCI 镜像。这样一来，沙箱配置不再只是散落在部署脚本、平台控制台和运维文档里的参数，而能像应用镜像一样构建、推送、固定版本并进入发布流程。

Kit 不只是另一份 Dockerfile

传统 Dockerfile 主要回答“容器里有什么”：基础镜像、依赖、代码、入口命令。Sandbox Kit 更关注“Agent 可以接触什么”：

  • 哪些网络目标允许访问，默认是否拒绝其他出站流量；
  • 运行时需要哪些凭证，以及凭证由哪里注入；
  • 哪些目录需要挂载，挂载点是只读还是可写；
  • 当前配置对应哪个不可变版本。

Specification v3 将这些内容装入普通 OCI 镜像，直接复用了成熟的镜像基础设施。团队可以使用现有 Registry 分发 Kit，用摘要定位不可变版本，并把镜像扫描、访问控制和保留策略延伸到沙箱配置。

这里最重要的不是“多构建一个镜像”，而是把 Agent 的运行边界变成可审查、可发布的制品。应用代码和沙箱 Kit 可以分别升级：代码版本变化不一定扩大网络权限，而策略变更也不必重新包装整个应用。

为什么应该使用摘要，而不是只使用标签

OCI 标签适合表达版本意图，例如 agent-kit:v1，但标签通常可以被重新指向。真正稳定的部署引用应使用摘要：

registry.example.com/ai/agent-kit@sha256:0123456789abcdef...

摘要固定的是镜像内容。只要网络规则、凭证声明或卷配置发生变化，镜像内容及其摘要也会变化。这让代码审查和回滚更清晰：变更记录可以准确说明生产环境从哪个 Kit 摘要切换到了哪个摘要。

一种实用的发布方式是：

  1. 在 Git 中审查 Kit 配置；
  2. CI 构建 OCI 镜像并推送到 Registry；
  3. 安全检查通过后记录镜像摘要；
  4. 部署清单只引用摘要；
  5. 更新策略时生成新摘要，而不是覆盖旧制品。

动手制作一个最小 Kit 镜像

下面是一个可以直接改造的最小项目。由于摘要信息没有给出 Specification v3 的正式字段名和目录布局，示例中的 JSON 文件属于演示性结构，不代表官方 schema；它展示的是如何把三类配置装入一个普通 OCI 镜像。接入实际运行时前，应将文件名和字段替换成该实现要求的格式。

把以下命令复制到一个空目录中执行：

set -eu

mkdir -p kit

cat > kit/network.json <<'EOF'
{
  "defaultAction": "deny",
  "egress": [
    {
      "action": "allow",
      "protocol": "https",
      "host": "api.github.com",
      "port": 443
    }
  ]
}
EOF

cat > kit/credentials.json <<'EOF'
{
  "credentials": [
    {
      "name": "github-token",
      "source": {
        "type": "environment",
        "key": "GITHUB_TOKEN"
      }
    }
  ]
}
EOF

cat > kit/volumes.json <<'EOF'
{
  "volumes": [
    {
      "name": "workspace",
      "mountPath": "/workspace",
      "mode": "rw"
    },
    {
      "name": "reference-data",
      "mountPath": "/reference",
      "mode": "ro"
    }
  ]
}
EOF

cat > Dockerfile <<'EOF'
FROM scratch

LABEL org.opencontainers.image.title="example-agent-sandbox-kit"
LABEL org.opencontainers.image.description="Illustrative AI agent sandbox policy bundle"
LABEL org.opencontainers.image.version="1.0.0"

COPY kit/ /kit/
EOF

docker build -t example-agent-kit:1.0.0 .
docker image inspect example-agent-kit:1.0.0

这个镜像没有操作系统和执行入口，因为它在示例中只是配置载体，而不是要启动的应用容器。实际 Sandbox Kit 消费方负责拉取并解释其中的内容。

如果要验证可固定的发布流程，可以将它推送到自己的 Registry。执行前修改 REGISTRY，并确保已经通过 docker login 登录：

set -eu

REGISTRY="registry.example.com/your-team"
REF="$REGISTRY/example-agent-kit:1.0.0"

docker tag example-agent-kit:1.0.0 "$REF"
docker push "$REF"
docker buildx imagetools inspect "$REF"

最后一条命令会显示镜像摘要。部署配置可以采用下面的表达方式；字段同样是平台无关的示意，需要适配实际沙箱运行时：

agent:
  image: registry.example.com/your-team/coding-agent@sha256:APP_IMAGE_DIGEST
  sandbox:
    kit: registry.example.com/your-team/example-agent-kit@sha256:KIT_IMAGE_DIGEST

这种分离非常有价值：Agent 应用镜像说明运行什么代码，Kit 镜像说明代码能访问哪些资源。

凭证不要跟着配置一起泄漏

“凭证被打包进 Kit”不应理解为把真实令牌直接写入镜像层。OCI 镜像可能被 Registry 管理员、CI 系统或具有拉取权限的开发者读取，而且删除标签并不能保证历史层立即消失。

更安全的做法是让 Kit 保存凭证声明或引用，例如环境变量名、Secret 标识或外部密钥服务路径；真实值在沙箱启动时注入。实践中还应设置以下边界：

  • 不在 Dockerfile、JSON 文件或构建参数中写入真实 Token；
  • 将网络策略设为默认拒绝，只开放 Agent 确实需要的目标；
  • 对工作目录和参考数据使用不同卷，能只读的卷不要设为可写；
  • 限制 Registry 仓库的推送权限，避免未经审查的 Kit 替换正式版本；
  • 在部署前验证允许使用的镜像仓库和摘要；
  • 保留旧摘要，以便策略更新导致任务失败时快速回滚。

落地时先从一个 Agent 开始

引入 Kit 时，不必立刻迁移所有 Agent。可以选择一个外部依赖清晰的任务，先盘点它访问的域名、凭证和目录，再生成第一版 Kit。观察拒绝日志和任务失败原因，逐项增加最小权限，而不是一开始就允许整个互联网或挂载完整主机目录。

上线前可以用这份检查表收尾：

  • Kit 是否由 CI 构建，而不是由个人工作站临时发布；
  • 生产部署是否引用 OCI 摘要，而不只是可变标签；
  • 镜像中是否只有凭证引用，没有真实密钥；
  • 网络规则是否默认拒绝并保持最小开放；
  • 每个卷是否明确了挂载路径和读写模式；
  • Kit 更新是否经过审查，并保留可回滚的旧摘要。

Sandbox Kit Specification v3 的实际意义，是让 AI Agent 的运行权限拥有与应用代码相似的供应链能力。网络、凭证和存储边界一旦成为可固定的 OCI 制品，就更容易审查差异、复现环境，也更难在一次临时部署中悄悄扩大权限。

# AI # Docker # LLM # 云原生

相关推荐