OpenSandbox 架构原理与接入实施全解：从 Docker 本地起步到 Firecracker 高密度集群

如果说 Kubernetes agent-sandbox 解决的是「沙箱在 K8s 里怎么编排」，那么 OpenSandbox 解决的是更上一层的问题：给 Agent 应用一个统一的沙箱 API——创建沙箱、跑命令、传文件、流式读输出、管网络出口，底下无论跑的是 Docker 容器还是 Firecracker 微虚机，应用侧代码不变。这个项目由阿里巴巴主导开源（现挂在 opensandbox-group 组织下，2025 年 12 月公开仓库），Apache-2.0 协议，半年时间做到了 15.7k stars、3300+ commits，已进入 CNCF Landscape 并通过 OpenSSF 最佳实践认证，是 2026 年自托管 Agent 沙箱赛道热度最高的项目。本文基于 main 分支架构文档与部署指南，讲清它的架构原理和完整接入路径。

一、总体架构：六个平面

OpenSandbox 官方架构文档把系统切成六个平面，这个切分本身就是理解它的钥匙：

flowchart LR
    subgraph Client["① 客户端面"]
        PY["Python SDK"]
        TS["TS/JS SDK"]
        GOCLI["Go SDK / Java / C#"]
        CLI["osb CLI"]
        MCP["MCP Server"]
    end
    subgraph Protocol["② 协议面（specs/ OpenAPI）"]
        LIFE["sandbox-lifecycle.yml"]
        EXEC["execd-api.yaml"]
        EGR["egress-api.yaml"]
    end
    subgraph Control["③ 生命周期控制面"]
        SERVER["FastAPI Server<br/>（鉴权/校验/持久化 SQLite·PG）"]
    end
    subgraph Runtime["④ 运行时后端"]
        DOCKER["Docker 运行时<br/>本地/单机"]
        BATCH["K8s BatchSandbox + Pool<br/>（自研 Operator）"]
        ASB["k8s agent-sandbox<br/>provider（可选）"]
        FSB["FastSandbox<br/>Firecracker microVM"]
    end
    subgraph Data["⑤ 沙箱数据面"]
        EXECD["execd 守护进程<br/>（Go）"]
        USER["用户镜像 + 入口进程"]
    end
    subgraph Net["⑥ 网络与安全面"]
        ING["Ingress 网关"]
        EGS["Egress Sidecar<br/>DNS/nftables + 凭据保管库"]
    end
    Client --> Protocol --> SERVER
    SERVER --> DOCKER & BATCH & ASB & FSB
    DOCKER & BATCH & FSB --> EXECD
    EXECD --- USER
    ING --> USER
    EGS --- USER

设计上有两条主线值得注意：协议优先——specs/ 目录下的 OpenAPI 规范是公共契约的唯一事实源，SDK 里生成代码与手写适配层分离；控制面与数据面分离——FastAPI 生命周期服务器只做编排、鉴权和元数据持久化，平台相关的资源创建交给运行时 provider，沙箱内部操作交给 execd。

二、控制面：一次 exec 请求的完整旅程

创建沙箱：POST /v1/sandboxes（带 image、snapshotId 或 templateId 三选一）→ 服务器校验请求与配置 → 按 [runtime].type 选服务实现（docker 或 kubernetes）→ provider 创建容器/工作负载/微虚机 → 注入 execd → 返回 Running。创建是异步的，客户端轮询 GET /v1/sandboxes/{id} 或用 SDK 的就绪助手。

执行阶段客户端绕过控制面直连数据面：从沙箱元数据或服务端代理解析出 execd 端点，直接调 execd API（必要时带 X-EXECD-ACCESS-TOKEN）。这个「控制面管生命周期、数据面管执行」的分离，是它做到高并发执行吞吐的关键。

Kubernetes 模式下还有一层聪明的复合路由（CompositeSandboxService）：创建请求带 templateId 走 FastSandboxService（微虚机路径），带 image/snapshotId 走 KubernetesSandboxService（容器路径）；存量操作按沙箱 ID 前缀路由——fsb- 开头归 FastSandbox。同一个 API 背后是两套执行形态，应用侧无感。

三、三种运行时后端的原理与取舍

3.1 Docker：本地与单机

