上一篇用订单统计跑通了 OpenSandbox:应用创建沙箱,把文件传进去,执行 Python,再取回报告。从调用代码看,这只是几个 SDK 方法;但在这几个方法背后,环境的创建、程序的执行、文件的传输和资源的回收,分别由不同的组件完成。
这样的拆分和 Agent 的工作方式有关。Agent 通常需要根据上一步的结果继续尝试,环境要在多次操作之间保留文件和进程;与此同时,不同任务又需要各自的资源和回收边界。Docker 和 Kubernetes 提供了运行环境的基础,OpenSandbox 则在其上组织沙箱的创建、访问、执行和回收。理解它的架构,关键在于看清环境由谁管理、任务在哪里执行,以及两者如何衔接。
整体架构
管理与执行
先把一次任务分成两类操作。创建沙箱时,应用需要决定镜像、资源和存活时间;环境准备好后,应用才会上传文件、运行程序、读取结果。前一类操作管理环境,后一类操作使用环境。
如果这些请求都交给同一个中心进程,管理服务就需要同时处理容器创建和长时间的命令输出、文件传输。OpenSandbox 将两类职责分开:管理服务负责沙箱的创建、查询和回收,沙箱内部的 execd 负责命令与文件操作。 execd 是一个随沙箱启动的执行服务,客户端向它发送请求,它再调用环境里的程序、读写环境里的文件。
文档中把它们分别称为控制面和数据面。在本文中,可以将控制面理解为“管理环境的部分”,将数据面理解为“实际处理任务请求的部分”。先看整体关系:
1 | +---------------------+ |
图中的 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 | OpenSandbox/ |
其中,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 | sandbox_service=sandbox_service, |
其中,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 | server/opensandbox_server/ |
认证由中间件处理,路由接收并规范化请求,服务实现负责创建、删除等操作。以创建路由为例,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 | implementations = { |
这些服务遵循 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 | self._copy_execd_to_container(container, sandbox_id, platform) |
镜像与容器的关系如下:
1 | User image, e.g. python:3.12-slim |
具体复制时,管理服务先从 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 | Management Service --> Kubernetes API --> BatchSandbox |
这里的 BatchSandbox 把环境需求保存为集群中的资源对象。它的规格描述期望的镜像、资源和到期时间,状态则记录实际分配和运行情况。控制器反复比较期望与现状:缺少 Pod 就创建,需要分配资源就协调分配,再将观察到的结果写回。
这就是 Kubernetes 的控制循环。创建请求先留下需要什么环境的记录,控制器随后持续推动环境达到要求。 Pod 的调度、镜像拉取和容器启动可以分别耗时,管理服务通过资源状态了解进度,客户端再等待执行端点可用。它与 Docker 后端在创建调用中完成容器创建和启动的过程有所不同。
相应代码分别位于 server/opensandbox_server/services/k8s/batchsandbox_provider.py 和 kubernetes/internal/controller/batchsandbox_controller.go。前者构造资源,后者观察资源并推动 Pod 创建、分配和清理。
普通新建 Pod 时,execd 的安装通过初始化容器完成。初始化容器先于用户容器运行,使用 execd 镜像将程序复制到共享卷;用户容器挂载同一个卷,再运行启动脚本:
1 | Sandbox Pod |
这部分资源构造位于 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 | Without pool: request --> create Pod --> wait --> 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 | Pod(提前准备) |
这样,每次创建沙箱时就省去了新建 Pod 的等待。虚拟机模板中已装好 execd,应用仍通过它执行命令、读写文件。
Docker、Kubernetes 普通容器和模板化 microVM,交付环境的方式不同。它们能够共用上层接口,是因为管理服务和 SDK 围绕沙箱能力组织,而具体环境由后端负责。
隔离边界
环境的隔离程度由底层实现决定。普通容器与宿主机共享内核,microVM 使用独立的虚拟机环境;容器部署也可以结合 gVisor、Kata 等安全运行时。管理服务负责选择和配置这些机制,execd 则在选定的环境内部执行任务。将一个程序交给 execd,执行边界仍取决于沙箱使用的运行时和权限配置。
任务执行
命令与输出
环境交付完成后,任务就进入 execd 的职责范围。execd 是沙箱内部的 Go 服务,命令、文件和终端等接口都由它处理,因此可以直接使用沙箱内的程序和文件系统。
以 sandbox.commands.run("python /tmp/summarize.py") 为例,执行过程如下:
1 | SDK --> execd /command --> start Python process |
这次调用会向 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 | if event_type == "stdout": |
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 | 客户端访问 127.0.0.1:45000/proxy/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 | 应用向管理服务查询:沙箱 demo 的 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 | User container ---+ |
策略实现分为两个层次:
- 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 | delay = max(0.0, (expires_at - datetime.now(timezone.utc)).total_seconds()) |
定时器保存在管理服务进程里,服务重新启动后,需要扫描已有容器,结合标签和本地到期时间记录恢复清理安排。计算使用原来的绝对到期时间:尚未到期就继续等待,已经到期就触发清理。服务停机期间,进程内的定时器无法执行,回收也会相应延后。
Kubernetes 的 BatchSandbox 后端把到期时间写入资源的 spec.expireTime,由控制器观察并发起删除。回收工作由谁执行,取决于底层环境由谁管理。
客户端仍然可以主动清理。Python SDK 的 destroy() 组合了远端沙箱终止和本地连接关闭;单独关闭客户端连接,可以让远端环境继续保留。主动删除负责及时释放资源,到期回收则处理调用方未完成清理的情况,两者共同完成沙箱的生命周期管理。
任务全流程
从申请环境到释放资源,一次任务会依次经过前面介绍的几个组件。管理服务协调沙箱的创建与回收,SDK 查询访问地址并等待 execd 能够响应,随后通过 execd 上传文件、执行命令和取回结果。整体流程如下:
1 | Application / SDK Management Service Runtime / Controller execd |
小结
OpenSandbox 的架构围绕一次任务所需的环境展开:客户端提供一致的调用方式,管理服务协调生命周期,运行时负责交付环境,execd 在沙箱内处理执行请求,网络组件负责接入与访问控制。各层通过 API、运行时资源和访问地址衔接起来。
这样的分工让本机 Docker、Kubernetes 容器和模板化 microVM 可以在同一套沙箱接口下提供能力。它们的创建、网络和回收方式有所不同,上层应用仍可以围绕“申请环境、完成任务、保存结果、释放资源”组织工作。
理解这套架构,重点在于把请求和状态放回对应的位置:创建问题沿管理服务与运行时排查,执行问题沿 execd 与任务进程排查,访问问题沿地址解析和网络组件排查。组件之间的边界清楚了,后续阅读具体实现也就有了一条稳定的线索。