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 填到客户端配置。
把业务程序和依赖 DLL 放到同一个发布目录。
把 SDK 的 Launcher.exe、Updater.exe、Bootstrap.exe 和运行时 DLL 放到该目录。
把 config/app_config.example.json 复制成 config/app_config.json 并修改字段。
用户入口改成 Launcher.exe，不要直接双击业务主程序。
在管理后台发布新版本时，选择包含业务主程序和 SDK 运行时的干净 Release 根目录。

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": "",
  "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 字符以上随机字符串。
main_executable：业务主程序文件名，默认填 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

生成结果：

dist/UpdateClientSDK/
  README.md
  bin/
  config/
  scripts/
  samples/

把 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 启动。
首次启动设备登记失败：检查 api_base_url、client_token、license_key、服务端 License 状态。
策略或 Manifest 验签失败：检查 config/manifest_public_key.pem 是否和服务端私钥匹配。
升级后回滚：检查业务程序是否在 health_check_timeout_ms 内写入健康标记。
发布失败提示主程序不在根目录：选择发布目录时要选择业务主程序所在目录，而不是上层或下层目录。

5.1 KiB Raw Blame History