nikelaluo/update-system

Fork 0

Files

T

nikelaluo e9a2400c48 chore: prepare repository for submodule split

2026-07-09 09:00:51 +00:00

8.2 KiB

Raw Blame History

UpdateClientSDK 接入说明

这个 SDK 是“独立更新器 SDK / 升级运行时 SDK”。它不是传统的 include + lib 形态，而是把自动升级能力作为一组独立程序交给业务软件使用。

SDK 核心程序：

Launcher.exe：用户入口。检查版本、验证策略，决定启动业务主程序或启动 Updater。
Updater.exe：下载、校验、备份、安装、健康确认、提交或回滚。
Bootstrap.exe：替换运行中可能被占用的 EXE/DLL。
config/app_config.json：接入方配置。
config/manifest_public_key.pem：验证服务端签名用的公钥。

接入方需要做什么

假设接入的软件叫 YourApp.exe。

在服务端管理后台创建应用，例如 app_id=your_app_id。
创建或确认渠道，例如 stable。
创建 License，把生成的 license_key 填到客户端配置。
把业务软件完整安装目录作为发布根目录，例如 SimCAE\，其中主程序位于 bin\SimCAE.exe。
把 SDK 的 Launcher.exe、Updater.exe、Bootstrap.exe 放到 SimCAE\bin\ 目录，和 SimCAE.exe 同级。不要覆盖 SimCAE 自带的 Qt5*.dll 和 Qt 插件目录。
把 config/app_config.example.json 复制成 SimCAE\bin\config\app_config.json 并修改字段。
用户入口改成 Launcher.exe，不要直接双击业务主程序。
在管理后台发布新版本时，选择包含业务主程序和 SDK 运行时的干净 Release 根目录。

安装目录写权限要求

当前 SDK 会在 Launcher.exe 所在目录下写入运行时状态文件。SDK 放在 SimCAE\bin 时，这些文件实际位于 SimCAE\bin 下，例如：

config/app_config.json
config/client_identity.dat
config/local_state.json
config/version_policy.dat
update/
update_temp/

所以联调和普通运行时，Launcher.exe 所在目录必须允许当前 Windows 用户写入。不要直接把联调目录放在 C:\Program Files\... 后用普通用户启动；该目录默认禁止普通程序写文件，会导致首次启动报错，例如 cannot save installation id。

推荐联调目录：

D:\SimCAE_Release\
C:\Users\<你的用户名>\Desktop\SimCAE_Release\

如果最终产品必须安装到 C:\Program Files\SimCAE\bin，需要额外设计管理员提权、Windows 服务，或把运行时状态迁移到 ProgramData / AppData。当前交付版本默认按“安装目录可写”的模式工作。

SimCAE 目录结构建议

SimCAE 当前安装目录是根目录下有 bin/、Licenses/、installerResources/ 等子目录。SDK 推荐放在 bin/ 目录，和 SimCAE.exe 同级；后台发布时仍选择整个安装根目录：

SimCAE/
  bin/
    Launcher.exe
    Updater.exe
    Bootstrap.exe
    SimCAE.exe
    config/
      app_config.json
      manifest_public_key.pem
    update/
      manifest_cache/
    Qt5Core.dll
    ...
  Licenses/
  installerResources/
  maintenancetool.exe

这种模式下，后台“发布新版本”时选择整个 SimCAE/ 目录，服务端会检查 bin/SimCAE.exe 是否存在，并把整个安装结构写入 Manifest。客户端配置里 install_root 填 ..，表示被更新的安装根目录是 bin 的上一级；升级事务、下载缓存和 Manifest 缓存仍放在 SimCAE\bin\update。

注意：SimCAE 自己已经带有 Qt 运行库。SDK 的 Launcher/Updater 应使用和 SimCAE 兼容的 Qt 编译，并复用 SimCAE 的 Qt5*.dll、platforms/、imageformats/ 等目录。不要把另一套 Qt DLL 覆盖到 SimCAE\bin，否则会出现“无法定位程序输入点”一类错误。

app_config.json 关键字段

{
  "app_id": "simcae",
  "app_name": "SimCAE",
  "channel": "stable",
  "current_version": "1.0.0",
  "client_protocol": "3",
  "launch_token": "SimCAE_Launch_Token_2026_ChangeMe_32Bytes",
  "license_key": "",
  "api_base_url": "http://YOUR_SERVER_IP:8000",
  "client_token": "SimCAEClientToken2026",
  "request_timeout_ms": "5000",
  "temp_folder": "update_temp",
  "device_id": "",
  "install_root": "..",
  "main_executable": "SimCAE.exe",
  "launcher_executable": "Launcher.exe",
  "updater_executable": "Updater.exe",
  "bootstrap_executable": "Bootstrap.exe",
  "health_check_timeout_ms": "15000",
  "platform": "windows",
  "arch": "x64"
}

