客户端安全自更新设计：键盘小鹿流式升级包哈希/签名预检、精确版本范围匹配与无感回退

一、 桌面自更新的三大安全威胁与架构死穴

在 Windows 生态中，免安装绿色客户端的自更新面临着比 Web 应用严峻得多的系统安全挑战：

• T1 & T2 & T3 & T4 -> DefensePipeline
• 1. 投毒攻击与二进制伪造： 很多小型工具软件在更新时，仅仅请求一个 latest.json，获取到下载地址后直接下载并无条件解压执行。一旦更新服务器被 DNS 劫持，或者 CDN 边缘节点遭到中间人攻击，用户电脑将被静默植入恶意木马，造成严重信任危机。
• 2. 覆盖更新引发的“碎布灾难”与数据抹杀： 桌面绿色包解压时，如果将新文件直接解压到旧软件目录： - 若新版本重命名或删除了某些旧 DLL，这些旧 DLL 将残留在目录中引发混合加载冲突； - 更严重的是，如果用户将个人学习数据保存在软件执行根目录，一次粗暴的解压覆盖将直接覆盖数据库或 JSON 进度文件，导致孩子连续几个月积累的星星小屋装扮、错键记录与通关进度瞬间归零。
• 3. Windows 文件锁定（EBUSY: resource busy or locked）： Windows 操作系统的底层文件系统（NTFS）对正在运行的 .exe 与已载入内存的 .dll 施加了强排他锁。如果更新调度器在主程序完全释放句柄前尝试覆盖写，会直接抛出 EBUSY 异常，更新半途而废，导致软件处于“部分新文件、部分旧文件”的不可用状态（变砖）。

二、 键盘小鹿端到端安全自更新拓扑与时序

为确保更新过程“绝对可信、状态可逆、零破坏性”，键盘小鹿设计了严密的全生命周期自更新流程：

• S -> >C: 返回 { hasUpdate: false }
• CDN -> >S: 返回精确 Content-Length 与扇区哈希
• S -> >C: 返回完整更新元数据: { version, downloadUrl, sha256, expectedSigner }
• Win -> >C: 返回证书链状态与发布主体 (Subject)

三、 核心工程实现细节

// server/online/src/modules/release-url-inspector.ts 服务端流式检测器
export interface PackageInspectionResult {
  verified: boolean
  contentLength: number
  lastModified: string
  sha256Probe: string
}

export async function inspectRemoteReleasePackage(
  targetUrl: string
): Promise<PackageInspectionResult> {
  // 1. 发起 HEAD 预检探测
  const headResponse = await fetch(targetUrl, { method: 'HEAD' })
  if (!headResponse.ok) {
    throw new Error(`无法连接目标安装包 URL，HTTP 状态码: ${headResponse.status}`)
  }

  const contentLength = Number(headResponse.headers.get('content-length') || 0)
  if (contentLength < 10 * 1024 * 1024) {
    throw new Error('安装包体积异常过小 (< 10MB)，疑似损坏或截断')
  }

  // 2. 探测文件首部 4KB 扇区，验证 Windows PE 签名头标识 (MZ/PE)
  const rangeResponse = await fetch(targetUrl, {
    headers: { Range: 'bytes=0-4095' }
  })
  const headerBuffer = await rangeResponse.arrayBuffer()
  const headerView = new Uint8Array(headerBuffer)

  // 验证 ZIP (PK..) 或 PE (.exe MZ..) 魔数
  const isZipMagic = headerView[0] === 0x50 && headerView[1] === 0x4b
  const isExeMagic = headerView[0] === 0x4d && headerView[1] === 0x5a

  if (!isZipMagic && !isExeMagic) {
    throw new Error('安装包头部扇区未检测到合法的 ZIP 或 EXE 魔数特征，拒绝入库')
  }

  return {
    verified: true,
    contentLength,
    lastModified: headResponse.headers.get('last-modified') || '',
    sha256Probe: 'verified_magic_header'
  }
}

• 1. 服务端：不落盘 HTTP Range 流式探测器（release-url-inspector.ts）： 在版本发布阶段，管理后台无需从外部下载几百兆完整安装包再计算，而是通过精确的 Range 请求探测 CDN 上的二进制文件真实有效性：
• 2. 客户端：Windows 权威数字签名（Authenticode）强校验： 下载完成后，必须核实文件是由官方专属代码签名证书签发，防止任何未经认证的可执行程序被替换：

四、 工业级排查复盘：Windows 文件锁占用的破局实践

在实现免安装绿色包原子替换时，最棘手的问题莫过于 app.exe 正在运行、操作系统不允许就地重写。

• 1. 传统错误做法的缺陷： 许多开源升级库会在主进程退出前拉起一个外部 update.bat 批处理脚本，在脚本里写 timeout /t 2 然后强制 copy /y。这种设计在遇到老旧电脑或者后台进程退出迟缓时，copy 命令会因为文件仍被锁定而直接抛错中断，导致软件主程序损坏。
• 2. 键盘小鹿的事务级移动方案（Atomic Move-in-Place）： Windows 操作系统的底层 NTFS 提供了一个重要的系统调用特性：正在运行的 EXE 进程虽然不允许被直接修改内容（Write Over），但允许被重命名或移动到其他路径！ 基于这一关键物理事实，键盘小鹿设计了“原子移出换入”流程：
• 重命名备份旧核：将当前的 app.exe 重命名为 app.exe.old（瞬间完成，即便进程正在运行也能成功）；
• 安全放入新核：将隔离区中的新版 app.exe 放入当前目录；
• 拉起新进程与自清：启动新版可执行文件，新程序启动后负责清理带有 .old 标记的历史废弃文件；
• 若出错秒级回滚：如果放入新文件失败，立即将 app.exe.old 重新改回 app.exe，保证任何异常下应用绝不“变砖”。

五、 用户学习资产零损伤与目录物理隔离规范

键盘小鹿严格遵循“程序代码（Read-Only）与用户数据（Stateful）物理分离”的黄金设计原则：

• ExecutionDir -> |升级覆盖只触碰自身| ExecutionDir
• ExecutionDir -> |严格只读访问 / 零冲突| UserDataDir
• - 程序升级只刷新安装目录：所有的 ASAR、EXE、DLL 更新全部在应用安装目录内闭环，绝不把任何用户数据文件存储在程序运行目录下；
• 用户数据受保护常驻：即便用户完全删除了客户端所在的文件夹，重新下载解压新版本后，软件依然能自动从 %APPDATA%\keydeer\ 载入孩子之前的错键记录、成就徽章与星星小屋资产，真正做到了“无感升级、资产永续”。