INTEGRITY Документация

← Sandbox SDK / sandbox

Начало работы

Создание первого приложения с помощью Sandbox SDK, безопасной среды для выполнения кода. В этом руководстве вы создадите Worker, который может выполнять код Python и работать с файлами в изолированных контейнерах.

Предварительные требования

  1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗.
  2. Установка Node.js ↗.

менеджер версий Node.js

Используйте менеджер версий Node, например Volta ↗ или nvm ↗ чтобы избежать проблем с правами доступа и переключать версии Node.js. Wrangler, о котором пойдёт речь далее в этом руководстве, требует версию Node 16.17.0 или более поздней версии.

Убедитесь, что Docker запущен локально

Sandbox SDK использует Docker ↗ чтобы собирать образы контейнеров вместе с вашим Worker.

Docker должен быть запущен локально при выполнении wrangler deploy. Большинству пользователей проще всего установить Docker, следуя документация по установке Docker Desktop ↗. Другие инструменты, такие как Colima ↗ тоже может подойти.

Проверить, что Docker работает корректно, можно с помощью команды docker info команду в терминале. Если 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 каталог со всем необходимым:

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");
	},
};

Основные понятия:

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 и контейнер:

npx wrangler deploy

Это сделает следующее:

  1. Создание образа контейнера с помощью Docker
  2. Отправьте его в Container Registry Cloudflare
  3. Разверните Worker по всему миру

Проверка статуса развертывания:

npx wrangler containers list

5. Проверка развёртывания

Откройте URL вашего Worker (указан в выводе развёртывания):

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

Теперь ваш sandbox развёрнут и может выполнять код в изолированных контейнерах.

Общие сведения о конфигурации

Ваш 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.

Следующие шаги

Теперь, когда песочница работает, изучите её дополнительные возможности: