Runtime 复用与 Daemon
从一次 CLI 命令的 Runtime 生命周期出发,理解 daemon 如何长期持有 Worker Runtime pool,并在多次调用之间复用已加载的 Unit。
执行一条 CLI 命令时,耗时的环节通常不是解析参数,而是把一个 Unit1 变成可读写的 live Univer:创建 Univer、安装插件、打开协同 backend、加载 checkpoint、补齐 changeset,再等待公式完成计算。
完成这项工作需要两种 Runtime2 能力,本文分别介绍:
@univer-cli/univer-collaboration-runtime:在当前进程中加载并操作一个 Unit;@univer-cli/univer-collaboration-runtime-pool:把 Runtime 放入 Worker,按 Unit 身份租用、复用和回收。
Worker Runtime 只有被长期存活的进程持有,才能跨多次 CLI 调用继续存在。本文中,这个持有者是本地 daemon。
先建立三个生命周期
在考虑复用之前,需要区分三个对象的生命周期:
| 对象 | 何时创建 | 何时结束 | 持有什么 |
|---|---|---|---|
| CLI 进程 | 用户每次执行命令时 | 命令输出结果之后 | 参数、一次请求,以及输出格式化逻辑 |
| Daemon 进程 | 首次请求时按需启动,或直接启动 | 被停止、因升级重启,或者崩溃 | Runtime pool、业务 handler 和本地 socket |
| Worker Runtime | pool 首次遇到某个 key 时 | TTL/LRU3 回收、失效、daemon 关闭或 Worker 崩溃 | 一个 Worker、一个 backend handle、一个已加载的 Unit,以及协同状态 |
所有权关系可以归纳为一条规则:CLI 只发起一次调用,daemon 持有 pool,pool 持有 Worker,Worker 持有 Runtime。
Daemon 只转发应用自身定义的 JSON 请求。Snapshot、changeset 和 block 由 Worker 内的 backend 直接读取,既不经过 CLI,也不经过 daemon。
第一步:每条 CLI 命令都直接加载 Runtime
最简单的实现方式是在 Commander action 中创建 @univer-cli/univer-collaboration-runtime,并在操作完成后关闭:
const runtime = await runtimeFactory.load(unitId, unitType);try { const pulled = await runtime.pull(); if (pulled.status === "conflict") throw new Error(pulled.conflict.message); const execution = await runtime.execute({ mode: "write", code }); let commit = await runtime.commit(); if (commit.status === "pull-required") { const repulled = await runtime.pull(); if (repulled.status === "conflict") throw new Error(repulled.conflict.message); commit = await runtime.commit(); } return { execution, commit };} finally { await runtime.close();}runtimeFactory 由 createUniverCollaborationRuntimeFactory() 创建。一个 Runtime 从加载到关闭只绑定一个 Unit,并保存该 Unit 当前的 revision、pending mutation、awaiting changeset 和 conflict 状态。调用方还必须检查最终的 commit status:只有 confirmed 和 nothing-to-commit 表示操作已经完成。
一次 load() 调用不只是读取文件,它按顺序执行以下步骤:
- 打开应用提供的 collaboration backend。
- 创建一个 headless Univer,并安装协同相关能力。
- 加载 UnitData 或 Snapshot checkpoint。
- replay checkpoint 中携带的 changeset。
- 拉取并 replay checkpoint 与远端最新 revision 之间的缺口。
- 等待已安装的公式模块完成计算并应用最新结果。
- 返回一个可以执行
execute()、pull()、commit()的 Runtime。
一次完整的一次性调用如下:
这种做法的所有权关系明确,失败后不留下状态,适合低频命令和一次性任务。代价是下一条 CLI 命令需要启动新的 Node.js 进程,重新执行整个加载流程,无法复用上一条命令创建的 Univer 和 Unit 状态。
第二步:用 Worker pool 承载 Runtime
@univer-cli/univer-collaboration-runtime-pool 为每个 resident key 维护独立的 Worker 进程和 Collaboration Runtime。应用需要先提供 Worker entry,backend、凭据和 Univer 都在 Worker 中创建:
import { defineUniverCollaborationRuntimeWorker } from "@univer-cli/univer-collaboration-runtime-pool";export default defineUniverCollaborationRuntimeWorker({ async createRuntime(init: { unitId: string; unitType: number }) { return createRuntimeFromApplicationInit(init); },});Worker entry 必须指向构建后的 JavaScript ESM 文件。init 只在冷创建时发送给 Worker,并且必须支持 structured clone。
调用方不需要自行设计 Runtime RPC 层。lease 已经代理了公共接口,包括 getState()、execute()、fetch()、pull()、commit() 和 exportUnitData():
import { createUniverCollaborationRuntimePool } from "@univer-cli/univer-collaboration-runtime-pool";const pool = createUniverCollaborationRuntimePool({ entry: new URL("./collaboration-worker.js", import.meta.url),});const lease = await pool.acquire({ key: targetKey, init: { unitId, unitType },});try { await lease.pull(); const result = await lease.execute({ mode: "read", code }); console.log(result.value);} catch (error) { await lease.invalidate(); throw error;} finally { await lease.release();}key 决定复用哪个 Runtime,它不只是查询参数。同一个 key 必须始终对应同一个 Unit、同一条协同状态链,以及兼容的初始化语义。普通 Unit 和 Worktree draft 即使 unitId 相同,也必须使用不同的 key。
以下四项行为会影响 pool 的复用:
- 同一个 key 在任意时刻只由一个 lease 持有。并发请求按 FIFO 排队,因此两个调用不会同时修改同一份 live state;
release()把可信的 Runtime 放回 idle cache,该 key 的下一次请求可以复用;invalidate()表示状态不再可信,Worker 及其 Runtime 会被销毁,下一次请求重新执行冷加载;- idle Runtime 可以按 TTL 和 LRU 回收。timeout、Worker crash 和协议错误同样会使当前实例失效。
如果 pool 本身位于生命周期很短的 CLI 进程中,复用仍然无法跨越命令边界:
Worker 提供了 Runtime 的进程隔离、独占租用和故障终止能力。要跨 CLI 调用复用,pool 仍然需要一个比任何单条命令存活更久的持有者。
第三步:让 Daemon 成为 pool 的长期 owner
Daemon 是一个按需启动的本地 Node.js 进程,CLI 通过 Unix socket 或 Windows named pipe 与其通信。CLI 退出不会终止 daemon,因此其 pool、Worker 和 idle Runtime 会继续存活。
在 daemon entry 中创建一次 pool,然后在每个业务 handler 中获取 lease:
import { createDaemonServer, DAEMON_SOCKET_ENV } from "@univer-cli/daemon";import { createUniverCollaborationRuntimePool } from "@univer-cli/univer-collaboration-runtime-pool";const socketPath = process.env[DAEMON_SOCKET_ENV];if (!socketPath) throw new Error(`${DAEMON_SOCKET_ENV} is required`);const pool = createUniverCollaborationRuntimePool({ entry: new URL("./collaboration-worker.js", import.meta.url), cache: { idleTtlMs: 5 * 60_000, maxEntries: 20 },});const server = createDaemonServer({ identity: { id: "my-cli", version: "1.0.0" }, socketPath, onShutdown: () => pool.close(),});server.handle("unit.execute", async (payload) => { const input = parseExecuteRequest(payload); const lease = await pool.acquire({ key: input.targetKey, init: { unitId: input.unitId, unitType: input.unitType }, }); try { const pulled = await lease.pull(); if (pulled.status === "conflict") throw new Error(pulled.conflict.message); const execution = input.mode === "read" ? await lease.execute({ mode: "read", code: input.code }) : await lease.execute({ mode: "write", code: input.code }); const commit = input.mode === "write" ? await commitWithPull(lease) : null; return { commitStatus: commit?.status ?? null, value: execution.value }; } catch (error) { await lease.invalidate(); throw error; } finally { await lease.release(); }});await server.listen();parseExecuteRequest() 与 targetKey 的规则由应用定义。daemon 只提供本地 transport 和生命周期管理,不识别 Unit、Runtime,也不识别协同协议。关闭 daemon 时必须调用 pool.close(),使 idle 和 active 的 Worker 都有明确的最终持有者。示例中的 commitWithPull() 负责 pull-required 之后的 pull 和 commit,并检查最终的提交状态。为保持示例的保守性,任何未处理的错误都会 invalidate 当前 lease。
此时一条普通的 CLI 命令只需向 daemon 发送一个业务请求:
import { createDaemonClient } from "@univer-cli/daemon";const client = createDaemonClient({ entry: new URL("./daemon-entry.js", import.meta.url), identity: { id: "my-cli", version: "1.0.0" }, socketPath,});const result = await client.request("unit.execute", { targetKey, unitId, unitType, mode, code,});当 socket 不存在时,client 会启动已配置的 daemon entry,等待 identity 和 protocol handshake 完成,再发送请求;如果已有兼容的 daemon 在运行,client 会直接复用它。
第四步:看清第一次与后续请求
首次访问某个 key 时走冷路径:daemon 可能需要启动,pool 也必须创建 Worker 和 Runtime。
之后访问同一个 key 时走热路径。CLI 进程仍会重新启动,但昂贵的 Runtime 加载不会重复:
复用的对象是已经创建并加载的 live Runtime。复用不绕过协同一致性:获取 lease 之后通常仍需调用 pull();commit() 之后仍需检查最终状态,并处理 pull-required、retry、unknown 或 conflict。
哪些消耗被省下,哪些仍然存在
| 成本 | 每次直接加载 Runtime | Daemon + Worker pool |
|---|---|---|
| CLI 进程启动、参数解析、结果输出 | 每次都会发生 | 每次都会发生 |
| 本地 socket JSON request/response | 无 | 每次都会发生 |
| Daemon 启动与模块加载 | 无 | 首次请求或重启后发生 |
| Worker 启动与 Worker entry 加载 | 无 Worker | 每个 key 冷创建时发生 |
| 创建 Univer、安装插件 | 每次都会发生 | 每个 key 冷创建时发生 |
| 加载 checkpoint、replay 初始 changeset、等待公式 | 每次都会发生 | 每个 key 冷创建时发生 |
pull() 获取空闲期间的新 changeset | 每次都会发生 | 每次通常仍然需要 |
execute() 与 commit() | 每次都会发生 | 每次都会发生 |
| idle 内存、backend handle、Worker 进程 | 命令结束即释放 | 保留到 eviction、失效或 daemon 关闭 |
因此,复用以常驻内存和 Worker 数量换取后续调用更低的启动延迟。idleTtlMs、maxEntries、open timeout 和 operation timeout 应根据 pool 事件和实测延迟设置,而不是长期保留所有 Unit。
并发、失败与关闭
系统的行为可以归纳为四条规则:
- 相同 key 的并发请求会排队。 一个 live Runtime 在任意时刻只属于一个 lease,交叉调用无法修改协同状态。
- 不同 key 可以由不同 Worker 并行处理。 代价是每个 resident key 都占用独立的 Worker 和 Runtime。
- 只有可信状态允许复用。 操作成功且本地 mutation 清理之后调用
release();出现 timeout、crash、协议错误,或者应用无法确认本地状态时,调用invalidate()。 - 关闭责任逐层向下。 CLI 完成一次 request;daemon shutdown 调用
pool.close();pool 终止 Worker,并关闭它们的 Runtime 和 backend。
对于低频命令,如果单次延迟可以接受,直接使用 @univer-cli/univer-collaboration-runtime 是最简单的选择。只有当实测表明重复加载是主要成本,且应用能够接受常驻进程及其内存占用时,才应将 daemon 与 @univer-cli/univer-collaboration-runtime-pool 组合使用。
完整的 package 清单见 Package 概览。
Footnotes
你觉得这篇文档如何?