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

← Sandbox SDK / sandbox / configuration

Переменные окружения

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

Переменные конфигурации SDK

Эти переменные окружения определяют поведение Sandbox SDK. Задайте их как Worker vars в вашем wrangler.jsonc файл. SDK считывает их из привязок окружения Worker.

SANDBOX_TRANSPORT

Тип "http" | "websocket" | "rpc"
По умолчанию "http"

Определяет протокол передачи данных для взаимодействия SDK с контейнером. Транспорт RPC мультиплексирует все операции через одно постоянное соединение, что позволяет избежать ограничения на подзапросы при выполнении множества операций SDK в рамках одного запроса.

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	}
}
[vars]
SANDBOX_TRANSPORT = "rpc"

Полное руководство с допустимыми режимами транспорта, вопросами производительности и инструкциями по миграции см. в Режимы транспорта.

COMMAND_TIMEOUT_MS

Тип number (миллисекунды)
По умолчанию Нет (без тайм-аута)

Задаёт глобальный тайм-аут по умолчанию для каждой exec() вызов. Если это значение задано, любая команда, превышающая эту длительность, вызывает ошибку на стороне вызывающего кода и закрывает соединение.

Для каждой команды timeout на exec() и уровня сессии commandTimeoutMs на createSession() оба переопределяют это значение. Подробнее о приоритете тайм-аутов см. Выполнение команд: тайм-ауты.

{
	"vars": {
		"COMMAND_TIMEOUT_MS": "30000"
	}
}
[vars]
COMMAND_TIMEOUT_MS = "30000"

Три способа задать переменные окружения

Sandbox SDK предлагает три способа задания переменных окружения, каждый из которых подходит для своих задач:

1. На уровне Sandbox с помощью setEnvVars()

Задайте переменные окружения глобально для всех команд в sandbox:

const sandbox = getSandbox(env.Sandbox, "my-sandbox");

// Set once, available for all subsequent commands
await sandbox.setEnvVars({
	DATABASE_URL: env.DATABASE_URL,
	API_KEY: env.API_KEY,
});

await sandbox.exec("python migrate.py"); // Has DATABASE_URL and API_KEY
await sandbox.exec("python seed.py"); // Has DATABASE_URL and API_KEY

// Unset variables by passing undefined
await sandbox.setEnvVars({
	API_KEY: "new-key", // Updates API_KEY
	OLD_SECRET: undefined, // Unsets OLD_SECRET
});

Когда использовать: Вам нужны одни и те же переменные окружения для нескольких команд.

Удаление переменных: Передайте undefined или null чтобы сбросить переменные окружения:

await sandbox.setEnvVars({
	API_KEY: 'new-key',     // Sets API_KEY
	OLD_SECRET: undefined,  // Unsets OLD_SECRET
	DEBUG_MODE: null        // Unsets DEBUG_MODE
});

2. Для отдельной команды через параметры exec()

Передайте переменные окружения для конкретной команды:

await sandbox.exec("node app.js", {
	env: {
		NODE_ENV: "production",
		PORT: "3000",
	},
});

// Also works with startProcess()
await sandbox.startProcess("python server.py", {
	env: {
		DATABASE_URL: env.DATABASE_URL,
	},
});

Когда использовать: Вам нужны разные переменные окружения для разных команд, или вы хотите переопределить переменные уровня sandbox.

3. На уровне сессии с помощью createSession()

Создайте изолированный сеанс с собственными переменными окружения:

const session = await sandbox.createSession({
	env: {
		DATABASE_URL: env.DATABASE_URL,
		SECRET_KEY: env.SECRET_KEY,
	},
});

// All commands in this session have these vars
await session.exec("python migrate.py");
await session.exec("python seed.py");

Когда использовать: Вам нужны изолированные контексты выполнения с разными переменными окружения, работающие одновременно.

Удаление переменных окружения

Sandbox SDK поддерживает удаление переменных окружения, если передать undefined или null значения. Это позволяет использовать идиоматичные шаблоны JavaScript для управления конфигурацией:

await sandbox.setEnvVars({
	// Set new values
	API_KEY: 'new-key',
	DATABASE_URL: env.DATABASE_URL,

	// Unset variables (removes them from the environment)
	OLD_API_KEY: undefined,
	TEMP_TOKEN: null
});

До этого изменения: Передача undefined значения приведут к ошибке во время выполнения.

После этого изменения: undefined и null значения запускают unset VARIABLE_NAME в оболочке.

Варианты использования удаления переменных

Удаляйте конфиденциальные данные после использования:

// Use a temporary token
await sandbox.setEnvVars({ TEMP_TOKEN: 'abc123' });
await sandbox.exec('curl -H "Authorization: $TEMP_TOKEN" api.example.com');

// Clean up the token
await sandbox.setEnvVars({ TEMP_TOKEN: undefined });

Условная настройка окружения:

