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 Runtimepool 首次遇到某个 key 时TTL/LRU3 回收、失效、daemon 关闭或 Worker 崩溃一个 Worker、一个 backend handle、一个已加载的 Unit,以及协同状态

所有权关系可以归纳为一条规则:CLI 只发起一次调用,daemon 持有 pool,pool 持有 Worker,Worker 持有 Runtime。

100%

Daemon 只转发应用自身定义的 JSON 请求。Snapshot、changeset 和 block 由 Worker 内的 backend 直接读取,既不经过 CLI,也不经过 daemon。

第一步:每条 CLI 命令都直接加载 Runtime

最简单的实现方式是在 Commander action 中创建 @univer-cli/univer-collaboration-runtime,并在操作完成后关闭:

TypeScript
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() 调用不只是读取文件,它按顺序执行以下步骤:

  1. 打开应用提供的 collaboration backend。
  2. 创建一个 headless Univer,并安装协同相关能力。
  3. 加载 UnitData 或 Snapshot checkpoint。
  4. replay checkpoint 中携带的 changeset。
  5. 拉取并 replay checkpoint 与远端最新 revision 之间的缺口。
  6. 等待已安装的公式模块完成计算并应用最新结果。
  7. 返回一个可以执行 execute()、pull()、commit() 的 Runtime。

一次完整的一次性调用如下:

100%

这种做法的所有权关系明确,失败后不留下状态,适合低频命令和一次性任务。代价是下一条 CLI 命令需要启动新的 Node.js 进程,重新执行整个加载流程,无法复用上一条命令创建的 Univer 和 Unit 状态。

第二步:用 Worker pool 承载 Runtime

@univer-cli/univer-collaboration-runtime-pool 为每个 resident key 维护独立的 Worker 进程和 Collaboration Runtime。应用需要先提供 Worker entry,backend、凭据和 Univer 都在 Worker 中创建:

TypeScript
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():

TypeScript
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 进程中,复用仍然无法跨越命令边界:

100%

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:

TypeScript
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 发送一个业务请求:

TypeScript
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。

100%

之后访问同一个 key 时走热路径。CLI 进程仍会重新启动,但昂贵的 Runtime 加载不会重复:

100%

复用的对象是已经创建并加载的 live Runtime。复用不绕过协同一致性:获取 lease 之后通常仍需调用 pull();commit() 之后仍需检查最终状态,并处理 pull-required、retry、unknown 或 conflict。

哪些消耗被省下,哪些仍然存在

成本每次直接加载 RuntimeDaemon + 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。

并发、失败与关闭

系统的行为可以归纳为四条规则:

  1. 相同 key 的并发请求会排队。 一个 live Runtime 在任意时刻只属于一个 lease,交叉调用无法修改协同状态。
  2. 不同 key 可以由不同 Worker 并行处理。 代价是每个 resident key 都占用独立的 Worker 和 Runtime。
  3. 只有可信状态允许复用。 操作成功且本地 mutation 清理之后调用 release();出现 timeout、crash、协议错误,或者应用无法确认本地状态时,调用 invalidate()。
  4. 关闭责任逐层向下。 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

  1. Unit 指一个文档实例,例如一个工作簿或一篇文档。工作表属于工作簿的一部分,不是独立的 Unit。 ↩

  2. 这里的 Runtime 指已加载文档的 Univer 实例及其操作 Unit 所需的运行资源,不是 Node.js 可执行程序,也不是保存到磁盘的文档快照。 ↩

  3. TTL 在达到配置的存活时间后回收空闲缓存 Runtime;LRU 在容量受限时优先回收最久未使用的实例。这些策略释放运行资源,不会删除持久化的 Unit。 ↩

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.