Жизненный цикл песочницы

Песочница представляет собой изолированную среду выполнения, в которой запускается ваш код. Каждая песочница:

Имеет уникальный идентификатор (sandbox ID)
Содержит изолированную файловую систему
Выполняется в выделенном контейнере Linux
Сохраняет состояние, пока контейнер активен
Существует как Cloudflare Durable Object

Состояния жизненного цикла

Создание

Песочница создаётся при первом обращении к её идентификатору:

const sandbox = getSandbox(env.Sandbox, "user-123");
await sandbox.exec('echo "Hello"'); // First request creates sandbox

Активно

Контейнер песочницы работает и обрабатывает запросы. Всё состояние остаётся доступным: файлы, запущенные процессы, сеансы оболочки и переменные окружения.

Простой

После периода бездействия (по умолчанию 10 минут, настраивается через sleepAfter), контейнер останавливается, чтобы освободить ресурсы. Когда приходит следующий запрос, запускается новый контейнер. Всё предыдущее состояние теряется, и среда возвращается в исходное состояние.

Примечание: Контейнеры с keepAlive: true никогда не переходят в состояние простоя: они автоматически отправляют heartbeat-пинги каждые 30 секунд, чтобы избежать вытеснения.

Уничтожение

Песочницы явно уничтожаются или автоматически очищаются:

await sandbox.destroy();
// All files, processes, and state deleted permanently

Время жизни и состояние контейнера

Состояние песочницы существует, только пока активен контейнер. Понимание этого крайне важно для создания надёжных приложений.

Пока контейнер активен (обычно от нескольких минут до нескольких часов активности):

Файлы, записанные в /workspace, /tmp, /home остаются доступны
Фоновые процессы продолжают работать
Сессии shell сохраняют свою рабочую директорию и окружение
Контексты Code interpreter сохраняют переменные и импорты

Когда контейнер останавливается (из-за бездействия или явного удаления):

Все файлы удаляются
Все процессы завершаются
Все состояние оболочки (shell) сбрасывается
Все контексты интерпретатора кода очищаются

Следующий запрос создаёт новый контейнер с чистым окружением.

Стратегии именования

Sandbox для каждого пользователя

const sandbox = getSandbox(env.Sandbox, `user-${userId}`);

Используйте этот паттерн для интерактивных сред, плейграундов и блокнотов, где каждый пользователь возвращается в свою активную рабочую область.

Sandbox для каждой сессии

const sessionId = `session-${Date.now()}-${Math.random()}`;
const sandbox = getSandbox(env.Sandbox, sessionId);
// Later:
await sandbox.destroy();

Используйте этот паттерн для разового выполнения, CI/CD и тестов, которым нужна чистая среда.

Sandbox для каждой задачи

const sandbox = getSandbox(env.Sandbox, `build-${repoName}-${commit}`);

Идемпотентные операции с чётким сопоставлением задач и sandbox. Подходит для сборок, конвейеров и фоновых задач.

Маршрутизация запросов

Первый запрос к песочнице определяет её географическое расположение. Последующие запросы направляются в то же расположение.

Для глобальных приложений:

Вариант 1: несколько песочниц на пользователя с суффиксом региона (user-123-us, user-123-eu)
Вариант 2: одна песочница на пользователя (проще, но у части пользователей выше задержка)

Управление жизненным циклом

Когда уничтожать

try {
	const sandbox = getSandbox(env.Sandbox, sessionId);
	await sandbox.exec("npm run build");
} finally {
	await sandbox.destroy(); // Clean up temporary sandboxes
}

Уничтожайте, когда: Сессия завершается, задача выполнена, ресурсы больше не нужны

Не уничтожайте: Персональные среды, долгоживущие сервисы

Управление контейнерами keepAlive

Контейнеры с keepAlive: true требуют явного управления, так как не завершаются по тайм-ауту автоматически:

const sandbox = getSandbox(env.Sandbox, 'persistent-task', {
  keepAlive: true
});

// Later, when done with long-running work
await sandbox.setKeepAlive(false); // Allow normal timeout behavior
// Or explicitly destroy:
await sandbox.destroy();

Обработка перезапусков контейнера

Контейнеры перезапускаются после бездействия или сбоев. Спроектируйте приложение так, чтобы оно корректно обрабатывало потерю состояния:

// Check if required files exist before using them
const files = await sandbox.listFiles("/workspace");
if (!files.includes("data.json")) {
	// Reinitialize: container restarted and lost previous state
	await sandbox.writeFile("/workspace/data.json", initialData);
}

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

Совместимость версий

SDK автоматически проверяет, что версия вашего пакета npm соответствует версии образа контейнера Docker. Несовпадение версий может привести к поломке функций или их непредсказуемому поведению.

Что происходит:

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

Когда вы можете увидеть предупреждения:

Вы обновили пакет npm (npm install @cloudflare/sandbox@latest) но забыли обновить FROM строку в вашем Dockerfile

Как исправить: Обновите Dockerfile в соответствии с версией вашего npm-пакета. Например, если используется @cloudflare/[email protected]:

# Default image (JavaScript/TypeScript)
FROM docker.io/cloudflare/sandbox:0.7.0

# Or Python image if you need Python support
FROM docker.io/cloudflare/sandbox:0.7.0-python

См. Справочник по Dockerfile для получения сведений о вариантах образов и расширении базового образа.