cloudflare/workspace

# Cloudflare Workspace Cloudflare Workspace 是一个存在于 Durable Object 内部的虚拟文件系统。Durable Object 在 SQLite 中保存权威状态，并通过可插拔的 backend 将文件系统暴露给 shell。目前内置两种 backend： - **Container** 将 SQLite 状态作为 真实的 FUSE 挂载映射到 sandbox container 中。sandbox 端的 daemon (`wsd`) 将状态挂载为 文件系统，并通过 capnweb RPC 通道将更改同步回去。 完整的 Linux 用户空间、真实的二进制文件、真实的网络。 - **Worker** 将 shell 作为 [just-bash](https://github.com/vercel-labs/just-bash) 运行在通过 `env.LOADER` 加载的 Dynamic Worker 内部。Shell 通过 Workers RPC 访问宿主工作区，因此没有第二个 存储，也没有同步往返。广泛的文本工具（`cat`、 `grep`、`awk`、`sed`、`jq`、...），没有 container 生命周期。 单个 Workspace 可以同时托管多个 backend。每个 backend 在一个稳定的 `id` 下注册；`shell.exec` 默认使用列表中的第一个，调用者可以使用 `{ backend: "sandbox" }` 将特定的调用路由到其他地方。常见结构：使用 Worker backend 处理轻量级的文本工具（每次 命令都是冷启动），再加上一个 Container backend，当 agent 需要 真实的 Linux 环境来运行 `npm`、`git` 或 worker isolate 无法 托管的任何其他内容时即可调用。每个 backend 都保留自己的 同步游标，并在首次使用时延迟连接。 Workspace 也可以在没有 backend 的情况下构建，让 调用者独立使用文件系统。 ## 要求 - Node 22 或更高版本。 - npm。此 repo 使用 npm workspaces。 - 如果你想端到端运行 `packages/wsd`，需要带有 FUSE 的 Linux。其他 软件包也可以在 macOS 上构建和测试。 - 可选的 Docker，用于 [`examples/container`](examples/container)。 Worker 示例不需要 Docker。 ## 快速开始 ``` git clone https://github.com/cloudflare/workspace.git cd workspace npm install npm run build:all npm test ``` 要查看各个部分如何协同工作，请从示例开始： - [`examples/container`](examples/container) — 在 container 内运行 `wsd`，挂载工作区，并通过 capnweb 与 Durable Object 通信。 - [`examples/worker`](examples/worker) — 与 container 示例具有相同的 HTTP 接口，但 shell 运行在 通过 `env.LOADER` 加载的 Dynamic Worker 中。不需要 container。 - [`examples/think`](examples/think) — 一个将 workspace 作为其工作目录的 agent。 ## 仓库布局 该 repo 是一个小型的 monorepo。每个软件包都有自己的 README，其中包含 特定于软件包的状态和使用说明。 - [`packages/dofs`](packages/dofs/README.md) (`@cloudflare/dofs`) — 基于 Durable Object SQLite 的虚拟文件系统、同步协议 构建块，以及用于 Node 的 `@platformatic/vfs` 提供程序。 - [`packages/rpc`](packages/rpc/README.md) (`@cloudflare/workspace-rpc`) — 在 Durable Object 和 `wsd` 之间共享的 capnweb 线路类型和 服务器/客户端助手。 - [`packages/wsd`](packages/wsd/README.md) (`@cloudflare/workspace-wsd`) — `wsd` daemon：一个 FUSE 挂载加上 在 sandbox container 内运行的 HTTP/WebSocket RPC 服务器。 - [`packages/workspace`](packages/workspace/README.md) (`@cloudflare/workspace`) — 由 Durable Object 使用的顶级 Workspace 软件包。开发中。 ## 性能 数据来自 `script/fs-bench.sh` 以及对 [`cloudflare/sandbox-sdk`](https://github.com/cloudflare/sandbox-sdk) （854 个软件包，36,675 个文件）的完整 `npm install`，在 Cloudflare Containers **standard-2** 实例（1 vCPU、6 GiB 内存、12 GB 磁盘）上运行 [`examples/wsd-container`](examples/wsd-container)。 wsd FUSE 挂载位于 `/workspace`；比较列分别是 位于 `/tmp` 的内存级 `tmpfs` 和位于 `/var/tmp` 的 container ext4 根磁盘。 比率是 `wsd / baseline` —— 数值越低速度越快，低于 1.0 的值意味着 wsd 优于 baseline。 ### `fs-bench` (REPS=3, WARMUP=1, 随机目标) | 场景 | wsd | tmpfs | tmpfs 比率 | ext4 磁盘 | 磁盘比率 | |---|---:|---:|---:|---:|---:| | **微小文件频繁操作** | | | | | | | 创建 1000 个文件 | 560.6 ms | 83.2 ms | 6.7x | 303.2 ms | 1.85x | | stat 1000 个文件 | 1971.9 ms | 1324.2 ms | 1.49x | 2659.3 ms | **0.91x** | | 删除 1000 个文件 | 827.7 ms | 322.7 ms | 2.56x | 1281.8 ms | **0.66x** | | **目录遍历** | | | | | | | mkdir 树 (10×10×10) | 1597.5 ms | 1585.7 ms | 1.01x | 3034.7 ms | **0.74x** | | find 树 | 1813.6 ms | 1819.9 ms | 1.00x | 4404.2 ms | **0.72x** | | **大文件 I/O** | | | | | | | 写入 64 MiB | 230.6 ms | 47.3 ms | 4.87x | 16.8 ms | 16.93x | | 复制 64 MiB | 1037.2 ms | 37.4 ms | 27.75x | 39.8 ms | 40.46x | | 读取 64 MiB | 437.5 ms | 22.6 ms | 19.33x | 25.6 ms | 39.72x | | 纯读取 64 MiB | 263.1 ms | 8.3 ms | 31.54x | 8.5 ms | 30.26x | | 纯复制 64 MiB | 852.9 ms | 21.7 ms | 39.27x | 22.0 ms | 41.47x | | 覆盖 64 MiB | 272.6 ms | 8.3 ms | 32.91x | 8.5 ms | 43.35x | | **git** | | | | | | | git init + commit 100 个文件 | 459.2 ms | 40.3 ms | 9.56x | 635.4 ms | **0.72x** | | git clone (shallow, ~1MB) | 549.1 ms | 421.0 ms | 1.30x | 576.2 ms | **0.84x** | | **npm** | | | | | | | npm init + 微量安装 | 598.5 ms | 630.7 ms | **0.95x** | 630.7 ms | **0.95x** | ### 完整的 `cloudflare/sandbox-sdk` `npm install` | 目标 | 时长 | |---|---:| | tmpfs (`/tmp`) | 34.3 s | | wsd FUSE (`/workspace`) | 124.7 s | | ext4 磁盘 (`/var/tmp`) | 63.9 s | 对于完整的 `npm install`，wsd 比 container 的 ext4 磁盘慢约 2 倍，比 tmpfs 慢约 3.6 倍。对于一般使用而言，磁盘比较 是更现实的 baseline。 ### wsd 快于磁盘 baseline 的情况 在元数据繁重的工作中，内存中的 inode 存储击败了真实磁盘： `stat`、`rm`、`mkdir tree`、`find tree`、`git init`、`git clone`、 `npm init`。这八个场景涵盖了工具（如 `git status`、模块解析和增量构建）的大部分日常开销。 ### wsd 较慢的情况 大文件顺序 I/O。wsd 写入路径会在每次发布时将每个 [`CHUNK_SIZE`](packages/dofs/src/fs/writeFile.ts) (512 KiB) 数据块 哈希到内容寻址的 blob 存储中；这就是 Durable Object 能够仅同步已更改的数据块并 对相同内容进行去重的原因。开销体现在原始的 `dd` 风格的吞吐量数据上，但很少影响真实的开发者 工作负载，这也是为什么尽管 `pure read 64 MiB` 慢了 30 倍，`npm init + tiny install` 仍能与磁盘 baseline 持平的原因。 ### 复现 ``` bash script/run-fs-bench.sh ``` 或者针对已部署的 `wsd-container` 实例，上传 [`script/fs-bench.sh`](script/fs-bench.sh) 并使用 `MOUNT=/workspace BASE=/tmp` 运行它。 ## 文档 - [`docs/`](docs/README.md) — 设计规范。具有前瞻性； 请视为意图。 ## 贡献 有关设置、格式化、 测试、提交信息和拉取请求规范，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 如果你作为 agent 在此 repo 中工作，请从 [`AGENTS.md`](AGENTS.md) 以及 [`.agents/skills/`](.agents/skills/) 下的技能开始。

标签：AI智能体, Durable Objects, MITM代理, SOC Prime, 后端开发, 开发工具, 沙箱容器, 程序员工具, 虚拟文件系统, 请求拦截