0%

OpenSandbox 学习 02:核心架构

上一篇用订单统计跑通了 OpenSandbox:应用创建沙箱,把文件传进去,执行 Python,再取回报告。从调用代码看,这只是几个 SDK 方法;但在这几个方法背后,环境的创建、程序的执行、文件的传输和资源的回收,分别由不同的组件完成。

这样的拆分和 Agent 的工作方式有关。Agent 通常需要根据上一步的结果继续尝试,环境要在多次操作之间保留文件和进程;与此同时,不同任务又需要各自的资源和回收边界。Docker 和 Kubernetes 提供了运行环境的基础,OpenSandbox 则在其上组织沙箱的创建、访问、执行和回收。理解它的架构,关键在于看清环境由谁管理、任务在哪里执行,以及两者如何衔接。

整体架构

管理与执行

先把一次任务分成两类操作。创建沙箱时,应用需要决定镜像、资源和存活时间;环境准备好后,应用才会上传文件、运行程序、读取结果。前一类操作管理环境,后一类操作使用环境。

如果这些请求都交给同一个中心进程,管理服务就需要同时处理容器创建和长时间的命令输出、文件传输。OpenSandbox 将两类职责分开:管理服务负责沙箱的创建、查询和回收,沙箱内部的 execd 负责命令与文件操作。 execd 是一个随沙箱启动的执行服务,客户端向它发送请求,它再调用环境里的程序、读写环境里的文件。

文档中把它们分别称为控制面和数据面。在本文中,可以将控制面理解为“管理环境的部分”,将数据面理解为“实际处理任务请求的部分”。先看整体关系:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
       +---------------------+
| Application / SDK |
+---------------------+
| |
lifecycle | | commands / files
v |
Management Service |
| |
v |
Docker / Kubernetes |
| |
v v
+-----------------------------+
| Sandbox |
| execd --> task processes |
| --> task files |
+-----------------------------+

图中的 Management Service 就是管理服务,项目中称为 Lifecycle Server。创建成功后,客户端向管理服务查询 execd 的访问地址,后续命令和文件请求便发往这个地址。请求可以直接连接沙箱,也可以通过网关转发。

这样的分层把管理请求与任务流量分开。一个任务持续输出日志、另一个任务上传大文件时,数据可以由各自沙箱内的 execd 处理,管理服务继续负责环境的创建和回收。执行请求的承载能力也因此可以随着沙箱数量分散开来。

组件分工

有了这条主线,再看各个组件就容易一些:

架构位置 组件 核心职责
应用接入 SDK、CLI、MCP 服务 把程序、终端或 Agent 的操作转换为 API 请求
环境管理 管理服务 校验创建参数,调用运行时,查询状态,提供访问地址,管理生命周期
环境交付 Docker 或 Kubernetes 后端 创建容器或集群工作负载,将用户需要的环境运行起来
沙箱执行 execd 在沙箱内执行命令、操作文件、提供终端与运行指标
入站访问 Ingress 在 Kubernetes 部署中,将客户端请求转发到对应沙箱
出站控制 Egress 按策略控制沙箱访问外部网络,可配合凭据代理使用

这些组件按部署方式组合。本机 Docker 可以直接访问沙箱;集群通常需要网关;需要限制出站访问时,再配置 Egress。整体架构包含这些能力,具体部署只需启用所需的部分。

Agent 本身也可以运行在沙箱内。例如,业务应用创建一个安装了 Claude Code 的沙箱,再启动 Agent,由它调用模型、编辑文件和运行命令。也可以让 Agent 运行在外部,把某些任务交给沙箱执行。两种方式使用同一套环境管理能力,区别在于 Agent 程序放在哪里。

目录结构

前面的组件在仓库中也有各自的位置。阅读源码时,可以先按职责找到对应目录,再沿着请求进入具体实现。与本文主线相关的目录如下,省略了部分辅助目录和文件:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
OpenSandbox/
├── specs/ # 管理、执行与出站策略等公共接口定义
├── sdks/
│ ├── sandbox/ # 多语言沙箱 SDK
│ ├── code-interpreter/ # 基于沙箱的代码解释器 SDK
│ └── mcp/ # 面向 MCP 客户端的沙箱工具服务
├── cli/ # osb 命令行客户端
├── server/
│ └── opensandbox_server/ # 管理服务与运行时对接实现
├── components/
│ ├── execd/ # 沙箱内部的命令、文件和会话服务
│ ├── ingress/ # 入站网关与沙箱路由
│ ├── egress/ # 出站网络策略与凭据代理
│ └── internal/ # 运行时组件共用的 Go 辅助代码
├── kubernetes/
│ ├── apis/ # BatchSandbox、Pool 等自定义资源类型
│ ├── internal/ # 控制器、池分配与任务调度实现
│ └── cmd/ # 控制器、任务执行器等程序入口
├── manifests/charts/ # Helm 部署配置
├── console/ # 开发者控制台
├── tests/ # 跨语言 SDK 端到端测试
├── examples/ # 可运行示例
├── docs/ # 架构、使用和部署文档
└── oseps/ # 设计提案

