130 lines
5.1 KiB
Markdown
130 lines
5.1 KiB
Markdown
|
# 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`。
|
||
|
|
|
||
|
|
1. 在服务端管理后台创建应用，例如 `app_id=your_app_id`。
|
||
|
|
2. 创建或确认渠道，例如 `stable`。
|
||
|
|
3. 创建 License，把生成的 `license_key` 填到客户端配置。
|
||
|
|
4. 把业务程序和依赖 DLL 放到同一个发布目录。
|
||
|
|
5. 把 SDK 的 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` 和运行时 DLL 放到该目录。
|
||
|
|
6. 把 `config/app_config.example.json` 复制成 `config/app_config.json` 并修改字段。
|
||
|
|
7. 用户入口改成 `Launcher.exe`，不要直接双击业务主程序。
|
||
|
|
8. 在管理后台发布新版本时，选择包含业务主程序和 SDK 运行时的干净 Release 根目录。
|
||
|
|
|
||
|
|
## app_config.json 关键字段
|
||
|
|
|
||
|
|
```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`：升级后等待业务程序写健康标记的时间。
|
||
|
|
|
||
|
|
## 业务主程序需要配合什么
|
||
|
|
|
||
|
|
当前安全模式下，业务主程序需要配合两件事：
|
||
|
|
|
||
|
|
1. 接收 `--ticket-file=<path>` 参数，验证并消费一次性启动票据。
|
||
|
|
2. 如果收到 `--health-file=<path>` 参数，启动成功后向该路径写入 `ok\n`，让 Updater 确认新版本可用。
|
||
|
|
|
||
|
|
当前仓库里的 `client/MainApp/main.cpp` 是接入示例，已经实现了：
|
||
|
|
|
||
|
|
- 启动票据校验。
|
||
|
|
- 本地 License/设备身份校验。
|
||
|
|
- 本地策略校验。
|
||
|
|
- Manifest 完整性校验。
|
||
|
|
- 健康标记写入。
|
||
|
|
|
||
|
|
如果第三方业务程序暂时不想改代码，可以先使用当前 `MainApp.exe` 作为 Demo 验证 SDK 包；真正接入时建议把这些启动检查逻辑移植到业务主程序。
|
||
|
|
|
||
|
|
## 如何生成 SDK 包
|
||
|
|
|
||
|
|
在 Windows PowerShell 中执行：
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
cd client
|
||
|
|
.\package-sdk.ps1 `
|
||
|
|
-SourceDir .\out\bin `
|
||
|
|
-OutputDir .\dist\UpdateClientSDK `
|
||
|
|
-ZipFile .\dist\UpdateClientSDK.zip `
|
||
|
|
-SdkVersion 0.1.0
|
||
|
|
```
|
||
|
|
|
||
|
|
生成结果：
|
||
|
|
|
||
|
|
```text
|
||
|
|
dist/UpdateClientSDK/
|
||
|
|
README.md
|
||
|
|
bin/
|
||
|
|
config/
|
||
|
|
scripts/
|
||
|
|
samples/
|
||
|
|
```
|
||
|
|
|
||
|
|
把 `UpdateClientSDK.zip` 发给接入方即可。
|
||
|
|
|
||
|
|
## 如何生成某个产品的最终客户端包
|
||
|
|
|
||
|
|
SDK 是给开发者接入用的，最终给用户安装/分发时，可以使用：
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
cd client
|
||
|
|
.\package-client.ps1 `
|
||
|
|
-SourceDir .\out\bin `
|
||
|
|
-ConfigFile .\config\app_config.json `
|
||
|
|
-OutputDir .\dist\UpdateClient `
|
||
|
|
-ZipFile .\dist\UpdateClient.zip
|
||
|
|
```
|
||
|
|
|
||
|
|
`package-client.ps1` 会检查配置和必需文件，并生成具体产品的客户端包。
|
||
|
|
|
||
|
|
## 常见错误
|
||
|
|
|
||
|
|
1. 直接启动业务主程序提示 ticket 错误：应从 `Launcher.exe` 启动。
|
||
|
|
2. 首次启动设备登记失败：检查 `api_base_url`、`client_token`、`license_key`、服务端 License 状态。
|
||
|
|
3. 策略或 Manifest 验签失败：检查 `config/manifest_public_key.pem` 是否和服务端私钥匹配。
|
||
|
|
4. 升级后回滚：检查业务程序是否在 `health_check_timeout_ms` 内写入健康标记。
|
||
|
|
5. 发布失败提示主程序不在根目录：选择发布目录时要选择业务主程序所在目录，而不是上层或下层目录。
|