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

← Sandbox SDK / sandbox / configuration

Конфигурация Wrangler

Минимальная конфигурация

Минимально необходимая конфигурация для использования Sandbox SDK:

{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": ["nodejs_compat"],
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}
name = "my-sandbox-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"

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

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

Обязательные настройки

Sandbox SDK работает на основе Cloudflare Containers. Конфигурация должна включать три раздела:

  1. контейнеры - Определите образ контейнера (среду выполнения)
  2. durable_objects.bindings - Привяжите Durable Object Sandbox к своему Worker
  3. миграции - Инициализируйте класс Durable Object

Минимальная конфигурация, показанная выше, включает все обязательные параметры. Подробные варианты настройки см. в Документация по настройке контейнеров.

Хранилище резервных копий

Чтобы использовать API для резервного копирования и восстановления, вам нужны привязка bucket R2 и учетные данные presigned URL. Контейнер загружает и выгружает архивы резервных копий напрямую в R2 и из R2 с помощью presigned URL, для чего требуются учетные данные API-токена R2.

1. Создайте бакет R2

npx wrangler r2 bucket create my-backup-bucket

2. Добавьте привязку и переменные окружения

{
	"vars": {
		"BACKUP_BUCKET_NAME": "my-backup-bucket",
		"CLOUDFLARE_ACCOUNT_ID": "<YOUR_ACCOUNT_ID>",
	},
	"r2_buckets": [
		{
			"binding": "BACKUP_BUCKET",
			"bucket_name": "my-backup-bucket",
		},
	],
}
[vars]
BACKUP_BUCKET_NAME = "my-backup-bucket"
CLOUDFLARE_ACCOUNT_ID = "<YOUR_ACCOUNT_ID>"

[[r2_buckets]]
binding = "BACKUP_BUCKET"
bucket_name = "my-backup-bucket"

3. Задайте учётные данные API R2 как секреты

npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY

Создайте токен API R2 в Панель управления Cloudflare ↗ в разделе R2 > Обзор > Управление API-токенами R2. Токену требуется Object Read & Write разрешения для вашего bucket с резервными копиями.

SDK использует эти учетные данные для создания предварительно подписанных URL, которые позволяют контейнеру передавать архивы резервных копий напрямую в R2 и из него. Полное руководство по настройке см. в разделе руководство по резервному копированию и восстановлению.

Устранение неполадок

Привязка не найдена

Ошибка: TypeError: env.Sandbox is undefined

Решение: Убедитесь, что ваш wrangler.jsonc включает привязку Durable Objects:

{
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
}
[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

Отсутствующие миграции

Ошибка: Durable Object не инициализирован

Решение: Добавьте миграции для класса Sandbox:

{
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}
[[migrations]]
new_sqlite_classes = [ "Sandbox" ]
tag = "v1"