其中,specs/ 定义各个服务对外提供的接口,sdks/ 和 cli/ 负责调用这些接口,server/ 与 components/ 则分别实现环境管理和沙箱执行、网络访问等能力。把这几处连起来,就能对应上前面的管理与执行两条路径。

server/ 和 kubernetes/ 的区别尤其值得先分清。 管理服务在 server/ 中接收创建请求,并把沙箱需求转换为容器操作或 Kubernetes 资源;kubernetes/ 中的控制器运行在集群侧,观察资源并创建或分配 Pod。管理服务负责提交需求,控制器负责持续落实需求,两者通过 Kubernetes API 协作。

接下来先从 specs/ 和 sdks/ 看应用如何表达一次沙箱操作,再进入管理服务和底层组件,理解请求如何一步步完成。

接口与客户端

统一接口

同样是运行一段 Python,本机 Docker 和 Kubernetes 集群需要的底层操作不同。应用如果直接依赖容器和集群的管理接口,就需要理解容器 ID、Pod、端口映射等细节。其中,Pod 是 Kubernetes 中承载容器的运行单元。

OpenSandbox 先定义沙箱层面的接口,再由后端实现底层操作。应用关心的是沙箱 ID、镜像、资源和任务,而容器与集群的差异由管理服务及运行时后端处理。

仓库中的 specs/ 保存这些公共接口的定义:

接口定义 主要内容 处理组件
specs/sandbox-lifecycle.yml 沙箱创建、查询、删除、续期和访问地址查询等 管理服务
specs/execd-api.yaml 命令执行、文件操作和代码执行等 execd
specs/egress-api.yaml 出站策略与凭据管理等 Egress

因此,“统一接口”也包含明确的职责边界。SDK 可以把不同接口组织到一个 Sandbox 对象上,实际请求仍然发送给负责相应功能的服务。

客户端封装

以 Python SDK 为例,sandbox.commands、sandbox.files 和 sandbox.kill() 看起来属于同一个对象,内部却有各自的客户端。

sdks/sandbox/python/src/opensandbox/sandbox.py 在创建沙箱对象时,把它们分别组织起来。下面是构造参数中的连续节选:

1
2
3
4
sandbox_service=sandbox_service,
filesystem_service=factory.create_filesystem_service(execd_endpoint),
command_service=factory.create_command_service(execd_endpoint),
health_service=factory.create_health_service(execd_endpoint),

其中,sandbox_service 连接管理服务;文件、命令和健康检查客户端使用管理服务返回的 execd 地址。这个结构把前面的管理与执行分工保留在客户端内部,应用调用时则可以保持简单。

因此,一个 Sandbox 对象主要保存沙箱 ID、连接配置和各类服务客户端。远端环境有自己的生命周期,关闭这个本地对象的连接,环境仍然可以继续运行,之后也能通过沙箱 ID 重新连接。

创建过程中,SDK 会先调用管理服务,再查询 execd 的访问地址,默认还要等待 /ping 健康检查通过,才把沙箱对象交给应用。这里分别确认了两件事:底层环境已经创建,客户端也能访问执行服务。例如,Docker 容器启动后,里面的 execd 还需要时间启动监听,SDK 会继续等待它响应。如果创建请求成功、后续连接检查却失败,SDK 会尝试删除已经创建的沙箱,减少遗留资源。

默认检查确认的是 execd 能够响应。假如应用还要等待沙箱里的 Web 服务或其他业务程序完成初始化,可以提供自己的健康检查,判断任务所需的服务是否准备好。

命令运行时,应用往往希望及时看到日志。为此,execd 会在同一个 HTTP 连接中陆续发送标准输出、标准错误和执行结果,这种传输方式称为 SSE。Python SDK 在 sdks/sandbox/python/src/opensandbox/adapters/command_adapter.py 中接收这些消息,把它们整理成应用可以读取的日志和结果,也支持在输出到达时调用应用提供的回调函数。

