バックアップ

サンドボックスディレクトリの特定時点のスナップショットを作成し、R2 から復元します。

セットアップ、復元の流れ、生成キャッシュの除外は バックアップと復元 を参照してください。オーバーレイの意味は ディレクトリのバックアップ を参照してください。

ディレクトリのスナップショットを作成し、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 のとき、署名付き URL ではなく BACKUP_BUCKET R2 バインディングを使います。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() が返すハンドル。id と dir を含みます。復元先は backup.dir で、元のバックアップパスと異なることがあります（DirectoryBackup を参照）。

戻り値: Promise<RestoreBackupResult>。次を含みます:

• success - 復元が成功したかどうか
• dir - 復元したディレクトリ
• id - 復元したバックアップ ID

await sandbox.restoreBackup(backup);

await sandbox.restoreBackup(backup);

仕組み:

本番では:

1. R2 からメタデータをダウンロードし、60 秒のバッファ付きで TTL を確認します。期限切れのバックアップは例外を投げます。
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 - コンテナが復元に失敗した場合

• 同じサンドボックスでのバックアップと復元の同時実行は直列化されます。
• 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（任意） - 署名付き URL ではなく BACKUP_BUCKET バインディングを使います。デフォルト: 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

• バックアップと復元 - セットアップと復元の流れ
• ディレクトリのバックアップ - オーバーレイ復元と EXDEV
• Storage API - S3 互換バケットのマウント
• Files API - ファイルの読み書き
• Wrangler の設定 - バインディングの設定