软件自更新模块总览 - Overview

本分类做什么

在已对接授权平台的前提下，由用户主动触发完成软件包下载、校验、安装/覆盖，并支持进度查询、错误日志读取与中断回滚。

与授权「查询更新」的分工（勿混淆）

需求	使用接口
仅查询是否有新版本、更新说明、下载地址	GetSoftUpdateStatus / GetSoftUpdateLogs
真正下载并安装/覆盖	本模块 SoftUpdateStart 等

当前包含 5 个接口：

• 启动软件自更新 - SoftUpdateStart
• 获取自更新进度 - SoftUpdateGetProgress
• 获取最近更新状态 - SoftUpdateGetLastStatus
• 获取最近更新错误 - SoftUpdateGetLastError
• 恢复中断的更新 - SoftUpdateTryRecover

---

一、接口职责对照

接口	典型目的
SoftUpdateStart	查询元数据→下载→MD5 校验→释放内嵌 Updater→启动升级进程。
SoftUpdateGetProgress	查询当前进程内下载/准备阶段进度（可选做进度条）。
SoftUpdateGetLastStatus	无日志/成功 → Code=1；有失败日志 → Code=0 并返回失败详情。
SoftUpdateGetLastError	读取最近一次失败摘要与日志路径。
SoftUpdateTryRecover	zip/rar 更新中断时从 backup 回滚。

---

二、推荐使用流程

顺序	步骤	说明
1	调用 GetSoftUpdateStatus	展示更新说明；IsForceUpdate 时提示必须更新。
2	用户确认后调用 SoftUpdateStart	传入安装根目录、可选静默参数与完成后启动路径。
3	（可选）轮询 SoftUpdateGetProgress	下载阶段进度；默认可静默。
4	若返回 NeedExit=true	退出宿主进程，释放文件锁，让 Updater 继续。
5	Updater 完成 zip/rar 覆盖或 exe 安装	可选自动拉起主程序。成功后日志清理；再用 SoftUpdateGetLastStatus 时通常 Code=1。
6	失败时读 SoftUpdateGetLastStatus / SoftUpdateGetLastError	Code=0 或查看 installRoot\.ola_update\logs\。

---

三、包类型与安全策略

包类型	行为
.zip / .rar	解压到 staging → 正式文件先备份 → rename/move 提交；失败从 backup 回滚。
.exe / .msi	等待宿主退出后，按调用方传入的 silentArgs 静默执行安装器。

SoftUpdateGetLastStatus / last_status.json 字段统一 PascalCase：Phase、StatusCode、Detail、Version、Package、PackageType、Percent、LogFile、UpdatedAt（另有接口层 Code/Message）。

安装根目录 installRoot 必须由调用方传入。日志与缓存位于：

installRoot\
  .ola_update\          # 缓存、staging、backup、logs、进行中标志
    logs\               # last_status.json / last_error.txt / 会话日志（成功后删除）

成功后 Updater 会清理会话日志、该版本的下载包/staging/backup，以及遗留的根目录 update_logs\，避免污染 exe 运行目录；失败时保留日志便于排查。

---

四、进度与 UI

• 默认静默更新，不强制弹窗。
• 需要进度条：下载阶段用 SoftUpdateGetProgress；宿主退出后看 last_status.json（或 SoftUpdateGetLastStatus）的 Phase / Percent / Detail。
• 更新结束后：SoftUpdateGetLastStatus 的 Code==1 表示成功或无失败日志；Code==0 表示失败。

---

五、详细 Demo 流程（SoftUpdateDemo）

仓库旁示例工程：ola.demo/SoftUpdateDemo（AppHost + PayloadApp + MockInstaller + 本地 HTTP 包）。

5.1 准备

1. 准备带自更新导出的 OLAPlug DLL（含内嵌 ola_updater.exe）。
2. 在 common/demo_config.h 填入 UserCode / SoftCode / DLL 路径 / 当前 softVersion。
3. 一键构建与沙箱部署：

cd D:\code\olaplug\ola.demo\SoftUpdateDemo
.\scripts\build_all.ps1

脚本会：编译 AppHost / PayloadApp / MockInstaller → 打 packages\update_2.0.0.zip → 部署 sandbox\install\（仅宿主 + DLL，不旁路拷贝 updater）。

5.2 本地 FileUrl（推荐联调）

后台若暂无真实包地址，可用本地 HTTP：

.\scripts\serve_local_package.ps1

控制台会打印 FileName / Size / Md5 / FileUrl（形如 http://127.0.0.1:8765/...）。把后台该版本的下载字段改成这些值；保持脚本运行，再在 AppHost 里点更新。

不要用 file://；下载走 HTTP，与线上一致。

5.3 宿主内操作顺序

1. 启动 sandbox\install\AppHost.exe。
2. （可选）菜单：GetSoftUpdateStatus / GetSoftUpdateLogs —— 确认有新版本与说明。
3. 菜单：SoftUpdateStart —— 内部下载到 .ola_update\cache\<ver>\，释放 updater，拉起进程。
4. （可选）轮询 SoftUpdateGetProgress —— 观察 downloading / verifying / launching。
5. 若返回 NeedExit=true：退出 AppHost，否则 zip 覆盖可能因文件占用失败。
6. Updater 等待宿主退出后解压/提交（或跑安装器）；成功后清理日志与临时目录，可选 --launch 拉起新程序。
7. 再次启动 AppHost / 新版本程序后调用 SoftUpdateGetLastStatus：
   • 成功清理后通常 Code=1、Message=success（无失败日志）。
   • 若失败则 Code=0，Message/Detail 为失败原因；也可用 SoftUpdateGetLastError。
8. 若曾中断 zip 提交，可调 SoftUpdateTryRecover 从 backup 回滚。

5.4 验收检查点

检查项	期望
更新成功	业务文件/版本号变为新版本；安装根下无多余 update_logs\；.ola_update\logs 已清理
SoftUpdateGetLastStatus	成功后 Code=1；失败后 Code=0 且带失败文案
Updater 来源	来自 DLL 内嵌释放到 .ola_update\cache\ola_updater.exe，而非安装目录旁路拷贝
失败可排障	.ola_update\logs\update_*.log 与 last_error.txt 仍在

5.5 最小代码骨架（C++ SDK）

#include "OLAPlugServer.h"

OLAPlugServer ola;
const char* installRoot = "C:\\App";

// 1) 仅查询（可选）
auto query = ola.GetSoftUpdateStatus("user", "soft", "1.0.0", "dealer");

// 2) 用户确认后启动
auto start = ola.SoftUpdateStart(
    "user", "soft", "1.0.0", "dealer",
    installRoot, /*silentArgs*/ "", /*launchPath*/ "C:\\App\\MyApp.exe", /*waitPid*/ 0);
if (start.Code == 1 && start.NeedExit) {
    // 退出当前进程，让 Updater 继续
    return 0;
}

// 3) 下次启动或旁路进程查询结果
auto status = ola.SoftUpdateGetLastStatus(installRoot);
if (status.Code == 0) {
    // 失败：status.Message / status.Detail
}