SuperAPI AI 工具集

debugging-computerd-fuse

测试与质量

查看项目

更新于 10-15 19:50

技能介绍

用途:隔离并复现仅在 computerd 使用内核 FUSE 后端时才触发的缺陷。常规单元测试跑在 SQLiteTestStorage 与进程内 VFS 或 FUSE_MOUNT=shim 轮询驱动上,不覆盖内核 FUSE 回调路径,因此部分生产缺陷(写缓冲未落盘到 VFS、spawn(cwd=/mount) 死锁)未被常规套件捕获。

主要能力:在真实 Docker 容器中以 --privileged --device /dev/fuse --cap-add SYS_ADMIN --cap-add MKNOD 启动 computerd SEA 二进制,等待 /health,并通过 Node 脚本经 /api 的 capnweb WebSocket 驱动 WorkspaceRPC。日志出现 backend=fuse 表示成功;backend=shim 说明 FUSE 挂载未生效,backend=none 表示设置了 FUSE_MOUNT=none。

使用方式:先构建二进制(npm run build:bin --workspace @cloudflare/computerd,或仓库根目录 npm run build:all)。启动脚本为 packages/computer/test-harness/run-computerd.sh,例如 COMPUTERD_HARNESS_PORT=18080 bash packages/computer/test-harness/run-computerd.sh,stdout 打印 URL,stderr 打印容器 id;用 curl -sf http://127.0.0.1:18080/health 验证,docker kill <CID> 清理。探针项目依赖 @cloudflare/dofs、@cloudflare/computer-rpc 与 ws,使用 createWorkspaceClient、pushOnce、pullOnce 与 SQLiteTestStorage;WebSocket 需固定为 ws 包,因为 Node 内置实现不协商 permessage-deflate。路径必须位于 MOUNT_POINT(默认 /workspace)之下,否则 FUSE 不会呈现。容器侧写入可用 docker exec <CID> sh -c 'echo container-write > /workspace/r2/hello.txt'。

已知死锁:FUSE 缓冲未在 release/flush/fsync 时落盘会导致主机侧读到 0 字节(修复见 commit 68407fc);Runner.exec 以 cwd=/workspace 调用 spawn 会在 fork 与 exec 之间触发 FUSE LOOKUP,而事件循环阻塞在状态管道读取上,导致 exec 与 /health 永久挂起。诊断方法是同一客户端分别以 cwd=/tmp 与 cwd=/workspace 执行 echo hi,后者挂起即复现。修复思路是在 shell 内 chdir(cd ... && exec ...),并用 dofs 的 stat 预检以保留 ENOENT 契约。任何对挂载点做同步 fs 调用(statSync、readdirSync、realpathSync)的代码都可能阻塞事件循环,应改为异步或直接读 dofs 数据库。

适用场景:用户报告 FUSE 写入后 RPC 读到 0 字节、exec 永久挂起或 /health 无响应;新增 computerd 操作需要不依赖 Docker-in-DO 或 Cloudflare Containers 的冒烟测试;确认修复在部署二进制中生效。

限制:不能替代单元测试与基准测试(后者用 script/run-fs-bench.sh),也不用于单独测试同步链路(packages/rpc/tests/wire.test.ts 已覆盖)。macOS 需 colima start --vm-type=vz。若问题不在 JS 层,可用 node --inspect-brk 或容器内 strace -fp <computerd-pid> 进一步定位。僵尸容器可能残留,换端口即可。