字段说明：

app_id：服务端应用 ID，默认填 simcae；如果后台创建了别的 App ID，这里同步修改。
channel：发布渠道，例如 stable、beta、dev。
current_version：当前客户端初始版本。
client_protocol：客户端协议号，当前建议为 3。
api_base_url：服务端 API 地址，例如 http://192.168.229.128:8000；服务器 IP 无法提前知道，所以这里需要按现场地址修改。
client_token：服务端 .env 中的 CLIENT_API_TOKEN，默认交付包已填 SimCAEClientToken2026。
license_key：管理后台创建 License 后返回的密钥；模板里先留空，创建授权后再填。
launch_token：本机启动票据 HMAC 密钥，模板已给默认值，可试跑；正式交付建议改成你自己的 32 字符以上随机字符串。
install_root：安装根目录相对 Launcher.exe 所在目录的位置。SDK 放在 bin 时填 ..。
main_executable：业务主程序相对 Launcher.exe 所在目录的路径，SimCAE 默认填 SimCAE.exe。
health_check_timeout_ms：升级后等待业务程序写健康标记的时间。

业务主程序需要配合什么

当前安全模式下，业务主程序需要配合两件事：

接收 --ticket-file=<path> 参数，验证并消费一次性启动票据。
如果收到 --health-file=<path> 参数，启动成功后向该路径写入 ok\n，让 Updater 确认新版本可用。

当前仓库里的 client/MainApp/main.cpp 是接入示例，已经实现了：

启动票据校验。
本地 License/设备身份校验。
本地策略校验。
Manifest 完整性校验。
健康标记写入。

如果第三方业务程序暂时不想改代码，可以先使用当前 MainApp.exe 作为 Demo 验证 SDK 包；真正接入时建议把这些启动检查逻辑移植到业务主程序。

如何生成 SDK 包

在 Windows PowerShell 中执行：

cd client
.\package-sdk.ps1 `
  -SourceDir .\out\bin `
  -OutputDir .\dist\UpdateClientSDK `
  -ZipFile .\dist\UpdateClientSDK.zip `
  -SdkVersion 0.1.0

默认生成的 SDK 不包含 Qt 运行库，避免覆盖业务软件自带的 Qt。只有在接入的软件本身不带 Qt，且你确认要让 SDK 自带一套 Qt 运行库时，才额外添加 -IncludeQtRuntime。

生成结果：

dist/UpdateClientSDK/
  SimCAE自动升级SDK接入说明_v0.1.docx
  sdk_manifest.json
  bin/
  config/
    app_config.json
    manifest_public_key.pem
  scripts/

把 UpdateClientSDK.zip 发给接入方即可。

如何生成某个产品的最终客户端包

SDK 是给开发者接入用的，最终给用户安装/分发时，可以使用：

cd client
.\package-client.ps1 `
  -SourceDir .\out\bin `
  -ConfigFile .\config\app_config.json `
  -OutputDir .\dist\UpdateClient `
  -ZipFile .\dist\UpdateClient.zip

package-client.ps1 会检查配置和必需文件，并生成具体产品的客户端包。

常见错误

直接启动业务主程序提示 ticket 错误：应从 Launcher.exe 启动。
首次启动提示 cannot save installation id：当前目录不可写，常见于 C:\Program Files\...；请换到可写目录联调，或用管理员权限/提权方案。
首次启动设备登记失败：检查 api_base_url、client_token、license_key、服务端 License 状态。
策略或 Manifest 验签失败：检查 config/manifest_public_key.pem 是否和服务端私钥匹配。
升级后回滚：检查业务程序是否在 health_check_timeout_ms 内写入健康标记。
发布失败提示主程序不在根目录：选择发布目录时要选择业务主程序所在目录，而不是上层或下层目录。
启动时提示 无法定位程序输入点 ... Qt5*.dll：通常是 Qt DLL 被不同版本覆盖或混用。恢复业务软件原始 Qt DLL，并重新打包 SDK；SimCAE 场景下不要使用 -IncludeQtRuntime。

8.2 KiB Raw Blame History