Files
adnify/docs/process-isolation.md
adnaan 1f1bd7262e refactor: migrate asset and session storage to utility process architecture
- Replaced Worker threads with UtilityProcessClient for AssetStorageWorkerClient and SessionStorageWorkerClient.
- Implemented utility server for handling requests in asset and session storage workers.
- Updated asset storage worker and session storage worker to use new request handling mechanism.
- Introduced ContentProcessClient for document reading operations with utility process support.
- Added tests for utility process lifecycle and asset service interactions.
- Enhanced error handling and request management in utility process client.
2026-09-05 20:07:10 +08:00

3.7 KiB

进程隔离

主进程负责窗口、系统集成、权限检查和任务协调。索引、数据库和内容解析通过 Electron utilityProcess 按需启动,避免它们的 CPU 工作、JS 堆和原生模块故障集中在主进程。

进程名称 承担的工作 生命周期
Adnify Code Index BM25、符号表、LanceDB、SQLite 索引、代码解析、本地或远程嵌入 每个工作区一份,首次初始化时启动,工作区关闭时退出
Adnify Session Storage 会话 SQLite、历史加载、备份 首次存储操作时启动,退出时清理连接
Adnify Asset Storage 素材 SQLite、批量事务 首次存储操作时启动,关闭时 checkpoint
Adnify Content Tools PDF/Office 解压解析、Sharp 元数据与预览、调用图解析 按需启动,全部任务结束后空闲 60 秒退出

索引内部保留解析和 SQLite 的 Worker 线程,它们属于索引服务进程。建库和查询的嵌入计算统一由该服务管理,共用模型和速率限制器;本地模型切换等待正在进行的推理完成,然后释放旧模型。切回结构化索引时释放本地模型。同一工作区多个窗口复用一个索引服务,不同工作区各自隔离。

文档中的图片分析通过请求回调交给主进程现有 LLM 流程,函数和模型凭据不传入内容解析进程。文件权限检查仍在主进程执行,子进程只接收已授权任务。内容处理最多并行两项,调用图解析串行复用解析器。Tree-sitter 查询对象在成功和异常路径均释放,混合语言解析在每次解析前重新绑定语言。

文件监听、终端协调和窗口管理继续留在主进程:监听和终端主要等待原生 I/O,语言服务器及搜索命令本来就运行在外部进程。本次拆分针对实际持有索引数据、加载模型、执行同步数据库操作或解析大文件的部分。

请求、退出与恢复

  • 共用 RPC 客户端合并并发启动,最多保留 128 个在途请求,启动上限 10 秒。
  • 存储请求上限 15 秒;普通索引和内容请求 120 秒;全量/增量建库 1 小时;包含图片分析的文档请求 15 分钟。
  • 超时终止该服务,并使其在途请求失败。崩溃后下一次请求可以重新启动服务;失败的写入不会自动重放。索引从持久化缓存加载,被中断的修改需要重新建库核对。
  • 同一客户端等待旧进程退出后才允许重新启动;工作区关闭再打开时也等待上一轮关闭完成。
  • 关闭时拒绝新请求,存储和索引优先执行清理,最多等待 2.5 秒,再终止子进程。应用退出时统一回收服务。

独立进程有自身运行开销,不能直接据此断言应用总内存下降。可以通过性能诊断中的命名 PID 对比主进程和各项服务,结合卡顿复现场景评估收益。

验证

先运行 pnpm build,再运行 node scripts/diagnostics/utility-process-smoke.cjs --asar。脚本使用临时配置、工作区和数据库,不读写用户会话,不连接外部模型服务,也不下载模型。

脚本在真实 Electron 中验证:结构化建库与增量更新、崩溃后缓存恢复、多工作区 PID 隔离、真实 LanceDB 和本机嵌入接口、SQLite 关闭后持久化、Sharp、DOCX 图片回调、调用图解析、超时与空闲退出、主事件循环响应,以及退出后没有残留业务进程。--asar 验证服务和内部 Worker 从 ASAR 路径启动,依赖从开发环境提供,并不替代完整安装包测试。报告保存在 .tmp/utility-process-smoke。

本次原生运行验证环境为 Windows。macOS/Linux 的实际安装包仍需各平台发布流程验证。