从创建环境到获取执行结果,SDK 把与管理服务、execd 的交互组织在一起。应用只需调用 Sandbox.create()、sandbox.commands.run() 等方法,就能完成这些操作。

管理服务

请求处理

沙箱创建从管理服务开始。它需要判断请求是否有权限、参数是否合法,以及当前后端是否支持指定的能力,然后才能真正创建环境。

管理服务使用 FastAPI,代码按职责组织:

1
2
3
4
5
server/opensandbox_server/
middleware/ request authentication
api/ routes and request models
services/ lifecycle and runtime integration
repositories/ snapshot and template records

认证由中间件处理,路由接收并规范化请求,服务实现负责创建、删除等操作。以创建路由为例,server/opensandbox_server/api/lifecycle.py 完成校验后,将请求交给服务层:

1
return await sandbox_service.create_sandbox(request)

Docker 的镜像检查、端口分配等逻辑继续放在 Docker 后端中;Kubernetes 的资源构造和集群调用放在 Kubernetes 后端中。这样,公共路由可以围绕沙箱 API 工作,各个运行时的细节也有自己的位置。

运行时选择

管理服务通过 runtime.type 选择运行时。server/opensandbox_server/services/factory.py 为 Docker 和 Kubernetes 注册了对应实现,其中 Kubernetes 分支还组合了 Fast Sandbox 后端。选择过程的关键代码如下,省略了配置读取和错误处理:

1
2
3
4
5
6
7
8
9
10
11
12
implementations = {
"docker": DockerSandboxService,
"kubernetes": KubernetesSandboxService,
}

if selected_type == "kubernetes":
implementation = KubernetesSandboxService(config=active_config)
return CompositeSandboxService(
implementation,
FastSandboxService(active_config, k8s_client=implementation.k8s_client),
)
return implementations[selected_type](config=active_config)

这些服务遵循 server/opensandbox_server/services/sandbox_service.py 中的 SandboxService 接口。创建、查询、删除和访问地址解析等操作,因此可以从同一个管理接口进入,再交给对应的后端。上面出现的 CompositeSandboxService 负责在 Kubernetes 容器和模板化虚拟机之间分派请求,后面再介绍这两条交付路径。

这层抽象统一的是沙箱操作的含义,具体能力仍取决于后端。 例如,Docker 可以调用本机 Docker Engine 创建容器,Kubernetes 则要通过集群资源和控制器交付环境;资源池、暂停恢复等能力也有各自的实现条件。

沙箱的交付

Docker 容器

运行时选定后,下一个问题是如何把普通镜像变成可以通过 API 操作的沙箱。Python 镜像里有 Python,Node.js 镜像里有 Node.js,但这些镜像通常没有 OpenSandbox 的命令和文件接口。

Docker 后端采用的方式,是将用户环境与执行服务分别准备:用户镜像提供语言和依赖,execd 镜像提供执行程序及启动脚本。管理服务创建目标容器后,将 execd 安装进去,再启动容器。

server/opensandbox_server/services/docker/runtime.py 中的两行代码体现了这个过程:

1
2
self._copy_execd_to_container(container, sandbox_id, platform)
self._install_bootstrap_script(container, sandbox_id, platform)

镜像与容器的关系如下:

1
2
3
4
5
6
7
8
9
10
User image, e.g. python:3.12-slim
|
| Docker creates container
v
+------------------------------------------+
| Sandbox container |
| Python + user dependencies |
| execd + bootstrap.sh | <-- copied from execd image
| task processes + task files |
+------------------------------------------+

具体复制时,管理服务先从 execd 镜像启动一个临时容器,通过 Docker 的归档接口取出程序和启动脚本。提取完毕后,临时容器就被删除;管理服务将缓存的程序和脚本写入目标容器的 /opt/opensandbox/,execd 最终运行在用户的沙箱容器内。

server/opensandbox_server/services/docker/container_ops.py 将 Linux 沙箱容器的入口设置为 /opt/opensandbox/bootstrap.sh。脚本负责启动 execd 和请求中指定的入口命令。环境启动后,后续的 commands.run() 再由 execd 启动对应的任务进程;上传的文件也保存在这个容器中。

