Cloudflare Computer同步幂等性设计：崩溃恢复与重复应用的零成本保证
【免费下载链接】computerGive your agent a computer 👾项目地址: https://gitcode.com/GitHub_Trending/computer1/computer
Cloudflare Computer 是 Cloudflare 官方的「给 Agent 一台计算机」项目：它把 SQLite 支撑的虚拟文件系统放进 Durable Object，通过 FUSE 挂载到沙箱容器，并在两侧之间跑一条双向增量同步协议。这篇文章带你拆解它的同步幂等性设计——为什么崩溃恢复、连接中断、重复投递，最终都接近零成本。
🏗️ 架构速览：两份文件副本，一条同步协议
Cloudflare Computer 始终维护同一棵目录树的两个副本：
- DO 侧：位于 Durable Object 内、SQLite 支撑的虚拟文件系统，是跨越重启的唯一权威状态；
- 容器侧：暴露给沙箱的 FUSE 挂载，容器内每次写入都会被打上递增的修订号。
数据沿两个方向、各按各的节奏流动：命令执行前，DO 把未送达的变更推给容器（push）；命令结束后，DO 把容器侧的变更拉回 SQLite（pull）。一次完整的exec()往返就是「推送 → 挂载水合 → 执行 → 拉取 → 应用」六步。
完整协议设计可参见 docs/02_sync_protocol.md。
⚡ 幂等的第一道防线：按路径合并的「最终状态」传输
很多同步系统记录"操作"（写了一次、删了一次、重命名了一次），恢复时必须按序重放——这是复杂度的根源。Cloudflare Computer 反其道而行：线上只传最终状态，不传操作。
关键在 coalesceChanges：两个水位之间，同一个路径被重写 5 次，线上只合并成 1 条——最新状态胜出。线上记录只有两种：存活条目和删除墓碑（tombstone）。这意味着：
- 重命名不需要专门的 opcode，表达为"新路径的存活条目 + 旧路径的墓碑"，冷启动的接收方无需任何历史上下文就能应用；
- 应用方无需按操作顺序重放：每条条目独立对照接收方当前状态判断，重复应用多少次结果都一样。
这就是幂等的前提：协议让"重复投递"成为常态场景，而不是异常。
🛡️ 重复应用零成本的秘诀：alreadyApplied 检查
应用阶段，applyChanges 对每条入口先做快速比对：本地状态已匹配的，直接丢弃。比较规则在 alreadyApplied 中按节点类型细分：
- 文件：比对清单哈希。哈希由文件的分块列表计算得出（见 computeManifestHash），内容寻址保证相同分块永远产生相同哈希，"是否相同"一次比对即可；
- 目录：只比对 mode，故意不比 mtime——避免目录的时间戳漂移变成无谓的同步流量；
- 符号链接：比对目标路径与 mode；
- 删除：直接强制删除，"已经不存在"也视为成功（apply.ts）。
还有一个更妙的收益：被丢弃的条目不会提升本地修订号，所以下一轮推送不会把它原样弹回来。重复应用不仅安全，而且"安静"——这正是"零成本"三字的含义。
🔄 崩溃恢复指南：(rev, path) 游标与每批次检查点
崩溃之后最多重取多少数据？答案是：一个批次（256 条）。
拉取侧按 PULL_BATCH_SIZE = 256 分批流式处理条目，每批提交后立刻把持久化游标推进到该批最后一条的(rev, path)（writeFetchCursor）。注意这是两级坐标：
rev是修订号，每次变更原子地加一；path是正交的第二坐标，记录同一 rev 内部推进到了哪一条。
一次大型目录重命名会在同一个 rev 里盖下海量条目。若只能停在 rev 边界恢复，一次崩溃就要重做整个 rev；有了path坐标，就能在 rev 中间恢复。源码注释说得非常直白（sync-driver.ts）：游标推进故意不与 apply 原子化——崩溃导致重复取回同一批时，alreadyApplied会默默吸收它。
推送侧同理：接收方确认并回显appliedPushCursor之后，发送方才推进pushRev。中途断开则水位未动，下次重试整批重放，由接收方的幂等检查兜底。
DO 侧的所有水位都持久化在_vfs_watermark表中，重启后新实例直接从旧进度继续；容器进程重启（内存数据库被清空）时，同步驱动会在重连后调用 reconcileWatermarks 把分叉的游标重置归零，从 rev-0 基线增量重建——依然不用全量传输。
📋 常见故障场景速查表
| 故障场景 | 恢复机制 | 保证 |
|---|---|---|
| DO 重启 | 水位持久化于_vfs_watermark表 | 新实例接着旧进度走 |
| 拉取中途崩溃 | 游标按批次推进，同批重取 | 浪费工作 ≤ 256 条，幂等吸收 |
| 推送中途断线 | pushRev未推进，整批重放 | 接收端alreadyApplied丢弃已应用条目 |
| 容器进程重启 | 重连 +reconcileWatermarks | 从 rev-0 基线增量重建 |
| 并发 push/pull | 每 Workspace 的 FIFO 队列 | 串行执行，失败不传染队列 |
💡 新手注意：幂等 ≠ 合并
有一个边界值得说清：上述幂等保证的是"同一状态应用多次必然收敛"，但两个不同状态同时写同一路径，仍是最后写入者胜出——没有合并、没有报错，和共享 NFS 挂载的语义一致。对"一个 Agent、一个容器"的常见用法，同步本质上是持久化机制，不存在冲突；若多个 Agent 共写一个文件或交接同一个工作区，建议用显式的workspace.pull()作为交接点。详见 docs/02_sync_protocol.md 的 Conflict semantics 一节。
📌 小结
- 最终状态传输：按路径合并、墓碑表达删除，不需要操作重放，幂等是协议属性；
alreadyApplied：重复应用只做一次哈希比对即丢弃，连本地修订号都不提升——真正意义上的零成本；(rev, path)两级游标：崩溃恢复的重取量恒定有界（≤ 256 条），可预测、可压测；- 持久水位 + 重连对账：DO 重启与容器重启各有一条明确的恢复路径。
四套机制叠加，让 Cloudflare Computer 的同步层"不怕重传"——这正是把一台可以长期可靠运行的计算机交给 Agent 的底层工程底气。
【免费下载链接】computerGive your agent a computer 👾项目地址: https://gitcode.com/GitHub_Trending/computer1/computer
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
