Kun v0.3.4 深度解析:Windows 安装器进程检测修复与 Runtime/Service Manager 重启恢复机制
Kun v0.3.4 深度解析:Windows 安装器进程检测修复与 Runtime/Service Manager 重启恢复机制
Kun v0.3.4 是一个面向 Windows 平台的稳定性热修复版本,核心解决两类问题:安装器在升级/卸载前的进程检测误报,以及正常退出后再次启动时被陈旧 Runtime 注册卡死在 active_writer 启动恢复页面的故障。本文基于发布说明 release/release-v0.3.4.md,结合仓库中 NSIS 安装器宏、PowerShell 迁移脚本和主进程 Runtime 协调源码,完整讲解这两处修复的实现原理、验证方式与升级操作步骤,帮助 Windows 用户理解故障根因并安全地完成热修复升级。
版本定位:不迁移、不删数据的热修复
v0.3.4 建议所有使用 v0.3.3 的 Windows 用户尽快通过应用内更新(如已启用)或下载安装包升级。需要特别强调的是:本次更新不迁移、不删除任何会话、设置或工作区数据,属于纯稳定性修复,用户数据面完全不受影响。完整变更清单为 v0.3.3 到 v0.3.4 之间的提交差异(发布文档中给出的 compare 链接指向上游仓库,此处不再贴出外链)。
从当前仓库主干看(package.json 中版本已演进至 0.3.10 之后),这两处修复的关键实现仍然保留在主代码路径中,可以作为理解 Kun 在 Windows 上进程管理整体设计的入口。
Windows 安装器进程检测修复(#1179)
修复前的问题
在 v0.3.3 及之前,升级或卸载前的进程检查存在一个语义混淆的缺陷:当安装器无法检查进程(例如 CIM 进程枚举失败、权限或安全校验异常)时,会被误报为“Kun 无法关闭”,提示用户去关闭应用。实际上应用可能根本没有运行,用户陷入“关不掉”的死循环。
v0.3.4 将这两种情况明确区分:
- 只有已验证仍有 Kun 应用进程占用安装目录时,才提示用户关闭 Kun 并重试;
- 进程枚举、权限或安全校验发生异常时,显示独立的安装检查失败提示并保留诊断信息,不再伪装成“应用仍在运行”;
- 自动更新保持失败保护:无法安全确认安装目录未被占用时,更新会停止而不会覆盖可能正在使用的文件。
源码实现:NSIS 层的三路分支
修复的核心逻辑位于 NSIS 安装器宏 customCheckAppRunning。该宏在卸载场景(BUILD_UNINSTALLER)下被调用,工作流如下:
- 安装器将自身 PID(
KUN_INSTALLER_SELF_PID)、应用根目录(KUN_INSTALLER_APP_ROOT)、规范可执行文件名等通过环境变量注入,并生成诊断日志路径$TEMP\Kun-installer-process-check-<PID>.log; - 调用捆绑的 PowerShell 迁移助手执行
StopProcesses动作,并读取退出码($KunInstallerHelperExitCode); - 根据退出码做三路分支:
| 退出码 | 语义 | 行为 |
|---|---|---|
0 |
安装目录下的应用进程已全部停止 | 继续安装/卸载 |
2 |
已验证进程仍在运行,多次停止尝试(最多 5 次重试、每次间隔 1.2 秒)后仍存活 | 手动安装弹出“应用无法关闭”对话框供用户重试;自动更新则中止并记录 process_stop_failed |
其他(含 1) |
无法安全地检查进程(枚举/权限/安全校验异常) | 手动安装弹出独立的“无法安全检查旧安装是否仍在使用文件”对话框并给出诊断日志路径;自动更新中止并记录 process_check_failed |
自动更新的中止动作由 KunAbortAutomaticUpdate 宏统一处理,process_check 与 process_stop 两个阶段码保证诊断上可以区分“检查失败”和“停止失败”。
源码实现:PowerShell 层的进程识别与停止
StopProcesses 动作的实现在 build/windows-installer-migration.ps1 中:
- 调用
Stop-InstallRootProcesses,若返回Outcome = 'running',向 stderr 输出KUN_INSTALLER_STOP_RESULT=running pids=...并以退出码2结束; - 若动作执行过程中发生任何异常(包括进程枚举失败),进入
catch分支,输出KUN_INSTALLER_STOP_RESULT=inspection-failed并以退出码1结束。注释明确说明:NSIS 调用方依赖这一约定来区分“安全检查失败”与“验证后的残留应用进程”,且不向 stderr 暴露任意 PowerShell 错误细节或安装路径。
进程识别与停止的底层函数在 build/windows-installer-migration-filesystem.ps1:
Get-VerifiedAppProcesses通过Get-CimInstance Win32_Process枚举进程,任何枚举异常都会抛出The installer could not inspect Windows processes.——这正是退出码1(inspection-failed)的来源,而不是running;Test-AppOwnedProcessPath只认定可执行文件路径位于安装根目录下且属于应用身份文件(或位于resources\、bin\子树) 的进程为“本应用进程”,避免误伤同名的第三方进程;Stop-AppProcesses最多进行 6 轮taskkill /PID <pid> /T /F(连同子进程树)加 500ms 等待,全部结束后仍存活才返回Outcome = 'running'及阻塞进程诊断(PID、父 PID、名称、可执行路径)。
从源码结构看,这套“先验证归属、再停止、最后区分 running 与 inspection-failed”的设计,正是发布说明中“只会在已验证仍有 Kun 应用进程占用安装目录时提示关闭”“无法安全确认时停止自动更新而不覆盖文件”两条承诺的直接落地。
Runtime 与 Service Manager 重启恢复(#1180)
故障场景
Kun 的 GUI 是共享 Kun Runtime 的客户端之一:正常关闭 GUI 后,Runtime 与 Service Manager 按设计保持存活,供其他客户端(如 TUI、IM 通道)继续使用。v0.3.3 的缺陷在于:Runtime 已退出但 Manager 中残留了陈旧注册记录时,下次启动会把无法检查的 Runtime 判定为“活跃写者(active writer)”,产生 active_writer: production Runtime could not be inspected 错误并阻止启动。
v0.3.4 的修复策略是:
- 普通关闭 GUI 后,共享 Runtime 仍可被复用;新的 GUI 启动通过 Service Manager 安全接管或复用健康 Runtime,而不是先强制终止它;
- 已退出 Runtime 留下的 Manager 注册会被自动识别并清理,随后启动可正常继续;
- 对仍存活但无法验证身份或无法响应的进程,继续采取安全失败(fail-closed)策略,避免误终止其他用户、客户端或数据目录所有者。
源码实现:对账(reconciliation)优先于检查
核心入口是 listServiceManagerRuntimeActiveWork(位于 src/main/runtime/),它负责在存储迁移/启动检查前枚举 Service Manager 管理的两种 Runtime flavor(production、development)上的活跃工作:
- 先调用 reconcileDeadManagerRuntimeRegistrations 对账:只清理记录中的 owner PID 已被证明已退出的 Manager 槽位。
inspectSharedRuntime会认证 Manager、校验 PID,并删除确切的陈旧 instanceId; - 对账之后,逐个读取各 flavor 的 Runtime 注册,通过
GET {baseUrl}/v1/threads?limit=500&include=side(5 秒超时)检查是否存在queued/in_progress/started/running状态的线程或轮次; - 如果 Runtime 存活但 HTTP 探测失败(无法验证身份或无响应),将其登记为
kind: 'external-writer'、interruptible: false的条目,标签即错误页上看到的production Runtime could not be inspected。源码注释明确解释了设计边界:“一个无法检查的存活 owner 仍然是外部写者,保持迁移的 fail-closed 边界”。
这个“先对账、再检查”的顺序正是本次修复的关键:陈旧注册在到达活跃工作检查之前已被移除,因此不再阻断启动;而真正存活但无法验证的进程仍会被保守地视为外部写者,绝不盲杀。
测试验证
单元测试 service-manager-runtime-active-work.test.ts 恰好覆盖了这两条路径:
removes a dead Manager registration before migration sees an external writer:Manager 中 production 槽位指向一个已死的 PID,断言对账会向DELETE /v1/runtimes/production/runtime-a发起删除,最终活跃工作列表为空(启动可继续);keeps a live but unresponsive Runtime as a non-interruptible external writer:注册 PID 存活但对/v1/runtime/info与线程列表均返回 503,断言结果为单条external-writer记录,且全程没有发起任何 DELETE 请求——验证了 fail-closed 策略未被破坏。
启动恢复流程的配合
启动侧的 recoverManager 与 recoverStartupManager 构成完整的启动恢复链路:
- 在
withManagerStartLock启动锁内读取 handoff 发现记录,并校验dataDir、settingsPath的规范路径是否与当前安装一致(不一致则直接抛出 scope 不匹配错误,防止误接管其他数据目录的 Manager); inspectServiceManager三次探测后,若 Manager 状态为ready且 buildId 匹配,则直接复用现有连接,不做替换;- 只有在确需替换时,才通过
drainKunOwnersForHandoffWithLock证明两个 flavor 槽位与身份后替换 Manager。源码注释强调:“不可用的认证状态绝不会被解释为空槽位”——与 fail-closed 原则一致。
此外,src/main/main-migrations.ts 中保留的 active_writer: ... 系列错误(如 Failed to interrupt、Timed out waiting for active Kun writes to stop)说明 active_writer 是存储迁移/数据目录接管中一类受保护的启动阻断错误码;v0.3.4 修复的正是其中“陈旧注册导致的误阻断”这一分支,而非弱化保护本身。
热修复升级实操指引
发布文档给出的升级步骤(建议原文照做):
- 能正常打开 Kun 时:在启用自动更新后安装此热修复;若当前无法启动,请下载 v0.3.4 Windows 安装包覆盖安装;
- 已卡在启动错误页时:先在任务管理器中结束所有名称为 Kun 的进程,再启动或安装;不要结束其他 Node、Electron 或 MCP 进程;
- 数据影响:强制结束 Kun 会中断正在执行的回复或任务,但不会删除已保存的会话数据。
结合安装器实现可以补充两点操作理解:
- 若在 v0.3.4 安装过程中看到“无法安全检查旧安装是否仍在使用文件”的新式提示(而非旧版“应用无法关闭”),这是进程检查失败分支的正常行为,按提示重启 Windows 后重试,并可发送提示中的诊断日志(位于
%TEMP%\Kun-installer-process-check-<PID>.log); - 自动更新在进程占用未解除时会主动中止并保留原安装目录,这与手动覆盖安装的行为一致——不会覆盖正在被使用的文件,因此可以安全重试。
关键文件索引
| 文件 | 作用 |
|---|---|
| release/release-v0.3.4.md | 本版本的发布说明原文 |
| build/installer-process-check.nsh | NSIS 安装器进程检查宏,区分 running 与 inspection-failed |
| build/windows-installer-migration.ps1 | 安装器 PowerShell 助手,StopProcesses 动作与退出码约定 |
| build/windows-installer-migration-filesystem.ps1 | 进程归属验证(Test-AppOwnedProcessPath)与 taskkill 停止逻辑 |
| build/installer-automatic-update.nsh | 自动更新中止宏 KunAbortAutomaticUpdate |
| src/main/runtime/service-manager-runtime-active-work.ts | 对账后枚举 Runtime 活跃工作,生成 external-writer 条目 |
| src/main/runtime/service-manager-runtime-reconciliation.ts | 清理 owner PID 已死陈旧的 Manager 注册 |
| src/main/runtime/service-manager-runtime-active-work.test.ts | 覆盖“清除死注册”与“保留存活但无响应 Runtime”两条路径的测试 |
| src/main/runtime/kun-startup-manager-recovery.ts | 启动时 Manager 的锁内检查、scope 校验与复用/替换决策 |
小结
v0.3.4 的两处修复都遵循同一条工程原则:把“检查失败”与“确认存在冲突”彻底分开,宁可安全失败也不做破坏性动作。安装器侧,进程枚举异常不再伪装成“应用无法关闭”,并保留诊断日志;Runtime 侧,只有 owner PID 被证明已死的注册才会被清理,存活但无法验证的进程永远被视为不可中断的外部写者。对 Windows 用户而言,这意味着升级/卸载更少的误报、启动更少的死锁;对阅读源码的开发者而言,build/ 下的 NSIS+PowerShell 双栈与 src/main/runtime/ 下的对账逻辑共同展示了桌面 Agent 应用在共享 Runtime 架构下处理进程生命周期的一个完整样本。