这个设计让应用可以选择已有的运行环境镜像,也让 execd 能独立构建和升级。语言依赖仍由用户镜像提供,命令和文件接口由 execd 提供,两者在沙箱中配合工作。这里以 Linux 容器路径为例,镜像仍需满足启动脚本、系统和架构等兼容要求。

Kubernetes 工作负载

使用 Kubernetes 后端时,管理服务会把沙箱的镜像、资源和存活时间等需求写入 Kubernetes 资源,通过 Kubernetes API 提交给集群。相应的控制器持续观察这些资源,再创建或分配承载沙箱的 Pod。

当前实现支持不同的 Kubernetes 工作负载提供方。以仓库自带控制器使用的 BatchSandbox 为例,它是一个描述沙箱需求的 Kubernetes 自定义资源,包含镜像、资源、到期时间等信息。

1
2
3
4
5
6
Management Service --> Kubernetes API --> BatchSandbox
|
Controller watches
|
v
Sandbox Pod

这里的 BatchSandbox 把环境需求保存为集群中的资源对象。它的规格描述期望的镜像、资源和到期时间,状态则记录实际分配和运行情况。控制器反复比较期望与现状:缺少 Pod 就创建,需要分配资源就协调分配,再将观察到的结果写回。

这就是 Kubernetes 的控制循环。创建请求先留下需要什么环境的记录,控制器随后持续推动环境达到要求。 Pod 的调度、镜像拉取和容器启动可以分别耗时,管理服务通过资源状态了解进度,客户端再等待执行端点可用。它与 Docker 后端在创建调用中完成容器创建和启动的过程有所不同。

相应代码分别位于 server/opensandbox_server/services/k8s/batchsandbox_provider.py 和 kubernetes/internal/controller/batchsandbox_controller.go。前者构造资源,后者观察资源并推动 Pod 创建、分配和清理。

普通新建 Pod 时,execd 的安装通过初始化容器完成。初始化容器先于用户容器运行,使用 execd 镜像将程序复制到共享卷;用户容器挂载同一个卷,再运行启动脚本:

1
2
3
4
5
6
7
8
9
10
Sandbox Pod
execd-installer (init container, runs first)
|
| copies execd + bootstrap.sh
v
shared emptyDir volume: opensandbox-bin
|
| mounted at /opt/opensandbox
v
user container --> bootstrap.sh --> execd + user entrypoint

这部分资源构造位于 server/opensandbox_server/services/k8s/provider_common.py。它与 Docker 的目标相同,都是把 execd 放进用户环境,交付方式则遵循各自运行时的机制。上面的图展示普通新建 Pod 的路径,预热池会使用事先准备好的 Pod。

预热池

如果每次创建都要等待 Pod 调度和启动,Agent 的短任务可能花很多时间在准备环境上。预热池把这部分工作提前完成:先启动一批可用 Pod,请求到来时再分配。

Pool 控制器会提前准备一批 Pod,并维持池中的可用数量。创建沙箱时,BatchSandbox 可以指定使用哪个池,由池分配已经准备好的 Pod,省去临时创建 Pod 的等待。

不过,提前准备好的 Pod 还需要接收本次请求指定的环境变量和入口命令。为此,Pod 中运行着任务执行器(task-executor)。分配完成后,控制器把这些配置交给它,由它启动 bootstrap.sh,再由启动脚本拉起 execd 和用户指定的程序。execd 启动后,应用就可以调用 commands.run() 执行命令,或通过文件 API 上传和下载文件。task-executor 负责把分配到的环境启动起来,execd 负责接收应用后续的命令和文件请求。

1
2
3
Without pool: request --> create Pod --> wait --> run task
With pool: prepare Pods in advance
request --> allocate ready Pod --> run task

预热的代价是需要保留空闲容量,并明确资源归还后的处理方式。kubernetes/apis/sandbox/v1alpha1/pool_types.go 定义的默认回收策略是 Delete,归还的 Pod 会被删除,再由池补足容量;Noop 则不对归还的 Pod 做回收操作。因此,环境分配、容量补充和任务之间的清理需要一起设计,才能持续交付可用的沙箱。

Fast Sandbox

前面的预热池分配的是 Pod。如果希望以轻量虚拟机作为每个任务的执行环境,OpenSandbox 还可以接入独立项目 opensandbox-group/fast-sandbox。这个项目使用 Firecracker 创建 microVM(轻量虚拟机),并提前准备好环境模板和运行容量,减少创建沙箱时的准备工作。本文将这套虚拟机沙箱平台称为 Fast Sandbox。