直连 Docker daemon 管容器，支持 CPU/内存/GPU 限制、AppArmor/seccomp/capabilities 加固、host/bridge/自定义网络。启动时把 execd 二进制从 execd_image 注入容器并安装 bootstrap 启动器再拉起用户入口。暂停/恢复用容器级 freeze/unfreeze（有 egress sidecar 时先冻结沙箱再冻结 sidecar，恢复反序）；快照是 docker commit 成本地镜像。

3.2 Kubernetes + BatchSandbox：高吞吐与池化

自研 Operator 提供三个 CRD：BatchSandbox（按 Pod 模板批量创建一到多个沙箱副本，支持任务编排，面向评测/RL 这类批量负载）、Pool（预热池，快速分配）、SandboxSnapshot（快照记录）。暂停/恢复有两条路径：默认对单副本工作负载做 rootfs 提交——把沙箱文件系统 commit 成 OCI 镜像并释放运行资源，恢复时用原沙箱 ID 重建；配置了 QEMU 快照契约的工作负载则走 VM 状态 checkpoint/restore。公共快照 API 会把镜像推到 OCI 仓库，实现跨机恢复。

3.3 FastSandbox：Firecracker 微虚机，97ms 的诞生

这是性能旗舰：模板化的 Firecracker microVM 执行形态。控制协议是与外部 fast-sandbox 平台控制面之间的 gRPC FastPath v2（9090 端口）——变更与运行时操作走 FastPath，Kubernetes 侧的 sandbox.fast.io/v1alpha2 CRD 只承载持久化状态与观测。恢复时由 FastPath 还原检查点。官方基准：warm 创建延迟 97ms P50 / 308ms P99（10 并发，Python SDK → 网关 → execd 健康检查全链路）。取舍也要知道：这条路径目前拒绝卷挂载，出口策略走共享的 Fastlet profile（不是每沙箱 sidecar），网络策略改由生命周期 API 的 /sandboxes/{id}/networkpolicy 管理。

值得一提的生态联动：OpenSandbox 把 kubernetes-sigs/agent-sandbox 列为官方工作负载 provider——编排标准（agent-sandbox）+ 沙箱平台（OpenSandbox） 可以叠着用，这是当前社区比较认可的分层姿势。

四、数据面 execd 与网络安全面

execd 是 Go（Gin）写的沙箱内守护进程，能力清单：命令执行（SSE 流式输出）、后台命令状态与增量日志、持久 bash 会话、WebSocket PTY、文件/目录操作、进程隔离会话、Jupyter 代码上下文（官方 code-interpreter 镜像内置 Python/Java/Node/Go 内核）、本机指标与 OpenTelemetry 导出、可选访问令牌。

入口：K8s 部署下沙箱 Pod 只有 ClusterIP，客户端流量必须过 Ingress 网关，支持三种路由模式——请求头 OpenSandbox-Ingress-To: <sandbox-id>-<port>、URI 前缀 /<sandbox-id>/<port>/<path>、通配符域名。secureAccess 开启后服务器签发端点凭证，还支持签名路由令牌。可选的「访问即续期」（renew-on-access）能通过服务端代理或网关事件自动延长沙箱 TTL。

出口：egress sidecar 支持 FQDN/通配符白黑名单，dns 模式只做 DNS 过滤，dns+nft 模式加 nftables 按 resolved IP 强制执行；凭据保管库（Credential Vault）在 dns+nft 下启用透明 TLS MITM 代理，按 host 注入托管密钥——真实凭据永远不进沙箱工作负载。K8s 下把主容器 NET_ADMIN 收走，只有 sidecar 能改网络规则。

五、接入实施全流程

5.1 本地五分钟起步

# 生成示例配置并启动生命周期服务器（Docker 运行时）
uvx opensandbox-server init-config ~/.sandbox.toml --example docker
uvx opensandbox-server

# pip install opensandbox
import asyncio
from opensandbox import Sandbox, WriteEntry

async def main():
    sandbox = await Sandbox.create("alpine")
    try:
        exe = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(exe.output)                       # 流式读输出
        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.sh", data="#!/bin/sh<br/>echo hi", mode=0o755)
        ])
        content = await sandbox.files.read_file("/tmp/hello.sh")
        print(content)
    finally:
        await sandbox.destroy()

asyncio.run(main())

