跳到主要内容

🩺 GeneralUpdate 故障排查

综合性诊断系统 — 覆盖 50+ 已知问题，均可追溯到 GitHub/Gitee Issue 或代码审计发现。

工作流程​

1. 症状收集
   ├── 用户描述的症状是什么？
   ├── 错误信息/堆栈是什么？
   ├── GeneralUpdate 版本号？
   ├── 平台（Windows/Linux/macOS）？
   └── 更新策略（标准/OSS/静默）？

2. 症状匹配 → 查找 reference.md
   ├── 找到匹配的 Q/C/H/M/L → 给出根因 + 修复 + 代码
   └── 未找到匹配 → 执行通用诊断流程（6步骤）

3. 提供修复
   ├── 具体的代码修改、配置调整、版本升级建议
   └── 预防措施（如何避免再发生）

4. 验证
   └── 确认修复后问题解决

症状分级​

reference.md 中的问题按严重度分级：

级别颜色含义数量
C🔴 致命阻断性故障、数据损坏、安全漏洞8
H🟠 高场景阻断、功能失效、需要升级11
M🟡 中功能异常、需要配置调整20
L🔵 低代码气味、边缘情况、已知行为12

C 级（Critical）— 阻塞升级​

问题原因排查/解决
升级没启动LaunchAsync() 未调用 / UpgradeApp.exe 未部署确认 Bootstrap.LaunchAsync() 在 Main() 中调用
Method not foundClient 和 Upgrade NuGet 版本不一致统一 NuGet 版本, 清理 bin/obj 后重新生成
路径超长 (>260)Windows 路径限制缩短安装路径
IPC 暴露IPC 加密密钥硬编码使用强 AppSecretKey; 更新到 v10.4.6+
跨租户泄露服务端多租户隔离缺失每个租户独立 ProductId + AppSecretKey
ZIP 遍历写入恶意 ZIP 含 ../ 路径v10.4.6+ 已修复
BSDIFF 整数溢出大文件差分补丁计算溢出使用 HDiffPatch 算法
静默不生效进程退出时未触发确保正确调用 Close() 或 Dispose()

H 级（High）— 严重但不阻塞启动​

问题原因排查/解决
无限循环更新manifest.json 版本号未回写更新到 v10.4.6+（已修复 WriteBack）
OSS 无更新Bucket 配置错误 / versions.json 格式不对curl 测试 OSS URL 是否可下载
文件占用目标文件被占用关闭主进程后更新; 排除杀软扫描目录
SignalR 推送无响应连接断开或认证失败检查 SignalR Hub 状态和 Token 配置
Bowl 不守护进程名配置错误确认 ProcessNameOrId 与实际进程名一致
差分更新失败基准文件不匹配校验原始文件哈希匹配
下载进度不动IDownloadService 未正确绑定确认桥接实现是否正确
跨版本跳跃失败中间版本包缺失确保服务端保留了所有版本的补丁

M 级（Medium）— 功能降级​

问题原因排查/解决
AOT 编译失败反射代码未适配 NativeAOT添加 [DynamicDependency] 属性
SignalR 重连慢RetryDelay 配置过长调整重连参数
日志不输出日志路径权限不足检查 %TEMP%/GeneralUpdate/logs/ 权限
多租户配置错误ProductId 冲突确保每个租户唯一 ProductId
黑名单不生效格式配置错误确认文件名和扩展名格式正确

L 级（Low）— 非关键​

问题原因排查/解决
分发包过大未使用差分差分已内嵌在 Core，启用 PatchEnabled 即可
首次更新慢CDN 冷启动预热 CDN
更新后配置丢失黑名单未包含配置目录确认 SkipDirectorys 包含配置文件夹

通用诊断流程（6 步）​

当问题无法直接匹配到已知症状时，执行以下 6 步排查：

  1. 版本一致性检查 — Client 和 Upgrade 的 NuGet 版本是否一致？
  2. manifest.json 验证 — 文件是否存在？字段值是否正确？
  3. UpgradeApp 存在性 — UpgradeApp.exe 是否在预期目录？
  4. 网络可访问性 — UpdateUrl 能否用 curl 访问？
  5. 日志分析 — 查看 %TEMP%/GeneralUpdate/logs/ 下的日志文件
  6. 最小重现 — 从 Minimal 集成开始，逐步增加复杂度

日志文件位置​

平台默认路径
Windows%TEMP%/GeneralUpdate/logs/
Linux/tmp/GeneralUpdate/logs/

安全注意事项​

  • AppSecretKey 管理 — 硬编码在客户端是最后手段; 优先从启动参数或环境变量注入
  • 定期轮换 IPC 加密密钥
  • 生产环境禁用调试日志

相关技能​