OpenSandbox 中的 FastSandboxService 是连接这套平台的服务实现,代码位于 server/opensandbox_server/services/fast_sandbox/。它接收沙箱创建、删除和地址查询等操作,再调用 Fast Sandbox 平台完成相应工作;虚拟机的实际创建和运行由该平台负责。

这条路径在 runtime.type = "kubernetes" 下使用。server/opensandbox_server/services/composite_service.py 根据请求内容分派:指定 templateId 时,交给 FastSandboxService,从预先构建的模板创建虚拟机沙箱;恢复这类沙箱的快照时,也交给同一服务。后续查询和删除等操作则通过沙箱 ID 的 fsb- 前缀识别。

Fast Sandbox 会提前准备好一批 Pod,用来承载虚拟机。创建沙箱时,平台直接利用这些已有 Pod 的容量启动虚拟机,分配给本次任务。

这里,一个沙箱对应一个轻量虚拟机,一个 Pod 可以承载多个沙箱:

1
2
3
4
Pod(提前准备)
├── 虚拟机 A:沙箱 A,内含 execd 和任务程序
├── 虚拟机 B:沙箱 B,内含 execd 和任务程序
└── 剩余容量:供后续沙箱使用

这样,每次创建沙箱时就省去了新建 Pod 的等待。虚拟机模板中已装好 execd,应用仍通过它执行命令、读写文件。

Docker、Kubernetes 普通容器和模板化 microVM,交付环境的方式不同。它们能够共用上层接口,是因为管理服务和 SDK 围绕沙箱能力组织,而具体环境由后端负责。

隔离边界

环境的隔离程度由底层实现决定。普通容器与宿主机共享内核,microVM 使用独立的虚拟机环境;容器部署也可以结合 gVisor、Kata 等安全运行时。管理服务负责选择和配置这些机制,execd 则在选定的环境内部执行任务。将一个程序交给 execd,执行边界仍取决于沙箱使用的运行时和权限配置。

任务执行

命令与输出

环境交付完成后,任务就进入 execd 的职责范围。execd 是沙箱内部的 Go 服务,命令、文件和终端等接口都由它处理,因此可以直接使用沙箱内的程序和文件系统。

以 sandbox.commands.run("python /tmp/summarize.py") 为例,执行过程如下:

1
2
3
4
SDK --> execd /command --> start Python process
^ |
| | stdout / stderr / exit
+---------- SSE events --------+

这次调用会向 execd 的 /command 接口发送执行请求。components/execd/pkg/web/router.go 将请求交给 components/execd/pkg/web/controller/command.go 中的处理函数,完成参数校验,再调用 components/execd/pkg/runtime/command.go 中的执行逻辑。

接下来,execd 启动命令,并在运行过程中收集输出。以 Linux 上的前台命令为例,进程的标准输出和标准错误会分别写入文件;execd 同时跟踪这两个文件,把新增内容转换成输出事件,陆续发送给客户端。

execd 为每次执行分配命令 ID,并在进程启动后保存进程与执行状态。进程结束后,等待逻辑先确认输出读取结束,再发送成功或错误信息。客户端由此可以在运行期间持续收到输出,结束时再获取最终结果。

SDK 通过 SSE 接收这些事件,再还原为应用使用的结果。sdks/sandbox/python/src/opensandbox/adapters/converter/execution_event_dispatcher.py 中的分派逻辑如下,省略了其他事件分支:

1
2
3
4
5
6
7
8
if event_type == "stdout":
await self._handle_stdout(event_node, timestamp)
elif event_type == "stderr":
await self._handle_stderr(event_node, timestamp)
elif event_type == "error":
await self._handle_error(event_node, timestamp)
elif event_type == "execution_complete":
await self._handle_execution_complete(event_node, timestamp)

stdout 和 stderr 被整理成日志,错误事件被写入执行结果中的错误字段,完成事件记录执行结束信息。应用既可以在事件到达时处理输出,也可以等待 SDK 收集最终结果。

前台执行时,应用可以一边接收输出,一边等待命令结束。如果选择后台执行,命令启动后 SDK 就会返回,程序继续在沙箱里运行。应用随后可以查询命令状态、读取日志,了解运行进度,并在命令结束后检查执行结果。

这里检查的是命令是否执行成功。命令结束后,沙箱通常还会继续运行,供后续操作使用。比如统计脚本报错退出,Agent 可以在原来的沙箱里查看错误、修改脚本并重新运行。因此,沙箱显示“运行中”,并不能说明其中的脚本已经执行成功。