await sandbox.setEnvVars({
	API_KEY: env.API_KEY,
	DEBUG_MODE: env.NODE_ENV === 'development' ? 'true' : undefined,
	PROFILING: env.ENABLE_PROFILING ? 'true' : undefined
});

Сбросьте настройки до системных значений по умолчанию:

// Unset to fall back to container's default NODE_ENV
await sandbox.setEnvVars({ NODE_ENV: undefined });

Типичные паттерны

Передача секретов Worker в песочницу

Безопасно передавайте секреты из своего Worker в песочницу. Сначала задайте секреты с помощью Wrangler:

wrangler secret put OPENAI_API_KEY
wrangler secret put DATABASE_URL

Затем передайте их в свою песочницу:

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

interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	OPENAI_API_KEY: string;
	DATABASE_URL: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = getSandbox(env.Sandbox, "user-sandbox");

		// Option 1: Set globally for all commands
		await sandbox.setEnvVars({
			OPENAI_API_KEY: env.OPENAI_API_KEY,
			DATABASE_URL: env.DATABASE_URL,
		});
		await sandbox.exec("python analyze.py");

		// Option 2: Pass per-command
		await sandbox.exec("python analyze.py", {
			env: {
				OPENAI_API_KEY: env.OPENAI_API_KEY,
			},
		});

		return Response.json({ success: true });
	},
};

Объединение переменных по умолчанию и специфичных переменных

const defaults = { NODE_ENV: "production", LOG_LEVEL: "info" };

await sandbox.exec("npm start", {
	env: { ...defaults, PORT: "3000", API_KEY: env.API_KEY },
});

Несколько изолированных сессий

Одновременный запуск разных задач с разными переменными окружения:

// Production database session
const prodSession = await sandbox.createSession({
	env: { DATABASE_URL: env.PROD_DATABASE_URL },
});

// Staging database session
const stagingSession = await sandbox.createSession({
	env: { DATABASE_URL: env.STAGING_DATABASE_URL },
});

// Run migrations on both concurrently
await Promise.all([
	prodSession.exec("python migrate.py"),
	stagingSession.exec("python migrate.py"),
]);

Настройте режим транспорта

Задайте SANDBOX_TRANSPORT в вашем Worker vars для переключения между транспортами HTTP, WebSocket и RPC. Подробнее о том, когда и как настраивать каждый транспорт, см. Режимы транспорта.

Учётные данные для монтирования бакета

При монтировании S3-совместимого объектного хранилища SDK использует s3fs-fuse под капотом, что требует учётных данных в стиле AWS. Для R2 создайте API-токены в панели управления Cloudflare и передайте их, используя имена переменных окружения AWS:

Получите API-токены R2:

  1. Перейдите в R2 > Обзор ↗ в панели управления Cloudflare
  2. Выберите Управление API-токенами R2
  3. Создайте токен с Object Read & Write разрешения
  4. Скопируйте Access Key ID и Secret Access Key

Задайте учётные данные как секреты Worker:

wrangler secret put AWS_ACCESS_KEY_ID
# Paste your R2 Access Key ID

wrangler secret put AWS_SECRET_ACCESS_KEY
# Paste your R2 Secret Access Key

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

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

interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	AWS_ACCESS_KEY_ID: string;
	AWS_SECRET_ACCESS_KEY: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = getSandbox(env.Sandbox, "data-processor");

		// Credentials automatically detected from environment
		await sandbox.mountBucket("my-r2-bucket", "/data", {
			endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
		});

		// Access mounted bucket using standard file operations
		await sandbox.exec("python", { args: ["process.py", "/data/input.csv"] });

		return Response.json({ success: true });
	},
};

SDK автоматически определяет AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY из окружения вашего Worker при вызове mountBucket() без явных учётных данных.

Явная передача учётных данных (если используются пользовательские имена секретов):

await sandbox.mountBucket("my-r2-bucket", "/data", {
	endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: env.R2_ACCESS_KEY_ID,
		secretAccessKey: env.R2_SECRET_ACCESS_KEY,
	},
});

См. Руководство по подключению бакетов для получения полной документации по монтированию бакетов.

Приоритет переменных окружения

Если одна и та же переменная задана на нескольких уровнях, приоритет имеет наиболее конкретный уровень:

  1. На уровне команды (наивысший) - Передаётся в exec() или startProcess() параметры
  2. Уровень песочницы или сессии - Задаётся с помощью setEnvVars()
  3. Контейнер по умолчанию - Встроено в образ Docker с помощью ENV
  4. Значение по умолчанию системы (низший) - Значения по умолчанию операционной системы

Пример:

// In Dockerfile: ENV NODE_ENV=development

// Sandbox-level
await sandbox.setEnvVars({ NODE_ENV: "staging" });

// Command-level overrides all
await sandbox.exec("node app.js", {
	env: { NODE_ENV: "production" }, // This wins
});