跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

快速入门

最后更新 查看 MarkdownAgent 设置

使用 Sandbox SDK 构建你的第一个应用——一个安全的代码执行环境。在本指南中，你将创建一个 Worker，可在隔离的 container 中执行 Python 代码并处理文件。

前提条件

  1. 注册 Cloudflare 账户 ↗。
  2. 安装 Node.js ↗。

Node.js 版本管理器

使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器，以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。

确保本地 Docker 正在运行

Sandbox SDK 使用 Docker ↗ 与你的 Worker 一起构建 container 镜像。

当您运行 wrangler deploy 时，必须在本地运行 Docker。对于大多数人来说，安装 Docker 的最佳方式是按照安装 Docker Desktop 的文档 ↗进行操作。其他工具（如 Colima ↗）也可能有效。

您可以通过在终端中运行 docker info 命令来检查 Docker 是否正常运行。如果 Docker 正在运行，该命令将成功执行。如果 Docker 未运行，docker info 命令将挂起或返回包含 "Cannot connect to the Docker daemon" 消息的错误。

1. 创建新项目

创建新的 Sandbox SDK 项目：

npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal

这会创建一个包含所需全部内容的 my-sandbox 目录：

  • src/index.ts - 集成了沙箱的 Worker
  • wrangler.jsonc - Workers 与 Containers 的配置
  • Dockerfile - Container 环境定义
cd my-sandbox

2. 探索模板

该模板提供了一个最小化的 Worker，演示核心沙箱能力：

import { getSandbox, proxyToSandbox, type Sandbox } from "@cloudflare/sandbox";

export { Sandbox } from "@cloudflare/sandbox";

type Env = {
	Sandbox: DurableObjectNamespace<Sandbox>;
};

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);

		// Get or create a sandbox instance. For user-facing apps,
		// derive this ID from the authenticated user.
		const sandbox = getSandbox(env.Sandbox, "my-sandbox");

		// Execute Python code
		if (url.pathname === "/run") {
			const result = await sandbox.exec('python3 -c "print(2 + 2)"');
			return Response.json({
				output: result.stdout,
				error: result.stderr,
				exitCode: result.exitCode,
				success: result.success,
			});
		}

		// Work with files
		if (url.pathname === "/file") {
			await sandbox.writeFile("/workspace/hello.txt", "Hello, Sandbox!");
			const file = await sandbox.readFile("/workspace/hello.txt");
			return Response.json({
				content: file.content,
			});
		}

		return new Response("Try /run or /file");
	},
};

关键概念：

  • getSandbox() - 按 ID 获取或创建沙箱实例。使用稳定 ID 可重新连接到同一沙箱。在面向用户的应用中，应将 ID 限定到单个用户。
  • sandbox.exec() - 在沙箱中执行 shell 命令，并捕获 stdout、stderr 和退出码。
  • sandbox.writeFile() / readFile() - 在沙箱文件系统中写入和读取文件。

3. 本地测试

启动开发服务器：

npm run dev
# If you expect to have multiple sandbox instances, you can increase `max_instances`.

测试端点：

# Execute Python code
curl http://localhost:8787/run

# File operations
curl http://localhost:8787/file

你应看到包含命令输出和文件内容的 JSON 响应。

4. 部署到生产

部署你的 Worker 和 container：

npx wrangler deploy

这将：

  1. 使用 Docker 构建 container 镜像
  2. 将其推送到 Cloudflare 的 Container Registry
  3. 在全球部署你的 Worker

检查部署状态：

npx wrangler containers list

5. 测试你的部署

访问你的 Worker URL（在部署输出中显示）：

# Replace with your actual URL
curl https://my-sandbox.YOUR_SUBDOMAIN.workers.dev/run

你的沙箱现已部署，可在隔离的 container 中执行代码。

理解配置

你的 wrangler.jsonc 将三部分连接在一起：

{
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
			"instance_type": "lite",
			"max_instances": 1,
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}
[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"
instance_type = "lite"
max_instances = 1

[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

[[migrations]]
new_sqlite_classes = [ "Sandbox" ]
tag = "v1"

有关环境变量、密钥和自定义镜像等详细配置选项，请参阅 Wrangler 配置参考。

后续步骤

现在你已有可工作的沙箱，可以探索更多能力：

这篇文档对您有帮助吗？