文件与会话

文件操作同样由 execd 在沙箱内部完成。应用上传的脚本和数据写入沙箱文件系统,程序产生的报告也先保存在那里,随后由应用下载或写入其他存储。

对于需要连续分析数据的任务,文件只是需要保留的一部分状态,程序里的变量也可能希望延续到下一次执行。execd 因此提供了不同的执行方式:

  • 普通命令:/command 启动独立命令,适合运行脚本或 CLI。沙箱里的文件可以保留,某次 Python 进程中的变量会随着该进程结束。
  • Shell 会话:/session 为连续的 shell 操作保留会话,适合需要延续工作目录和环境的操作。
  • 代码上下文:代码执行接口借助 Jupyter 内核保存上下文,让后续代码继续使用前面定义的变量。对应的内核和语言依赖需要由镜像准备。

可见,环境的存活、文件的保留和解释器上下文的保留,是三个不同层次的问题。应用可以根据任务选择执行方式。

如果运行的是完整 Agent,execd 可以负责启动 Agent 进程;Agent 随后在沙箱内部调用模型和本地工具。它执行的每一条本地命令,并不都需要重新经过 OpenSandbox 的管理接口。

进程管理

Agent 可能启动测试程序、开发服务器和其他子进程。长期运行的沙箱需要处理进程退出和信号传递,否则容易积累未回收的子进程,停止环境时也难以让各个进程正确结束。

当前实现支持由 execd 充当容器的初始进程,也就是 PID 1。启用该模式时,启动脚本将控制权交给 execd,由它负责管理用户入口进程、转发信号并回收子进程。相关入口位于 components/execd/bootstrap.sh,Linux 实现位于 components/execd/pkg/runtime/initmode_linux.go。

这使 execd 除了提供执行 API,还能承担沙箱内的进程管理工作。不过,某条通过 API 执行的命令失败,与用户入口进程结束仍是不同事件,不能仅凭一次命令结果推断整个沙箱的状态。

网络访问

地址解析

同一个沙箱服务,在 Docker 中可能通过宿主机映射端口访问,在 Kubernetes 中可能通过 Pod 地址或网关访问。SDK 如果把这些地址规则写死,运行环境一变,应用就需要跟着修改。

OpenSandbox 将“服务在哪里”交给管理服务解析。客户端先用沙箱 ID 和容器内端口查询访问地址,再向返回的地址发送请求。这个结果还可以携带访问所需的请求头。

这样,应用只需指定沙箱 ID 和目标端口,具体连接哪个地址,由管理服务确定。SDK 连接 execd 时也是如此:先向管理服务查询它的访问地址,再向这个地址发送命令和文件请求。

以 Docker 的 bridge 模式为例。假设沙箱里启动了一个监听 3000 端口的 Web 服务,应用需要从宿主机访问它。容器内的 3000 和宿主机的 3000 属于不同的网络环境,直接访问宿主机的这个端口,并不会连接到沙箱中的服务。

OpenSandbox 利用 execd 转发这类请求。创建沙箱时,Docker 已经将 execd 的容器端口映射到宿主机端口。假设映射到的是 45000,查询沙箱的 3000 端口时,管理服务就会返回 127.0.0.1:45000/proxy/3000。请求的路径如下:

1
2
3
4
5
6
7
8
9
客户端访问 127.0.0.1:45000/proxy/3000
|
| Docker 端口映射
v
沙箱内的 execd(44772 端口)
|
| 根据 /proxy/3000 转发
v
沙箱内的 Web 服务(127.0.0.1:3000)

这里的 45000 是示例端口,实际值在创建沙箱时分配。/proxy/3000 告诉 execd:把请求转给同一个沙箱里的 3000 端口。这样,沙箱里后来启动的 HTTP 服务也能通过 execd 已有的端口映射对外提供访问。

对应的地址拼接代码位于 server/opensandbox_server/services/docker/networking.py。其中,execd_host_port 是 execd 映射到宿主机的端口,port 是要访问的沙箱内端口:

1
endpoint = Endpoint(endpoint=f"{public_host}:{execd_host_port}/proxy/{port}")

当前实现为容器内的 8080 端口单独保留了宿主机端口映射,查询它时会直接返回映射地址。应用使用管理服务返回的地址即可,无需自行判断采用哪条访问路径。

入站网关