SDK 覆盖 Python / TS(JS) / Java·Kotlin / C#(.NET) / Go 五门语言；osb CLI 管日常操作（sandbox/command/file/egress/skills 五组子命令）；opensandbox-mcp 包能把整个沙箱变成 Claude Code、Cursor 里的 MCP 工具——给 Agent 配执行环境的最短路径。

5.2 Kubernetes 生产部署

前提：K8s 1.21.1+、Helm 3、节点具备容器运行时（用 FastSandbox 还需节点有 KVM）。官方按组件拆了 Helm chart，安装顺序有讲究：

顺序	Chart	说明
1	base	集群级 CRD 与 RBAC：sandbox.opensandbox.io（BatchSandbox/Pool/SandboxSnapshot）+ sandbox.fast.io
2	opensandbox-controller	调和 BatchSandbox/Pool/SandboxSnapshot
3	fast-sandbox（可选）	Firecracker 运行时控制面 + 节点运行时（Deployment+DaemonSet）；必须装在 server 之前
4	ingress-gateway	K8s 部署必需：沙箱 Pod 只有 ClusterIP，客户端流量从这里进
5	opensandbox-server	生命周期 REST API；需配 API Key 鉴权，持久化可选 PostgreSQL

用 umbrella chart 一条 release 搞定时顺序自动处理。生产化要点：服务器鉴权必须开（无鉴权模式仅限本地开发）；快照/模板元数据量大了切 PostgreSQL；出口策略挂 sidecar 时给 sidecar 单独配资源；fast-sandbox 节点要确认 /dev/kvm 可用并关注嵌套虚拟化场景；官方镜像发布在 Docker Hub/GHCR/阿里云 ACR 三处且带 Cosign 签名，供应链上可以直接验签。

5.3 应用侧接入模式

给 Agent 框架做工具时，推荐把「沙箱生命周期」封成一个长会话池：创建（或从预热池取）→ 执行循环（commands.run 流式、files 读写、code 上下文）→ 空闲 pause / 到期 destroy。暂停恢复用 sandbox.pause() / resume()（ID 不变，端点恢复后要重新解析）；要「克隆现场」用快照：从运行中沙箱建 snapshot，再按 snapshotId 起新沙箱，Docker/BatchSandbox 路径均支持。examples 目录里有 Claude Code、Codex CLI、DeerFlow 在沙箱里跑的完整参考实现，以及 Playwright/Chrome、VS Code Web、桌面自动化的暴露样例——沙箱里任何监听端口都能通过入口网关变成可访问端点。

六、对比与选型

方案	定位	隔离形态	自托管	适合谁
OpenSandbox	沙箱平台（API+控制面+数据面）	容器 → microVM 可切换	完整开源	要自建执行基建的团队
E2B	商用云（Runtime 栈开源）	Firecracker microVM	有（Embed/企业版）	快速起步、不想运维
Daytona	沙箱平台	容器为主	部分开源	开发环境场景
k8s agent-sandbox	编排标准（CRD）	委托 RuntimeClass	开源	已有 K8s、自建平台层
Modal	云函数平台	容器/microVM（闭源）	否	只要算力不要基建

OpenSandbox 的差异化在三处：协议中立（多语言 SDK + OpenAPI 契约 + MCP，Agent 框架无论什么技术栈都能接）、运行时可切换（Docker 起步、K8s 批量、Firecracker 高密度，一套 API 不换代码）、网络控制纵深（入口网关 + 出口策略 + 凭据保管库，把「沙箱能访问什么」做成了一等 API）。当前限制：FastSandbox 路径不支持卷挂载与部分创建参数；Firecracker 形态对节点有 KVM 要求；项目年轻（2025-12 开源），API 仍在快速演进，升级要盯 release notes 与 oseps/ 增强提案。

参考资料

• 项目仓库：https://github.com/opensandbox-group/OpenSandbox （README、ROADMAP.md）
• 架构总览：https://github.com/opensandbox-group/OpenSandbox/blob/main/docs/architecture/index.md
• Kubernetes 部署指南：https://github.com/opensandbox-group/OpenSandbox/blob/main/docs/deployment/index.md
• 暂停恢复指南（pause-resume）、安全容器指南（secure-container）、凭据保管库（credential-vault）：仓库 docs/guides/
• 沙箱生命周期 / execd / egress OpenAPI 规范：仓库 specs/ 目录
• CNCF Landscape 收录与 OpenSSF Best Practices（项目 12588）：https://landscape.cncf.io