バックアップと復元は、サンドボックスのディレクトリを R2 アーカイブにスナップショットし、あとからそのツリーを戻します。公開 API は本番と wrangler dev で同じです。復元の仕組みは異なります。
/workspace のようなプロジェクトディレクトリをあとから戻したいときに、バックアップを使います。/data のような別のストレージパスを、サンドボックスのファイルシステムとは独立して残したいときは、バケットマウント を使います。
本番では、restoreBackup() は squashfs アーカイブを FUSE overlayfs でマウントします。
- バックアップは読み取り専用の下位レイヤーです。
- 新しい書き込みは、書き込み可能な上位レイヤーに行きます。
- R2 内の元のアーカイブは変わりません。
- 同じハンドルで再度復元すると、上位レイヤーは破棄されます。
オーバーレイは、コンテナの実行中だけ存在します。サンドボックスがスリープするかコンテナが再起動すると、マウントはなくなり、ディレクトリは空になります。DirectoryBackup ハンドルを保存し、再度復元してください。
localBucket: true のとき、wrangler dev は unsquashfs でアーカイブを展開します。対象ディレクトリは置き換わります。オーバーレイはないため、ローカル復元は本番の FUSE 動作を再現しません。
overlayfs は、下位レイヤーと上位レイヤーを別デバイスとして扱います。復元した下位レイヤーから書き込み可能な上位レイヤーへディレクトリを移すリネームは、EXDEV（cross-device link not permitted）で失敗することがあります。
Vite は node_modules/.vite/deps でこれを行います。そのディレクトリをバックアップから除外するか、復元後に削除してください。
手順は 生成キャッシュを除外する を参照してください。
- バックアップと復元 - 作成、復元、キャッシュの除外
- Backups API - メソッドのシグネチャとオプション
- サンドボックスのライフサイクル - サンドボックスがスリープしたときの動き