Sandbox 说明文档

# Cloudflare 沙箱 SDK 在 Cloudflare 边缘容器中进行安全隔离的代码执行。运行不受信任的代码、管理文件、暴露服务并与 AI 智能体集成。 **应用场景**: AI 代码执行、交互式开发环境、数据分析、CI/CD、代码解释器、多租户执行。 ## 架构 - 每个沙箱 = Durable Object + 容器 - 请求间持久化（相同的 ID = 相同的沙箱） - 隔离的文件系统/进程/网络 - 可配置的休眠/唤醒以优化成本 ## 快速入门 typescript import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox'; export { Sandbox } from '@cloudflare/sandbox'; type Env = { Sandbox: DurableObjectNamespace; }; export default { async fetch(request: Request, env: Env): Promise { // 关键：预览 URL 必须首先调用 proxyToSandbox const proxyResponse = await proxyToSandbox(request, env); if (proxyResponse) return proxyResponse; const sandbox = getSandbox(env.Sandbox, 'my-sandbox'); const result = await sandbox.exec('python3 -c "print(2 + 2)"'); return Response.json({ output: result.stdout }); } }; **wrangler.jsonc**: c { "name": "my-sandbox-worker", "main": "src/index.ts", "compatibility_date": "2025-01-01", // 新项目请使用当前日期 "containers": [{ "class_name": "Sandbox", "image": "./Dockerfile", "instance_type": "lite", // lite | standard | heavy "max_instances": 5 }], "durable_objects": { "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }] }, "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Sandbox"] }] } **Dockerfile**: dockerfile FROM docker.io/cloudflare/sandbox:latest RUN pip3 install --no-cache-dir pandas numpy matplotlib EXPOSE 8080 3000 # wrangler dev 所需 ## 核心 API - `getSandbox(namespace, id, options?)` → 获取/创建沙箱 - `sandbox.exec(command, options?)` → 执行命令 - `sandbox.readFile(path)` / `writeFile(path, content)` → 文件操作 - `sandbox.startProcess(command, options)` → 后台进程 - `sandbox.exposePort(port, options)` → 获取预览 URL - `sandbox.createSession(options)` → 隔离会话 - `sandbox.wsConnect(request, port)` → WebSocket 代理 - `sandbox.destroy()` → 终止容器 - `sandbox.mountBucket(bucket, path, options)` → 挂载 S3 存储 ## 关键规则 - 始终首先调用 `proxyToSandbox()` - 相同的 ID = 重用沙箱 - 使用 `/wo