前面的 Docker 示例通过宿主机端口访问沙箱。换成 Kubernetes 集群,沙箱分布在不同节点的 Pod 中,外部应用通常无法直接访问这些 Pod 的地址。OpenSandbox 为此提供入站网关 Ingress,作为客户端访问沙箱的统一入口。

继续以沙箱内 3000 端口的 Web 服务为例。配置网关后,应用向管理服务查询这个端口,得到的是网关地址,以及告诉网关“访问哪个沙箱、哪个端口”的信息。应用随后按这些信息向网关发送请求,网关再连接沙箱里的 Web 服务。

例如,采用请求头传递目标时,访问沙箱 demo 的 3000 端口会携带下面的请求头。这里的 demo 仅作示意,实际使用创建沙箱时返回的 ID:

1
OpenSandbox-Ingress-To: demo-3000

请求经过的路径如下:

1
2
3
4
5
6
7
8
9
10
11
应用向管理服务查询:沙箱 demo 的 3000 端口
|
v
管理服务返回:网关地址 + 目标请求头
|
v
应用向网关发送 HTTP 请求
|
| 网关根据 demo-3000 查找沙箱地址
v
沙箱 demo 的 Web 服务(3000 端口)

网关能找到沙箱,是因为它持续读取集群中的沙箱位置信息。以 BatchSandbox 为例,控制器将 Pod 地址写入资源的注解,网关监听这些资源并在本地缓存地址。收到请求时,它先按沙箱 ID 查到地址,再连接请求中指定的端口。地址查询实现在 components/ingress/pkg/sandbox/batchsandbox_provider.go,请求转发实现在 components/ingress/pkg/proxy/。

访问 execd 也走同样的流程,只是目标端口换成 execd 的端口。命令输出和文件内容通过网关返回给 SDK,终端连接则通过网关转发 WebSocket。管理服务负责告诉客户端如何访问沙箱,实际任务数据经由网关传输。

请求头是传递目标的一种方式,网关也支持从 URL 路径中读取沙箱 ID 和端口。启用访问认证后,返回结果还可能包含令牌或带签名的地址。应用应使用管理服务返回的完整连接信息,SDK 会据此发送相应请求。

出站控制

入站网关解决客户端访问沙箱的问题,出站控制则处理沙箱访问外部服务的问题。Agent 可能需要访问模型 API、代码仓库和软件源,同时又需要限制其他访问目标。只在应用代码中约定允许访问哪些地址,很难覆盖沙箱内启动的所有程序。

容器部署中的 Egress 以辅助容器的方式运行,与用户容器共享网络命名空间,也就是共享网络接口和网络规则。它在这条网络路径上实施策略,让沙箱内不同程序的访问都能受到控制。

Docker 后端先启动 Egress,再用 container:<egress-container-id> 作为用户容器的网络模式,让两个容器进入同一套网络环境。同时,用户容器移除 NET_ADMIN,修改网络规则所需的权限留给 Egress。Kubernetes 则利用同一个 Pod 内容器共享网络的机制。

1
2
3
User container ---+
| shared network namespace
Egress sidecar ---+ DNS redirect + optional nftables rules --> external service

策略实现分为两个层次:

  • DNS 过滤:处理域名解析,拒绝被禁止的域名。
  • 网络层过滤:dns+nft 模式进一步使用 nftables 控制连接,并根据允许域名的解析结果维护可访问地址。

DNS 过滤决定某个域名能否解析,网络层规则进一步约束实际连接。例如,程序直接连接 IP 时不需要查询 DNS,单靠域名解析过滤无法覆盖这条路径。因此,网络隔离的范围需要结合实际启用的模式判断。

域名解析和网络规则的主要实现分别位于 components/egress/pkg/dnsproxy/ 与 components/egress/nft.go。它们将创建时声明的网络策略落实到沙箱的网络环境中,运行期间也能通过策略 API 更新规则。

凭据代理建立在出站访问路径上。启用相关功能后,Egress 可以为匹配的外部请求注入凭据,让沙箱中的程序访问服务,同时减少真实密钥暴露在任务环境中的机会。Fast Sandbox 则使用按沙箱区分策略的共享出站组件,部署形态与每沙箱一个辅助容器有所不同。

状态与回收

状态归属

