INTEGRITY Dokumentace

← Sandbox SDK / sandbox / configuration

Proměnné prostředí

Konfiguraci, tajné klíče a nastavení runtime předávejte do sandboxů pomocí proměnných prostředí.

Konfigurační proměnné SDK

Tyto proměnné prostředí určují chování Sandbox SDK. Nastavte je jako Worker vars ve vašem wrangler.jsonc soubor. SDK je načítá z vazeb prostředí Workeru.

SANDBOX_TRANSPORT

Typ "http" | "websocket" | "rpc"
Výchozí "http"

Určuje transportní protokol pro komunikaci mezi SDK a kontejnerem. Přenos RPC multiplexuje všechny operace přes jediné trvalé připojení, čímž se vyhne limity subrequestů při provádění mnoha operací SDK v rámci jednoho požadavku.

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

Úplného průvodce s platnými režimy transportu, doporučeními k výkonu a pokyny k migraci najdete v Režimy transportu.

COMMAND_TIMEOUT_MS

Typ number (milisekundy)
Výchozí Žádné (bez časového limitu)

Nastaví globální výchozí časový limit pro každý exec() volání. Pokud je nastaveno, každý příkaz, který tuto dobu překročí, vyvolá chybu na straně volajícího a ukončí spojení.

Pro jednotlivé příkazy timeout na exec() a na úrovni relace commandTimeoutMs na createSession() obě tuto hodnotu přepisují. Podrobnosti o prioritě timeoutů najdete v Spouštění příkazů: časové limity.

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

Tři způsoby nastavení proměnných prostředí

Sandbox SDK nabízí tři způsoby nastavení proměnných prostředí, každý vhodný pro jiný případ použití:

1. Na úrovni sandboxu pomocí setEnvVars()

Nastavte proměnné prostředí globálně pro všechny příkazy v sandboxu:

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

Použijte, když: Potřebujete stejné proměnné prostředí pro více příkazů.

Rušení proměnných: Předejte undefined nebo null ke zrušení nastavení proměnných prostředí:

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

2. U jednotlivých příkazů pomocí voleb exec()

Předejte proměnné prostředí pro konkrétní příkaz:

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

Použijte, když: Potřebujete pro různé příkazy jiné proměnné prostředí, nebo chcete přepsat proměnné na úrovni sandboxu.

3. Na úrovni session pomocí createSession()

Vytvořte izolovanou relaci s vlastními proměnnými prostředí:

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

Použijte, když: Potřebujete izolované kontexty spouštění s různými proměnnými prostředí, které běží souběžně.

Rušení proměnných prostředí

Sandbox SDK umožňuje zrušit nastavení proměnných prostředí předáním undefined nebo null hodnoty. To umožňuje používat idiomatické vzory JavaScriptu pro správu konfigurace:

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

Před touto změnou: Předání undefined hodnoty by vyvolaly chybu za běhu.

Po této změně: undefined a null hodnoty spustí unset VARIABLE_NAME v shellu.

Případy použití pro zrušení proměnných

Po použití odstraňte citlivá data:

// 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 });

Podmíněné nastavení prostředí:

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

Obnovte výchozí nastavení systému:

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

Běžné vzory

Předejte tajné klíče Workeru do sandboxu

Bezpečně předejte secrets z vašeho Workeru do sandboxu. Nejprve nastavte secrets pomocí Wrangler:

wrangler secret put OPENAI_API_KEY
wrangler secret put DATABASE_URL

Poté je předejte svému sandboxu:

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

Kombinace výchozích a specifických proměnných

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

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

Více izolovaných relací

Souběžně spouštějte různé úlohy s různými proměnnými prostředí:

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

Nakonfigurujte přenosový režim

Nastavte SANDBOX_TRANSPORT ve vašem Workeru vars k přepínání mezi přenosem HTTP, WebSocket a RPC. Podrobnosti o tom, kdy a jak nastavit jednotlivé přenosy, najdete v Režimy transportu.

Přihlašovací údaje pro připojení bucketu

Při připojování úložiště objektů kompatibilního s S3 SDK používá s3fs-fuse interně, což vyžaduje přihlašovací údaje ve stylu AWS. Pro R2 vygenerujte API tokeny v Cloudflare dashboardu a zadejte je pomocí názvů proměnných prostředí ve stylu AWS:

Získejte tokeny R2 API:

  1. Přejděte na R2 > Přehled ↗ v dashboardu Cloudflare
  2. Vyberte Správa tokenů R2 API
  3. Vytvořte token s Object Read & Write oprávnění
  4. Zkopírujte Access Key ID a Secret Access Key

Nastavte přihlašovací údaje jako tajné klíče Workeru:

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

Připojte buckety s automatickou detekcí přihlašovacích údajů:

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 automaticky rozpoznává AWS_ACCESS_KEY_ID a AWS_SECRET_ACCESS_KEY z prostředí vašeho Workeru při volání mountBucket() bez explicitních přihlašovacích údajů.

Předávejte přihlašovací údaje explicitně (pokud používáte vlastní názvy tajných klíčů):

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

Viz Průvodce připojováním bucketů pro úplnou dokumentaci k připojování bucketů.

Priorita proměnných prostředí

Pokud je stejná proměnná nastavena na více úrovních, má přednost ta nejspecifičtější:

  1. Na úrovni příkazu (nejvyšší) - Předává se do exec() nebo startProcess() možnosti
  2. Na úrovni sandboxu nebo relace - Nastavte pomocí setEnvVars()
  3. Výchozí kontejner - Zabudováno do Docker image pomocí ENV
  4. Výchozí systémové nastavení (nejnižší) - Výchozí hodnoty operačního systému

Příklad:

// 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
});