架构 · Cloudflare Sandbox SDK docs

Sandbox SDK 让你从 Workers 安全地执行不受信任的代码。它结合三项 Cloudflare 技术，提供安全、有状态且隔离的执行环境：

Workers - 调用 Sandbox SDK 的应用逻辑
Durable Objects - 具有唯一标识的持久 sandbox 实例
Containers - 实际运行代码的隔离 Linux 环境

架构概览

flowchart TB
    accTitle: Sandbox SDK Architecture
    accDescr: Three-layer architecture showing how Cloudflare Sandbox SDK combines Workers, Durable Objects, and Containers for secure code execution

    subgraph UserSpace["<b>Your Worker</b>"]
        Worker["Application code using the methods exposed by the Sandbox SDK"]
    end

    subgraph SDKSpace["<b>Sandbox SDK Implementation</b>"]
        DO["Sandbox Durable Object routes requests & maintains state"]
        Container["Isolated Ubuntu container executes untrusted code safely"]

        DO -->|HTTP API| Container
    end

    Worker -->|RPC call via the Durable Object stub returned by `getSandbox`| DO

    style UserSpace fill:#fff8f0,stroke:#f6821f,stroke-width:2px
    style SDKSpace fill:#f5f5f5,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5
    style Worker fill:#ffe8d1,stroke:#f6821f,stroke-width:2px
    style DO fill:#dce9f7,stroke:#1d8cf8,stroke-width:2px
    style Container fill:#d4f4e2,stroke:#17b26a,stroke-width:2px

第 1 层：客户端 SDK

你在 Workers 中使用的面向开发者的 API：

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const result = await sandbox.exec("python script.py");

用途：为所有 sandbox 操作提供简洁、类型安全的 TypeScript 接口。

第 2 层：Durable Object

管理 sandbox 生命周期与路由：

export class Sandbox extends DurableObject<Env> {
	// Extends Cloudflare Container for isolation
	// Routes requests between client and container
	// Manages preview URLs and state
}

用途：提供具有唯一标识的持久、有状态 sandbox 实例。

为何使用 Durable Objects：

持久标识 - 相同 sandbox ID 始终路由到同一实例
容器管理 - Durable Object 拥有并管理容器生命周期
地理分布 - Sandbox 在靠近用户的位置运行
自动扩展 - Cloudflare 管理预配

第 3 层：容器运行时

在隔离环境中执行代码，并具备完整 Linux 能力。

用途：安全执行不受信任的代码。

为何使用容器：

基于 VM 的隔离 - 每个 sandbox 在自己的 VM 中运行
完整环境 - Ubuntu Linux，包含 Python、Node.js、Git 等

通信传输

SDK 支持两种传输协议，用于 Durable Object 与容器之间的通信：

HTTP 传输（默认）

每个 SDK 方法都会向容器 API 发起单独的 HTTP 请求。简单可靠，适用于大多数用例。

// Default behavior - uses HTTP
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
await sandbox.exec("python script.py");

WebSocket 传输

通过单个持久 WebSocket 连接复用所有 SDK 调用。在并发执行大量操作时，可避免子请求限制。

通过在 Worker 配置中设置 SANDBOX_TRANSPORT 变量启用 WebSocket 传输：

{
	"vars": {
		"SANDBOX_TRANSPORT": "websocket"
	},
}

[vars]
SANDBOX_TRANSPORT = "websocket"

传输层对应用代码透明——无论使用哪种传输，所有 SDK 方法的工作方式都相同。有关何时使用各传输方式及配置示例，请参阅传输模式。

请求流程

当你执行命令时：

await sandbox.exec("python script.py");

HTTP 传输流程：

客户端 SDK 验证参数并向 Durable Object 发送 HTTP 请求
Durable Object 进行认证，并将 HTTP 请求转发到容器
容器运行时 验证输入、执行命令并捕获输出
响应经各层返回，并完成适当的错误转换

WebSocket 传输流程：

客户端 SDK 验证参数，并通过持久 WebSocket 连接发送请求
Durable Object 维护 WebSocket 连接，并复用并发请求
容器运行时 将 WebSocket 消息适配为 HTTP 风格的请求/响应
响应经同一 WebSocket 连接返回，并完成适当的错误转换

WebSocket 连接在首次 SDK 调用时建立，并在后续所有操作中复用，从而降低高频操作的开销。

架构