备份与恢复会将 sandbox 目录快照到 R2 归档中,之后再把该目录树还原回来。在生产环境和 wrangler dev 中,公开 API 相同,但恢复机制不同。
当你希望 /workspace 这类项目目录稍后还能回来时,请使用备份。当 /data 这类独立存储路径应独立于 sandbox 文件系统持久保存时,请使用 存储桶挂载。
在生产环境中,restoreBackup() 使用 FUSE overlayfs 挂载 squashfs 归档:
- 备份是只读的下层。
- 新写入进入可写上层。
- R2 中的原始归档不会改变。
- 再次使用同一 handle 恢复会丢弃上层。
overlay 仅在容器运行期间存在。当 sandbox 休眠或容器重启时,挂载会消失,目录为空。请保存 DirectoryBackup handle,并再次恢复。
当 localBucket: true 时,wrangler dev 使用 unsquashfs 解压归档。目标目录会被替换。没有 overlay,因此本地恢复不会复现生产环境的 FUSE 行为。
Overlayfs 将下层和上层视为不同设备。如果重命名把某个目录从已恢复的下层移动到可写上层,可能失败并出现 EXDEV(cross-device link not permitted)。
Vite 会对 node_modules/.vite/deps 这样做。请将该目录从备份中排除,或在恢复后删除它。
操作步骤请参阅 排除生成的缓存。
- 备份与恢复 - 创建、恢复并排除缓存
- Backups API - 方法签名与选项
- Sandbox 生命周期 - sandbox 休眠时会发生什么