备份

创建沙箱目录的时间点快照，并从 R2 恢复它们。

有关设置、恢复工作流以及生成缓存的排除，请参阅 备份与恢复。有关 overlay 语义，请参阅 目录备份。

创建目录快照，并将其上传到 R2。

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

参数：

• options — 备份配置（见 BackupOptions）：
  • dir（必填）— 要备份的绝对路径。必须位于 /workspace、/home、/tmp、/var/tmp 或 /app 下。
  • name（可选）— 可读名称。最长 256 个字符。控制字符会被拒绝。
  • ttl（可选）— 生存时间（秒）。默认：259200（3 天）。必须为正数。
  • gitignore（可选）— 为 true 时，如果 dir 位于 git 仓库内，则排除匹配 .gitignore 规则的路径。默认：false。如果目录不在 git 仓库内，则不应用 git 排除。如果未安装 git，SDK 会记录警告并在没有基于 git 的排除的情况下继续。
  • excludes（可选）— 要从归档中省略的 glob 模式。作为通配符排除传给 mksquashfs。** globstar 会自动规范化。默认：[]。
  • localBucket（可选）— 为 true 时，使用 BACKUP_BUCKET R2 绑定，而不是预签名 URL。适用于 wrangler dev。默认：false。
  • compression（可选）— 归档压缩。默认格式：lz4。默认线程数：8。格式必须是 gzip、lz4 或 zstd。threads 必须为正整数。
  • multipart（可选）— 对大型归档使用并行分片上传。默认：true。

返回：Promise<DirectoryBackup>，包含：

• id — 唯一备份标识符（UUID）
• dir — 已备份的目录
• localBucket（可选）— 备份是否使用了本地 R2 绑定模式

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

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

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

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

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

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

工作原理：

在生产环境中：

1. 容器创建压缩的 squashfs 归档。
2. 容器使用预签名 URL 将归档上传到 R2。
3. 元数据与归档一并存储在 R2 中。
4. 删除本地归档。

使用 localBucket: true 时：

1. 容器创建压缩的 squashfs 归档。
2. 归档通过 BACKUP_BUCKET R2 绑定上传。
3. 元数据与归档一并存储在 R2 中。
4. 删除本地归档。

抛出：

• InvalidBackupConfigError — 如果 dir 不是允许的绝对路径、缺少 BACKUP_BUCKET 绑定，或（在生产中）未配置 R2 预签名 URL 凭据
• BackupCreateError — 如果归档创建或上传到 R2 失败

恢复先前创建的备份。

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

参数：

• backup — 由 createBackup() 返回的 handle。包含 id 与 dir。恢复会写入 backup.dir，该路径可以与原始备份路径不同。（见 DirectoryBackup）

返回：Promise<RestoreBackupResult>，包含：

• success — 恢复是否成功
• dir — 已恢复的目录
• id — 已恢复的备份 ID

await sandbox.restoreBackup(backup);

await sandbox.restoreBackup(backup);

工作原理：

在生产环境中：

1. 从 R2 下载元数据并检查 TTL，带有 60 秒缓冲。过期备份会抛出错误。
2. 容器使用预签名 URL 从 R2 下载归档。
3. 容器使用 FUSE overlayfs 挂载归档。

使用 localBucket: true 时：

1. 从 BACKUP_BUCKET 绑定下载元数据并检查 TTL。
2. 从 R2 绑定下载归档。
3. 使用 unsquashfs 解压归档。

抛出：

• InvalidBackupConfigError — 如果 backup.id 缺失或不是 UUID，或 backup.dir 无效
• BackupNotFoundError — 如果元数据或归档不在 R2 中
• BackupExpiredError — 如果 TTL 已过期
• BackupRestoreError — 如果容器恢复失败

• 同一 sandbox 上的并发备份与恢复操作会串行化。
• DirectoryBackup 可序列化。可将其存储在 KV、D1 或 Durable Object 存储中。
• 重叠的备份彼此独立。恢复父目录会覆盖子目录挂载。同时恢复两者时，请先恢复父目录。
• ttl 仅在恢复时强制执行。过期对象会保留在 R2 中，直到你删除它们，或由 R2 生命周期规则 移除。
• 备份对象使用 backups/{id}/data.sqsh 和 backups/{id}/meta.json。

interface BackupCompressionOptions {
	format?: "gzip" | "lz4" | "zstd";
	threads?: number;
}

interface BackupOptions {
	dir: string;
	name?: string;
	ttl?: number;
	gitignore?: boolean;
	excludes?: string[];
	localBucket?: boolean;
	compression?: BackupCompressionOptions;
	multipart?: boolean;
}

字段：

• dir（必填）— /workspace、/home、/tmp、/var/tmp 或 /app 下的绝对路径
• name（可选）— 可读名称。最长 256 个字符。无控制字符。
• ttl（可选）— 生存时间（秒）。默认：259200（3 天）。必须为正数。
• gitignore（可选）— 为 true 时，如果 dir 位于 git 仓库内，则排除 .gitignore 匹配项。默认：false。
• excludes（可选）— 要省略的 glob 模式。示例：['node_modules/.cache', '*.log']。请参阅 排除生成的缓存。
• localBucket（可选）— 使用 BACKUP_BUCKET 绑定，而不是预签名 URL。默认：false。
• compression（可选）— format 默认为 lz4。threads 默认为 8。
• multipart（可选）— 并行分片上传。默认：true。

interface DirectoryBackup {
	readonly id: string;
	readonly dir: string;
	readonly localBucket?: boolean;
}

字段：

• id — 唯一备份标识符（UUID）
• dir — 要恢复到的目录
• localBucket（可选）— 备份是否使用了本地 R2 绑定模式

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

字段：

• success — 恢复是否成功
• dir — 已恢复的目录
• id — 已恢复的备份 ID

• 备份与恢复 — 设置与恢复工作流
• 目录备份 — overlay 恢复与 EXDEV
• 存储 API — 挂载兼容 S3 的存储桶
• 文件 API — 读写文件
• Wrangler 配置 — 配置绑定