INTEGRITY Dokumentace

← Sandbox SDK / sandbox / api

Zálohy

Vytvářejte snímky adresářů sandboxu v daném okamžiku a obnovujte je pomocí překryvů copy-on-write.

Metody

createBackup()

Vytvoří časový snímek adresáře a nahraje ho do úložiště R2.

await sandbox.createBackup(options: BackupOptions): Promise<DirectoryBackup>

Parametry:

Vrací: Promise<DirectoryBackup> obsahující:

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

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

// Create a backup of /workspace
const backup = await sandbox.createBackup({ dir: "/workspace" });

// Later, restore the backup
await sandbox.restoreBackup(backup);
import { getSandbox } from "@cloudflare/sandbox";

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

// Create a backup of /workspace
const backup = await sandbox.createBackup({ dir: "/workspace" });

// Later, restore the backup
await sandbox.restoreBackup(backup);

Jak to funguje:

V produkčním prostředí:

  1. Kontejner vytvoří z adresáře komprimovaný archiv squashfs.
  2. Kontejner nahraje archiv přímo do R2 pomocí předpodepsané URL.
  3. Metadata se ukládají spolu s archivem v R2.
  4. Lokální archiv se následně smaže.

S localBucket: true (lokální vývoj):

  1. Kontejner vytvoří z adresáře komprimovaný archiv squashfs.
  2. Archiv se nahraje přímo do BACKUP_BUCKET R2 binding.
  3. Metadata se ukládají spolu s archivem v R2.
  4. Lokální archiv se následně smaže.

Vyhazuje:

restoreBackup()

Obnoví dříve vytvořenou zálohu do adresáře.

await sandbox.restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>

Parametry:

Vrací: Promise<RestoreBackupResult> obsahující:

// Create a named backup with 24-hour TTL
const backup = await sandbox.createBackup({
	dir: "/workspace",
	name: "before-refactor",
	ttl: 86400,
});

// Store the handle for later use
await env.KV.put(`backup:${userId}`, JSON.stringify(backup));
// Create a named backup with 24-hour TTL
const backup = await sandbox.createBackup({
	dir: "/workspace",
	name: "before-refactor",
	ttl: 86400,
});

// Store the handle for later use
await env.KV.put(`backup:${userId}`, JSON.stringify(backup));

Jak to funguje:

V produkčním prostředí:

  1. Metadata se stáhnou z R2 a zkontroluje se TTL. Pokud vypršela, vyvolá se chyba (s 60sekundovou rezervou).
  2. Kontejner stáhne archiv přímo z R2 pomocí předpodepsané URL.
  3. Kontejner připojí archiv squashfs pomocí FUSE overlayfs.

S localBucket: true (lokální vývoj):

  1. Metadata se stahují z BACKUP_BUCKET R2 binding a kontroluje se TTL.
  2. Archiv se stáhne z vazby R2.
  3. Archiv se rozbalí do cílového adresáře pomocí unsquashfs.

Vyhazuje:

Způsoby použití

Vyloučit soubory z .gitignore

Použijte useGitignore pro vyloučení souborů odpovídajících .gitignore pravidla (například node_modules/ nebo dist/) ze zálohy. Tím se u git repozitářů zmenší velikost zálohy.

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

// Exclude gitignored files from the backup
const backup = await sandbox.createBackup({
	dir: "/workspace",
	useGitignore: true,
});

// Without useGitignore (default), all files are included
const fullBackup = await sandbox.createBackup({
	dir: "/workspace",
});
const sandbox = getSandbox(env.Sandbox, "my-sandbox");

// Exclude gitignored files from the backup
const backup = await sandbox.createBackup({
	dir: "/workspace",
	useGitignore: true,
});

// Without useGitignore (default), all files are included
const fullBackup = await sandbox.createBackup({
	dir: "/workspace",
});

Pokud adresář neleží uvnitř repozitáře git, useGitignore nemá žádný účinek a jsou zahrnuty všechny soubory. Pokud useGitignore je true ale git není v kontejneru nainstalovaný, BackupCreateError je vyvolána.

Checkpoint a obnovení

Používejte zálohy jako kontrolní body před rizikovými operacemi.

// Save checkpoint before risky operation
const checkpoint = await sandbox.createBackup({ dir: "/workspace" });

try {
	await sandbox.exec("npm install some-experimental-package");
	await sandbox.exec("npm run build");
} catch (error) {
	// Restore to the checkpoint if something goes wrong
	await sandbox.restoreBackup(checkpoint);
}
// Save checkpoint before risky operation
const checkpoint = await sandbox.createBackup({ dir: "/workspace" });

try {
	await sandbox.exec("npm install some-experimental-package");
	await sandbox.exec("npm run build");
} catch (error) {
	// Restore to the checkpoint if something goes wrong
	await sandbox.restoreBackup(checkpoint);
}

Zpracování chyb

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

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

try {
	const backup = await sandbox.createBackup({ dir: "/workspace" });
	console.log(`Backup created: ${backup.id}`);
} catch (error) {
	if (error.code === "INVALID_BACKUP_CONFIG") {
		console.error("Configuration error:", error.message);
	} else if (error.code === "BACKUP_CREATE_FAILED") {
		console.error("Backup failed:", error.message);
	}
}
import { getSandbox } from "@cloudflare/sandbox";

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

try {
	const backup = await sandbox.createBackup({ dir: "/workspace" });
	console.log(`Backup created: ${backup.id}`);
} catch (error) {
	if (error.code === "INVALID_BACKUP_CONFIG") {
		console.error("Configuration error:", error.message);
	} else if (error.code === "BACKUP_CREATE_FAILED") {
		console.error("Backup failed:", error.message);
	}
}

Chování

Vynucování TTL

ttl hodnota určuje, kdy je záloha považována za expirovanou. SDK toto vynucuje na pouze čas obnovy : při volání restoreBackup(), SDK načte metadata zálohy z R2 a zkontroluje, zda uplynula platnost TTL. Pokud ano, obnovení se odmítne s chybou BACKUP_EXPIRED chyba.

TTL ne automaticky mazal objekty z R2. Archivy záloh a metadata s vypršenou platností zůstávají v R2 bucketu, dokud je neodstraníte. Pro automatické čištění objektů s vypršenou platností nastavte Pravidlo životního cyklu objektu R2 na vašem záložním bucketu. Bez pravidla životního cyklu budou expirované zálohy nadále zabírat úložiště R2.

Typy

BackupOptions

interface BackupOptions {
	dir: string;
	name?: string;
	ttl?: number;
	useGitignore?: boolean;
	localBucket?: boolean;
}

Pole:

DirectoryBackup

interface DirectoryBackup {
	readonly id: string;
	readonly dir: string;
}

Pole:

RestoreBackupResult

interface RestoreBackupResult {
	success: boolean;
	dir: string;
	id: string;
}

Pole: