Cloudflare Computer执行追踪器详解：并发exec状态跟踪的完整设计指南-港品优选

Cloudflare Computer执行追踪器详解：并发exec状态跟踪的完整设计指南

【免费下载链接】computerGive your agent a computer 👾项目地址: https://gitcode.com/GitHub_Trending/computer1/computer

Cloudflare Computer 是一个为 AI Agent 提供"一台计算机"的开源项目（Give your agent a computer 👾），它把虚拟文件系统和可插拔的执行后端封装在 Durable Object 中。当多个exec命令同时在不同后端（容器、Worker Shell、Worker JavaScript）上并发运行时，系统如何准确跟踪每个执行（execution）属于哪个运行时（runtime）？答案就是ExecutionRuntimeTracker（执行追踪器）——本文带你用最短的时间理解它的状态跟踪设计。

Cloudflare Computer 的整体架构：Durable Object 持有权威状态，执行面可插拔

为什么并发 exec 需要"执行追踪器"

一个 Workspace 可以同时注册多个后端，workspace.runtime.exec()是唯一的执行入口。每条命令执行后，系统会拿到一个executionId，后端容器可能随时被替换（reconnect、重建）。这时候有两个经典问题：

后续操作该发给谁？对某条 exec 执行killExec、disposeExec、拉取事件流（getExec）时，必须确认它当前所在的运行时；
运行时被换了怎么办？如果容器已重建，旧 exec 已经"丢失"，系统要快速、明确地报错，而不是把命令发到错误的运行时上。

执行追踪器就是为这两个问题设计的：记录"最近活跃的执行 → 所属运行时"的映射关系。

双层结构：有界内存 LRU + SQLite 持久化

追踪器的核心实现非常克制，只有 100 行左右，位于 execution-runtime-tracker.ts。

层级	实现	作用
内存层	`Map`实现的有界 LRU（默认1024条）	快速命中，避免无界增长
持久层	`SqlExecutionRuntimeStore`（SQLite 表`computer_execution_runtime`）	Durable Object 重启/缓存淘汰后恢复所有权

几个关键设计点：

LRU 淘汰：#touch()方法在读取时把条目"重新插入"到 Map 末尾，利用 Map 的插入顺序把最久未访问的键淘汰——最近活跃的执行永远不会先被挤出去；
持久兜底：内存命中不了时回查 SQLite，查到的映射会被回填进内存缓存；
乐观删除：delete(key, expectedRuntimeId)只有当前值与期望的 runtimeId 一致时才真正删除，防止并发场景下"晚到的旧操作"误删新执行刚写入的映射。

Workspace 构造时这样装配追踪器（见 workspace.ts）：

this.#executionRuntimes = new ExecutionRuntimeTracker( 1_024, new SqlExecutionRuntimeStore(this.#db), );

一次并发 exec 的完整状态跟踪流程

整个闭环体现在 workspace.ts 的命令适配层中，流程大致是：

exec 返回时记忆：每条命令的返回信封（envelope）自带runtimeId，通过#rememberExecutionRuntime()写入追踪器，键由JSON.stringify([backendId, executionId])组合，天然区分不同后端下的同号执行 ID；
后续操作前查表：getExec/killExec/disposeExec先查追踪器拿到"期望的 runtimeId"；
断言校验：真正下发前，assertExecutionRuntime()会把期望值与当前运行时对比。若容器已被替换，立即抛出WorkspaceExecutionLostError（错误码EEXEC_LOST），明确告知"这条执行在运行时替换时丢失了"；
清理收尾：disposeExec成功后，用带期望值的乐观删除清理映射，避免脏数据残留。

这样即使缓存被淘汰、甚至 Durable Object 整体重建（新的 Workspace incarnation），持久层也能把"谁属于哪个运行时"的信息恢复回来——测试用例 execution-runtime-tracker.test.ts 覆盖了 LRU 淘汰、持久回退、跨实例恢复和乐观删除全部场景。

设计亮点小结

✅有界内存：LRU 上限固定，缓存占用不随 Durable Object 生命周期无限增长；
✅持久兜底：SQLite 保证跨实例（incarnation）的所有权连续性；
✅失败即明确：运行时不匹配时报EEXEC_LOST，而不是静默执行到错误环境；
✅并发安全：乐观删除 + 键中携带后端 ID，双保险防并发误操作。

企业官网建设流程全解析