管理服务需要返回沙箱状态,但实际运行的环境在 Docker 或 Kubernetes 中。把两边各维护一份独立的运行状态,很容易在重启、超时或创建失败时出现分歧。当前架构以底层运行时资源作为沙箱运行状态的主要依据:Docker 后端读取容器状态和标签,Kubernetes 后端读取相应工作负载的规格与状态。管理服务再将这些信息转换为公共 API 中的沙箱状态。

信息 主要保存位置
Docker 沙箱身份、初始配置与运行状态 容器标签和 Docker 状态
Docker 后续修改的元数据、到期时间与生命周期转换记录 管理服务本地的 JSON 元数据文件
Kubernetes 沙箱需求、分配和运行情况 Kubernetes 资源及其状态
管理服务拥有的快照记录与模板目录 SQLite 或配置的 PostgreSQL
任务生成的文件 沙箱文件系统,或挂载的存储

Docker 的标签不能在容器运行时直接修改,所以续期和元数据更新另外保存在 JSON 文件中,读取时优先采用更新后的记录。这部分实现在 server/opensandbox_server/services/docker/metadata.py,默认目录为 ~/.opensandbox/metadata/。因此,Docker 后端恢复管理状态时,既需要容器信息,也需要保留这些本地记录。

快照记录与模板目录通过数据库保存,任务文件则需要在沙箱删除前取回,或写入持久化存储。理解信息各自保存在哪里,才能判断服务重启后能恢复什么,以及删除沙箱会影响哪些数据。

到期回收

任务可能异常结束,客户端也可能断开连接,因此沙箱不能只依赖客户端主动删除。创建请求指定存活时长时,管理服务会将它转换为明确的到期时间,后端根据这个时间安排回收;选择手动清理的沙箱则由调用方负责删除。

Docker 后端在 server/opensandbox_server/services/docker/docker_service.py 中计算到期时间,并用定时器触发清理。定时器的关键代码如下,省略了加锁和替换旧定时器等部分:

1
2
3
4
5
6
7
delay = max(0.0, (expires_at - datetime.now(timezone.utc)).total_seconds())
timer = Timer(
delay,
self._expire_sandbox,
args=(sandbox_id,),
kwargs=expire_kwargs or None,
)

定时器保存在管理服务进程里,服务重新启动后,需要扫描已有容器,结合标签和本地到期时间记录恢复清理安排。计算使用原来的绝对到期时间:尚未到期就继续等待,已经到期就触发清理。服务停机期间,进程内的定时器无法执行,回收也会相应延后。

Kubernetes 的 BatchSandbox 后端把到期时间写入资源的 spec.expireTime,由控制器观察并发起删除。回收工作由谁执行,取决于底层环境由谁管理。

客户端仍然可以主动清理。Python SDK 的 destroy() 组合了远端沙箱终止和本地连接关闭;单独关闭客户端连接,可以让远端环境继续保留。主动删除负责及时释放资源,到期回收则处理调用方未完成清理的情况,两者共同完成沙箱的生命周期管理。

任务全流程

从申请环境到释放资源,一次任务会依次经过前面介绍的几个组件。管理服务协调沙箱的创建与回收,SDK 查询访问地址并等待 execd 能够响应,随后通过 execd 上传文件、执行命令和取回结果。整体流程如下:

1
2
3
4
5
6
7
8
9
10
11
Application / SDK      Management Service       Runtime / Controller       execd
| | | |
|--- create ----------->|--- provision ---------->| |
| | |--- start -------->|
|<-- ID + status -------| | |
|--- resolve endpoint ->| | |
|<-- address + headers -| | |
|--- health check --------------------------------------------------->|
|--- upload / command / download ------------------------------------>|
|<-- file contents / output / result ---------------------------------|
|--- delete ----------->|--- release ------------>| |

小结

OpenSandbox 的架构围绕一次任务所需的环境展开:客户端提供一致的调用方式,管理服务协调生命周期,运行时负责交付环境,execd 在沙箱内处理执行请求,网络组件负责接入与访问控制。各层通过 API、运行时资源和访问地址衔接起来。

这样的分工让本机 Docker、Kubernetes 容器和模板化 microVM 可以在同一套沙箱接口下提供能力。它们的创建、网络和回收方式有所不同,上层应用仍可以围绕“申请环境、完成任务、保存结果、释放资源”组织工作。

理解这套架构,重点在于把请求和状态放回对应的位置:创建问题沿管理服务与运行时排查,执行问题沿 execd 与任务进程排查,访问问题沿地址解析和网络组件排查。组件之间的边界清楚了,后续阅读具体实现也就有了一条稳定的线索。