INTEGRITY Dokumentace

← Sandbox SDK / sandbox

Začínáme

Vytvořte svou první aplikaci se Sandbox SDK - zabezpečeným prostředím pro spouštění kódu. V tomto průvodci vytvoříte Worker, který dokáže spouštět kód Python a pracovat se soubory v izolovaných kontejnerech.

Předpoklady

  1. Zaregistrujte si účet Cloudflare ↗.
  2. Nainstalujte Node.js ↗.

Správce verzí Node.js

Použijte správce verzí Node, jako je Volta ↗ nebo nvm ↗ abyste se vyhnuli problémům s oprávněními a mohli měnit verze Node.js. Wrangler, o kterém se dozvíte dále v této příručce, vyžaduje verzi Node 16.17.0 nebo novější.

Ujistěte se, že Docker běží lokálně

Sandbox SDK používá Docker ↗ pro sestavování image kontejnerů společně s vaším Workerem.

Docker musí lokálně běžet, když spouštíte wrangler deploy. Pro většinu lidí je nejlepším způsobem instalace Dockeru postupovat podle dokumentace k instalaci Docker Desktop ↗. Další nástroje, například Colima ↗ může také fungovat.

Že Docker běží správně, můžete ověřit spuštěním docker info příkaz v terminálu. Pokud Docker běží, příkaz proběhne úspěšně. Pokud Docker neběží, příkaz docker info se zasekne, nebo vrátí chybu obsahující zprávu „Cannot connect to the Docker daemon“.

1. Vytvořte nový projekt

Vytvořte nový projekt Sandbox SDK:

npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal

Tím se vytvoří my-sandbox adresář se vším, co potřebujete:

cd my-sandbox

2. Prozkoumejte šablonu

Šablona poskytuje minimální Worker, který demonstruje základní možnosti sandboxu:

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

Klíčové koncepty:

3. Otestujte lokálně

Spusťte vývojový server:

npm run dev
# If you expect to have multiple sandbox instances, you can increase `max_instances`.

Otestujte koncové body:

# Execute Python code
curl http://localhost:8787/run

# File operations
curl http://localhost:8787/file

Měli byste vidět odpovědi JSON s výstupem příkazu a obsahem souborů.

4. Nasaďte do produkce

Nasaďte svůj Worker a kontejner:

npx wrangler deploy

Tím dojde k následujícímu:

  1. Vytvořte obraz kontejneru pomocí Dockeru
  2. Nahrajte ho do Cloudflare Container Registry
  3. Nasaďte svůj Worker globálně

Zkontrolujte stav nasazení:

npx wrangler containers list

5. Otestujte nasazení

Otevřete URL adresu svého Workeru (zobrazenou ve výstupu nasazení):

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

Váš sandbox je nyní nasazený a umí spouštět kód v izolovaných kontejnerech.

Vysvětlení konfigurace

Váš wrangler.jsonc propojuje tři části dohromady:

{
	"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"

Podrobné možnosti konfigurace včetně proměnných prostředí, secrets a vlastních images najdete v Referenční dokumentace ke konfiguraci Wrangler.

Další kroky

Nyní, když máte funkční sandbox, prozkoumejte další možnosti: