nikelaluo/update-client
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(client): 迁移Hub更新客户端实现

Browse Source
This commit is contained in:
laluo
2026-09-08 17:08:58 +08:00
parent 0c500024e6
commit 8dfef45bc4
34 changed files with 2032 additions and 2903 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Docs/00-先读我-客户端文档入口.txt
+11 -72
View File
@@ -1,81 +1,20 @@
客户端文档入口
==============
SimCAE Hub 客户端文档入口
========================
你第一次打开 update-client/Docs 时，先看这一份。这里告诉你每份文档是干什么的，以及不同角色应该从哪里开始。
本目录记录 SimCAE Hub 的 Qt/C++ 客户端更新链路。当前方向是保留 Launcher / Updater / Bootstrap 的桌面客户端机制，适配 SimCAE Hub 当前 Go API，不用 Go 或 Web 技术重写客户端。
文档阅读顺序
============
建议先按这个顺序阅读：
1. 01-客户端接入打包部署指南.md
适合 SDK 接入方、测试人员和交付人员。按“生成 SDK -> 放进业务软件 -> 生成配置 -> 联调 -> 打最终包”的顺序写。
说明客户端运行链路、配置字段、打包方式和人工验证方法。
2. 02-编译环境和第三方依赖说明.md
适合需要编译 Launcher、Updater、Bootstrap 的人。说明 Windows/Linux 下 Qt、OpenSSL、thirdparty/ 和 CMake 怎么准备。
说明 Windows 和 Linux 下编译 Qt/C++ 客户端需要的工具、Qt、OpenSSL 和 CMake 命令。
3. ../i18n/ReadMe.txt
适合维护界面文案的人。说明新增 tr() 后怎么更新 .ts、生成 .qm，并把翻译文件打进 qrc。
3. ../config/server_config.json
编译进客户端资源的服务端地址配置，当前测试服务器是 http://192.168.1.158:18000。
常用任务入口
============
4. ../scripts/ReadMe.txt
SDK 打包脚本和客户安装包打包脚本的简短说明。
如果你只是拿到 SDK 接入业务软件：
```text
读 01-客户端接入打包部署指南.md 的“三、你：把 SDK 放进业务软件目录”和“四、你：生成并填写 app_config.json”。
```
如果你要重新打 Windows SDK 包：
```powershell
cd update-client
.\scripts\package-sdk.ps1 -SourceDir .\out\bin\Release -OutputDir .\dist\UpdateClientSDK -ZipFile .\dist\UpdateClientSDK.zip -SdkVersion 0.1.0
```
如果你要重新打 Linux SDK 包：
```bash
cd update-client
cmake --preset linux-x64-release
cmake --build --preset linux-x64-release
bash ./scripts/package-sdk.sh --source-dir ./out/linux/bin --output-dir ./dist/UpdateClientSDK-linux --archive ./dist/UpdateClientSDK-linux.tar.gz --sdk-version 0.1.0
```
客户端配置速记
==============
config/app_config.json 是部署配置源文件。Launcher / Updater / MainApp 启动时会把它同步到当前用户的 QSettings 配置区；Windows 下对应注册表，Linux 下对应用户配置文件。后续运行配置优先从 QSettings 读取。
config/server_config.json 是编译期服务端地址配置源文件。它通过 config/server_config.qrc 编进 Launcher / Updater / MainApp，不写入 app_config.json，也不写入注册表。修改 api_base_url 后必须重新编译客户端程序才会生效。
如果 config/app_config.json 内容被修改，下一次启动时会按解析后的 JSON 内容 SHA256 判断变化并重新导入注册表。
非空 app_config.json 成功导入注册表后会自动清空为 {}，文件保留不删除，方便下次直接粘贴管理后台生成的新配置。
Windows 注册表位置：HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config。
Linux 配置位置由 Qt QSettings 决定，通常在当前用户 home 目录的 .config/Marsco/UpdateClientSDK.conf 一类路径下。
Windows 运行态数据目录类似：%LOCALAPPDATA%\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\。
如果检测到 app_config.json 发生变化，SDK 会删除当前用户数据目录里的 client_identity.dat、version_policy.dat 和 local_state.json，避免继续使用旧授权身份、旧策略或旧防回滚状态；这些运行态文件不再默认写入安装目录。
正常启动成功后不要删除这些状态文件，它们用于本地身份、离线策略和安全状态。
首次运行时如果该文件不存在且发现旧 client.ini，会自动迁移。
接入新软件时通常需要修改：
1. app_id、app_name、channel、current_version。
2. client_token、license_key、launch_token。
3. config/server_config.json 里的 api_base_url。
4. main_executable：团队业务主程序文件名。
5. launcher_executable、updater_executable、bootstrap_executable。
6. health_check_timeout_ms：升级后等待业务程序健康确认的毫秒数，最小 1000。
Windows 完整格式参考 update-client/config/app_config.example.json；Linux 完整格式参考 update-client/config/app_config.linux.example.json。
运行时生成的 client_identity.dat、local_state.json 等文件不得打入通用 SDK 模板。app_config.json 可以作为部署模板，但不要把某台机器运行后产生的临时状态混进去。
Windows 发布打包：
1. 使用 Release 配置编译全部客户端程序。
2. 先完成当前版本在线校验。签名 Manifest 缓存现在默认保存在当前用户数据目录：
Windows：%LOCALAPPDATA%\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\update\manifest_cache
Linux：$XDG_DATA_HOME/Marsco/UpdateClientSDK/installations/<安装目录SHA256>/update/manifest_cache，未设置 XDG_DATA_HOME 时通常是 ~/.local/share。
打包脚本会优先从用户数据目录读取，也兼容旧版 Release 目录里的 update/manifest_cache。
3. 准备一份实际 app_config.json，确认其中包含正确的 License Key、当前版本和业务程序名；确认客户端程序已用正确的 config/server_config.json 编译。
4. 在 PowerShell 执行：
powershell -ExecutionPolicy Bypass -File .\scripts\package-client.ps1 -ConfigFile .\config\app_config.json
5. 输出位于 dist/UpdateClient 和 dist/UpdateClient.zip。
脚本会拒绝 Debug DLL、PDB、嵌套重复主程序和缺少签名 Manifest 的发布源目录。
客户端能力、接口链路、配置字段和接入限制统一看 01 文档。当前不包含邮箱、支付、告警、灰度发布等页面上没有的业务模块；崩溃报告作为旧系统兼容后端接口保留，具体看项目根目录的 使用教学.md。
Docs/01-客户端接入打包部署指南.md
+199 -357
View File
@@ -1,432 +1,274 @@
# UpdateClientSDK 客户端接入、打包和部署指南
# SimCAE Hub 客户端接入、打包和部署指南
本文按“维护者打包 SDK -> 你接入业务软件 -> 联调测试 -> 生成最终客户端包”的顺序说明。你拿到这份文档后，按章节一步一步做即可。
本文说明 `update-client` 的当前实现。它保留 Launcher / Updater / Bootstrap 的桌面客户端机制，服务端协议使用 SimCAE Hub 当前 Go API。
## 先看这里：你要做哪件事
## 1. 适用范围
| 你的目标 | 直接看哪一节 |
当前客户端只覆盖项目已有页面和接口对应的能力：
1. 产品版本、软件发布、发布包和 Manifest。
2. 客户授权、在线命名用户席位和门户受控下载。
3. 在线检查更新、Manifest 拉取、受控下载、SHA-256 校验。
4. Manifest 签名验签、临时文件、断点重试、安装前后完整性校验。
邮箱、支付、灰度、告警等页面上没有的能力不属于当前范围。崩溃报告是 SimCAE Hub 保留的旧系统兼容后端接口，不属于 Launcher / Updater / Bootstrap 的更新链路；接入方需要崩溃上报时，按 `使用教学.md` 里的崩溃报告接口说明调用。
## 2. 客户端程序组成
| 程序 | 作用 |
| --- | --- |
| 重新生成给别人用的 SDK 包 | 二、维护者：生成 SDK 包 |
| 把 SDK 放到 SimCAE 或其他业务软件目录 | 三、你：把 SDK 放进业务软件目录 |
| 从后台生成 `app_config.json` 和 qrc 服务端配置 | 四、你：生成并填写客户端配置 |
| 给业务主程序接入启动保护代码 | 五、你：业务主程序接入要求 |
| 验证升级、回滚、健康检查 | 六、你：联调测试 |
| 生成最终交付给用户的客户端包 | 七、维护者：生成最终客户端包 |
| `Launcher` | 客户日常启动入口，负责导入配置、使用 `client_token` 检查更新、启动 Updater 或主程序 |
| `Updater` | 负责拉取 Manifest、下载发布包、校验文件、准备安装事务 |
| `Bootstrap` | 负责在需要替换运行中文件时接管安装，并把结果交回 Updater |
| `MainApp` | 示例主程序，用来验证 launch ticket 和安装后完整性校验 |
| `Common` | 配置、HTTP、票据、完整性校验等公共代码 |
## 一、这个 SDK 是什么
## 3. 当前在线更新链路
UpdateClientSDK 是“独立更新器 SDK / 升级运行时 SDK”。它不是传统的 `include + lib` 形态，而是把自动升级能力做成一组独立程序，让业务软件通过这些程序完成检查更新、下载、安装、回滚和启动保护。
1. `Launcher` 启动后读取服务端生成的 `config/app_config.json`，并把静态配置导入当前用户的运行配置。
2. 如果配置里没有 `api_base_url`，客户端会回退到编译进 EXE 资源中的 `server_config.json`。
3. `Launcher` 确保存在 `device_id`，并检查 `client_token` 是否存在。
4. `Launcher` 调用 `GET /api/v1/client/update/authorized-check`，请求头带 `X-Client-Token`。
5. 如果服务端返回可用发布，`Launcher` 启动 `Updater`，并传入产品编码、渠道、目标版本和发布 ID。
6. `Updater` 调用 `GET /api/v1/client/update/manifest`，请求头继续带 `X-Client-Token`。
7. `Updater` 先校验服务端返回的 `manifestSha256`，再按配置决定是否强制要求 RSA-SHA256 签名。
8. `Updater` 从 Manifest 中读取每个文件的 `downloadUrl`、`sizeBytes` 和 `sha256`。
9. 下载请求统一带 `X-Client-Token`。
10. 下载使用 `.part` 临时文件保存进度，请求失败后按网络重试策略处理。
11. 文件下载完成后，客户端按 Manifest 校验文件大小和 SHA-256。
12. 安装前校验 staging 目录，安装完成后保存 Manifest 缓存，并可在主程序启动时再次校验已安装文件。
SDK 核心程序：
## 4. 关键配置字段
- `Launcher.exe` / `Launcher`：用户入口。检查版本、验证授权和策略，决定直接启动业务主程序或进入升级流程。
- `Updater.exe` / `Updater`：下载、校验、备份、安装、健康确认、提交或回滚。
- `Bootstrap.exe` / `Bootstrap`：处理运行中可能被占用的 EXE/DLL 或 Linux 可执行文件替换。
- `config/app_config.json`：部署配置源文件。启动时会同步到当前用户的 QSettings 配置区；Windows 下对应注册表，Linux 下对应用户配置文件。
- `config/server_config.json`：编译期服务端地址配置源文件，通过 `config/server_config.qrc` 编进 Launcher / Updater / MainApp，不写入 `app_config.json` 或注册表。
- `config/manifest_public_key.pem`：Manifest 签名公钥，用来验证服务端发布包没有被篡改。
正式客户安装包里的 `config/app_config.json` 由服务端在上传发布包 ZIP 时自动生成。常用字段如下：
## 二、维护者：生成 SDK 包
| 字段 | 说明 |
| --- | --- |
| `product_code` | SimCAE Hub 后台产品目录中的产品编码，例如 `stage2-dap` |
| `app_id` | 本地应用标识，默认和产品编码一致 |
| `channel` | 发布渠道，例如 `stable` |
| `current_version` | 当前本地安装版本，例如 `1.0.0` |
| `api_base_url` | 后端 API 地址，例如 `http://192.168.1.158:18000` |
| `client_token` | Launcher/Updater 调更新接口使用的部署级令牌，不绑定某一个客户 |
| `install_root` | 相对 Launcher/Updater 所在运行目录解析的更新根目录，决定 Updater、Bootstrap 和启动校验作用在哪棵目录 |
| `main_executable` | 相对运行目录解析的业务入口程序，通常是 `MainApp.exe` 或真实软件入口 |
| `launcher_executable` | 相对运行目录解析的 Launcher 文件名，主要用于提示和保持启动链路配置一致 |
| `updater_executable` | 相对运行目录解析的 Updater 文件名，Launcher 检查到更新后会启动它 |
| `bootstrap_executable` | 相对运行目录解析的 Bootstrap 文件名，Updater 需要替换文件时会启动它 |
| `platform` | 操作系统，例如 `windows` 或 `linux` |
| `arch` | 架构，例如 `x86_64` |
| `abi` | ABI，例如 `msvc`；没有时可留空 |
| `launch_token` | Launcher 和 MainApp 之间生成一次性启动票据的本地密钥 |
| `require_manifest_signature` | 是否强制要求 Manifest 必须带签名 |
| `verify_installed_on_start` | 主程序启动时是否按 Manifest 缓存校验已安装文件 |
这一节是 SDK 维护者操作。接入方通常只需要拿到 `UpdateClientSDK.zip`。
`config/server_config.json` 会编译进客户端资源，作为 `api_base_url` 缺失时的兜底地址，当前测试服务器地址为：
打包前确认：
`http://192.168.1.158:18000`
1. 已在 Windows 上用 Release 配置编译完成，输出目录里有 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe`。
2. `config/manifest_public_key.pem` 和服务端使用的私钥是一对。
3. `update-client/Docs` 里的 Markdown 文档会随 SDK 一起打包，是默认接入说明来源。
4. Word 接入说明是可选增强。如果本地有文件名包含 `SDK` 的 `.docx`，打包脚本会额外复制到 SDK 根目录；如果没有，也不会影响 SDK 打包。
5. 如果业务软件本身已经带 Qt DLL，通常不要把 SDK 的 Qt 运行库打进去，避免 Qt 版本混用。
如果换服务器，可以改完该文件后重新编译客户端；正式客户包通常由服务端写入 `api_base_url`，不需要把 `server_config.json` 暴露给客户。
在 Windows PowerShell 中执行：
## 5. 编译
Windows Release 编译：
```powershell
cd C:\Users\admin\Desktop\update-client
cd update-client
cmake --preset x64-release
cmake --build --preset x64-release
```
Linux Release 编译：
```bash
cd update-client
cmake --preset linux-x64-release
cmake --build --preset linux-x64-release
```
## 6. 打包 SDK
Windows 示例：
```powershell
cd update-client
.\scripts\package-sdk.ps1 `
-SourceDir .\out\bin\Release `
-OutputDir .\dist\UpdateClientSDK `
-ZipFile .\dist\UpdateClientSDK.zip `
-OutputDir .\dist\SimCAEHubUpdateClientSDK `
-ZipFile .\dist\SimCAEHubUpdateClientSDK.zip `
-SdkVersion 0.1.0
```
生成结果：
执行成功后会生成：
```text
dist/
UpdateClientSDK/
sdk_manifest.json
Docs/
00-先读我-客户端文档入口.txt
01-客户端接入打包部署指南.md
02-编译环境和第三方依赖说明.md
bin/
Launcher.exe
Updater.exe
Bootstrap.exe
...
config/
app_config.json
manifest_public_key.pem
scripts/
install-sdk.ps1
package-client.ps1
package-sdk.ps1
SimCAE自动升级SDK接入说明_v0.1.docx # 可选：只有本地存在 Word 说明时才会出现
UpdateClientSDK.zip
1. 展开目录：`update-client\dist\SimCAEHubUpdateClientSDK`
2. 对外提供的 SDK 压缩包：`update-client\dist\SimCAEHubUpdateClientSDK.zip`
默认不会打包 Qt DLL 和 Qt 插件目录，适合接入方已经有 Qt 运行环境，或者希望自己控制依赖部署的情况。
如果希望 SDK 包里带上 Qt runtime：
```powershell
cd update-client
.\scripts\package-sdk.ps1 `
-SourceDir .\out\bin\Release `
-OutputDir .\dist\SimCAEHubUpdateClientSDK-with-qt `
-ZipFile .\dist\SimCAEHubUpdateClientSDK-with-qt.zip `
-SdkVersion 0.1.0 `
-IncludeQtRuntime
```
把 `dist/UpdateClientSDK.zip` 发给接入方即可。
执行成功后会生成：
可选参数：
1. 展开目录：`update-client\dist\SimCAEHubUpdateClientSDK-with-qt`
2. 对外提供的 SDK 压缩包：`update-client\dist\SimCAEHubUpdateClientSDK-with-qt.zip`
- `-IncludeDemoMainApp`：把仓库里的 Demo 主程序 `MainApp.exe` 也打进 SDK，方便演示。
- `-IncludeQtRuntime`：把 Qt 运行库也打进 SDK。只有业务软件本身不带 Qt 时才建议使用。
其中 `-OutputDir` 是脚本整理 SDK 的展开目录，`-ZipFile` 是最终要交给接入方的 SDK 压缩包。接入方没有单独准备 Qt 运行库时，优先使用带 Qt runtime 的压缩包。
Linux SDK 打包方式：
Linux 示例：
```bash
cd /home/laluo/project/update-client
cmake --preset linux-x64-release
cmake --build --preset linux-x64-release
bash ./scripts/package-sdk.sh \
cd update-client
./scripts/package-sdk.sh \
--source-dir ./out/linux/bin \
--output-dir ./dist/UpdateClientSDK-linux \
--archive ./dist/UpdateClientSDK-linux.tar.gz \
--output-dir ./dist/SimCAEHubUpdateClientSDK-linux \
--archive ./dist/SimCAEHubUpdateClientSDK-linux.tar.gz \
--sdk-version 0.1.0
```
Linux SDK 包里核心程序名不带 `.exe`：
Linux 如需带上 Qt runtime，追加 `--include-qt-runtime`。
SDK 包不会包含最终 `app_config.json`、`server_config.json`、`server_config.qrc` 或 `manifest_public_key.pem`。这些最终配置在完整客户软件包上传到 SimCAE Hub 后由服务端生成。
## 7. 客户安装包配置
接入方应把以下文件放到客户软件目录的根目录或 `bin/` 目录：
1. `Launcher`
2. `Updater`
3. `Bootstrap`
4. `MainApp` 或真实业务主程序
5. `config/` 目录，可以先为空
### 7.1 标准目录结构和路径口径
更新系统不要求必须放在客户软件根目录。它可以放在 `SimCAE/` 根目录，也可以放在 `SimCAE/bin/` 目录。关键是让客户端配置里的 `install_root` 和服务端 Manifest 文件路径使用同一套口径。
先区分三个目录概念：
| 概念 | 说明 |
| --- | --- |
| 运行目录 | Launcher、Updater、Bootstrap 所在目录，由客户端自动识别 |
| `install_root` | 相对运行目录解析的更新根目录，Updater 下载、校验、备份、回滚和 Bootstrap 替换文件都以它为范围 |
| Manifest `files[].path` | 服务端生成的安装相对路径，客户端会把它拼到 `install_root` 下面 |
目录结构一：更新系统放在软件根目录。
```text
dist/
UpdateClientSDK-linux/
sdk_manifest.json
Docs/
00-先读我-客户端文档入口.txt
01-客户端接入打包部署指南.md
02-编译环境和第三方依赖说明.md
bin/
Launcher
Updater
Bootstrap
Common/
ConfigHelper.h
ConfigHelper.cpp
TicketHelper.h
TicketHelper.cpp
config/
app_config.json
manifest_public_key.pem
scripts/
package-sdk.sh
package-client.sh
SimCAE自动升级SDK接入说明_v0.1.docx # 可选：只有本地存在 Word 说明时才会出现
UpdateClientSDK-linux.tar.gz
```
## 三、你：把 SDK 放进业务软件目录
假设业务软件目录是：
```text
D:\SimCAE\
bin\
SimCAE.exe
Qt5Core.dll
SimCAE/
Launcher.exe
Updater.exe
Bootstrap.exe
MainApp.exe
config/
app_config.json
App/
...
Licenses\
installerResources\
```
推荐把 SDK 放到 `bin` 目录，和 `SimCAE.exe` 同级；后台发布新版本时仍选择整个 `D:\SimCAE\` 作为发布根目录。
对应配置：
先解压 SDK：
```powershell
Expand-Archive D:\交付\UpdateClientSDK.zip -DestinationPath D:\SimCAE_SDK -Force
```json
{
"install_root": ".",
"main_executable": "MainApp.exe",
"launcher_executable": "Launcher.exe",
"updater_executable": "Updater.exe",
"bootstrap_executable": "Bootstrap.exe"
}
```
再安装到业务软件的 `bin` 目录：
```powershell
cd D:\SimCAE\bin
D:\SimCAE_SDK\scripts\install-sdk.ps1 `
-SdkRoot D:\SimCAE_SDK `
-ReleaseDir .
```
安装后目录应类似：
目录结构二：更新系统和启动入口放在 `bin/`。
```text
D:\SimCAE\
bin\
SimCAE/
bin/
Launcher.exe
Updater.exe
Bootstrap.exe
SimCAE.exe
config\
MainApp.exe
config/
app_config.json
manifest_public_key.pem
Qt5Core.dll
App/
...
Licenses\
installerResources\
```
如果你需要重新覆盖 `config/app_config.json`，执行安装脚本时加 `-OverwriteConfig`：
```powershell
D:\SimCAE_SDK\scripts\install-sdk.ps1 `
-SdkRoot D:\SimCAE_SDK `
-ReleaseDir D:\SimCAE\bin `
-OverwriteConfig
```
注意：SimCAE 自己已经带有 Qt 运行库。SDK 的 Launcher/Updater 应复用 SimCAE 的 `Qt5*.dll`、`platforms/`、`imageformats/` 等目录。不要把另一套 Qt DLL 覆盖到 `SimCAE\bin`，否则可能出现“无法定位程序输入点”一类错误。
## 四、你：生成并填写客户端配置
最推荐的方式是在服务端管理后台生成客户端配置：
1. 浏览器打开服务端管理后台，例如 `http://服务器IP:8000/`。
2. 登录后台。
3. 创建或选择应用，例如 `app_id=simcae`。
4. 创建 License。
5. 在“客户端配置生成”区域选择应用、渠道、License 和主程序名。
6. 点击生成配置。
7. 复制“客户端 app_config.json”，覆盖 `D:\SimCAE\bin\config\app_config.json`。
8. 复制“qrc 服务端配置 server_config.json”，覆盖 `update-client\config\server_config.json`，然后重新编译 Launcher / Updater / Bootstrap。这个文件会被 `config/server_config.qrc` 编进程序，不会放进用户机器的 `app_config.json` 或注册表。
配置同步规则：
- `app_config.json` 是部署配置源文件，适合交付、复制、人工修改。
- `api_base_url` 不再属于 `app_config.json` 字段。它只存在于 `config/server_config.json`，并通过 qrc 编进程序。
- 交付给你的 SDK 运行包不会包含 `server_config.json` 和 `server_config.qrc`。它们是编译材料，不是运行配置；修改 SDK 包里的文件不会改变已经编译好的 `Launcher.exe`。
- Launcher / Updater / MainApp 启动时会计算 `app_config.json` 解析后的 JSON 内容 SHA256；如果 JSON 内容和上次导入时不同，就把文件里的配置重新写入当前 Windows 用户的注册表。
- 后续运行时优先从注册表读取配置，不再每次直接读 JSON。
- 运行过程中产生的动态值，例如首次输入的 `license_key`、服务端返回的 `device_id`、升级后的 `current_version`，会写入注册表。
- 为减少明文暴露，SDK 成功把非空 `app_config.json` 导入注册表后，会把 `app_config.json` 内容自动清空为 `{}`，但不会删除这个文件。以后你从管理后台复制新的客户端配置时，直接覆盖这个文件即可。
- SDK 会同步更新注册表里的 `source_sha256`，所以 `{}` 不会在下一次启动时反向覆盖注册表配置。
- 如果你手动修改了 `app_config.json`，下一次启动会重新导入并覆盖注册表里的同名字段。
- 如果检测到 `app_config.json` 确实发生变化，SDK 会同时删除当前用户数据目录里的 `client_identity.dat`、`version_policy.dat` 和 `local_state.json`，避免继续使用旧 License、旧设备身份、旧版本策略或旧防回滚状态；这些运行态文件不再默认写入安装目录。
- 正常启动成功后，不要删除 `client_identity.dat`、`version_policy.dat`、`local_state.json`。它们分别用于本地设备身份、离线策略和防回滚/防时间倒退，删除后会影响离线启动或导致重新授权。
- 注册表按安装目录隔离；同一台电脑上多个安装目录不会互相覆盖配置。
- 注册表位置为 `HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config`。
关键字段说明：
- `app_id`：服务端应用 ID，要和管理后台里的应用一致。
- `app_name`：应用显示名称。
- `channel`：发布渠道，例如 `stable`、`beta`、`dev`。
- `current_version`：客户端当前初始版本，必须和后台已发布的版本一致。
- `client_protocol`：客户端协议号，当前建议为 `3`。
- `launch_token`：本机启动票据 HMAC 密钥。服务端生成配置时会填默认值；正式部署建议按项目统一修改。
- `license_key`：管理后台创建 License 后生成的授权码。为空时首次启动 `Launcher.exe` 会弹窗让用户输入并保存到注册表；如果授权错误或过期，也会提示重新输入。
- `client_token`：服务端 `.env` 中的 `CLIENT_API_TOKEN`，必须和服务端一致。
- `device_id`：设备 ID。一般可以留空，首次启动时 SDK 会向服务端登记并写入注册表。
- `install_root`：被更新的安装根目录相对 `Launcher.exe` 所在目录的位置。SDK 放在 `bin` 时填 `..`。
- `main_executable`：业务主程序相对 `Launcher.exe` 所在目录的路径。SDK 放在 `bin` 且主程序也在 `bin` 时填 `SimCAE.exe`。
- `launcher_executable`、`updater_executable`、`bootstrap_executable`：通常不用改。
- `platform`、`arch`：当前为 `windows`、`x64`。
典型配置：
如果希望整个 `SimCAE/` 都属于更新范围，对应配置：
```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": "MARSCO-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"client_token": "SimCAEClientToken2026",
"request_timeout_ms": "5000",
"temp_folder": "update_temp",
"device_id": "",
"install_root": "..",
"main_executable": "SimCAE.exe",
"main_executable": "MainApp.exe",
"launcher_executable": "Launcher.exe",
"updater_executable": "Updater.exe",
"bootstrap_executable": "Bootstrap.exe",
"health_check_timeout_ms": "15000",
"platform": "windows",
"arch": "x64"
"bootstrap_executable": "Bootstrap.exe"
}
```
对应的 `config/server_config.json` 示例：
这表示 Launcher 从 `bin/` 启动 `MainApp.exe`，Updater 和 Bootstrap 更新的是 `bin/` 的上一级，也就是整个 `SimCAE/`。
服务端发布包路径要和客户端 `install_root` 对应：
| 客户端配置 | 服务端 Manifest 路径口径 |
| --- | --- |
| 更新系统在根目录，`install_root` 是 `.` | `MainApp.exe`、`App/xxx.dll` 相对 `SimCAE/` |
| 更新系统在 `bin/`，`install_root` 是 `..` | `bin/MainApp.exe`、`App/xxx.dll` 相对 `SimCAE/` |
当前管理后台“发布包”上传接口会使用上传文件名作为 `artifactName`，后端按安全文件名校验。当前稳定支持的是发布一个完整安装包或压缩包文件，或者把文件放在 `install_root` 根层级；还不是“自动解析压缩包并生成 App/bin 多文件 Manifest”的完整安装器。后续如果要让在线 Updater 直接把多个文件铺到 `App/`、`bin/` 等子目录，需要在现有发布包页面和 Go 后端上继续增强安全相对路径或 Manifest 文件清单生成能力。
如果后续要支持“更新系统在 `bin/`，但只校验和更新 `App/`”这类更窄的安装根目录，需要在管理后台和 Go 后端增加对应配置项，让服务端生成 `../App` 这类定制 `install_root`。当前服务端自动生成配置时只使用标准的 `.` 或 `..`。
如果开启 `verify_installed_on_start`，客户端会扫描 `install_root` 下的 EXE 和 DLL。整包 Manifest 中 `required=true` 的核心文件必须存在且 SHA-256 匹配；`required=false` 的可选组件文件可以由 MaintenanceTool 管理，缺失时不会阻止启动。可选组件建议放在独立目录中，例如 `plugins/dap/`，不要和核心程序 DLL 混放。
上传完整客户软件 ZIP 时，服务端会根据发布包记录自动写入这些关键值：
```json
{
"api_base_url": "http://192.168.229.128:8000"
"product_code": "stage2-dap",
"channel": "stable",
"current_version": "1.1.0",
"api_base_url": "http://192.168.1.158:18000",
"client_token": "<由服务器 .env 配置>",
"install_root": ". 或 ..",
"platform": "windows",
"arch": "x86_64",
"abi": "msvc"
}
```
## 五、你：业务主程序需要配合什么
`install_root` 由服务端根据 Launcher 所在位置自动判断：更新系统在软件根目录时写 `.`，在 `bin/` 目录时写 `..`。
当前安全模式下，业务主程序需要配合两件事：
## 8. 运行数据位置
1. 接收 `--ticket-file=<path>` 参数，验证并消费一次性启动票据。
2. 如果收到 `--health-file=<path>` 参数，启动成功后向该路径写入 `ok\n`，让 Updater 确认新版本可用。
Windows 运行数据目录：
接入位置：
`%LOCALAPPDATA%\SimCAE\HubUpdateClient\installations\<安装目录SHA256>\`
```text
main / WinMain 开头，创建主窗口之前
```
Linux 运行数据目录：
当前仓库里的 `update-client/MainApp/main.cpp` 是接入示例，已经实现：
`$XDG_DATA_HOME/SimCAE/HubUpdateClient/installations/<安装目录SHA256>/`
- 启动票据校验。
- 本地 License/设备身份校验。
- 本地策略校验。
- Manifest 完整性校验。
- 健康标记写入。
未设置 `XDG_DATA_HOME` 时通常是：
真正接入业务软件时，把这些启动检查逻辑移植到业务主程序。用户入口应改成 `Launcher.exe`，不要让用户直接双击 `SimCAE.exe`。
`~/.local/share/SimCAE/HubUpdateClient/installations/<安装目录SHA256>/`
重要：业务主程序校验 ticket 时，必须使用 SDK 当前运行配置里的动态值，不要直接从 `app_config.json` 读取 `device_id`。
Manifest 缓存保存在运行数据目录下的 `update/manifest_cache`。
原因是 `app_config.json` 是部署源文件，网页生成时 `device_id` 通常为空；真正的设备 ID 是 `Launcher.exe` 首次向服务端登记后写入当前用户注册表的。`Launcher.exe` 生成 ticket 时使用的是注册表里的真实 `device_id`。如果业务主程序从 `app_config.json` 读取空的 `device_id` 来校验，就会出现：
## 9. 常见问题
```text
ticket signature, identity, time or nonce invalid
```
或者细化后的：
```text
ticket device_id mismatch
```
业务主程序应像 `MainApp/main.cpp` 示例一样使用：
```cpp
ConfigHelper& config = ConfigHelper::instance();
TicketHelper::consumeAndVerify(
ticketFilePath,
config.getValue("App", "app_id"),
config.getValue("Update", "device_id"),
config.getValue("App", "current_version"),
config.getValue("App", "launch_token"),
&ticketError);
```
也就是说，接入业务主程序时不能只复制一小段 ticket 代码后自己解析 JSON；要么复用 SDK 的 `ConfigHelper` / `TicketHelper`，要么保证业务主程序读取到的 `app_id`、`device_id`、`current_version`、`launch_token` 和 `Launcher.exe` 完全来自同一套运行配置。
## 六、你：准备服务端数据
首次联调前，服务端至少要准备这些内容：
1. 创建应用，例如 `simcae`。
2. 创建渠道，例如 `stable`。
3. 创建 License。
4. 发布一个初始版本，例如 `1.0.0`。
5. 生成客户端配置，并写入 `bin\config\app_config.json`。客户端下次启动时会自动同步到注册表。
6. 生成 qrc 服务端配置，并写入源码目录 `config\server_config.json` 后重新编译 SDK 程序。
为什么必须先发布初始版本：Launcher 启动业务主程序前会做 Manifest 完整性校验。这个 Manifest 是服务端发布版本时生成并签名的清单，用来证明当前本地文件属于一个可信版本。如果没有发布过 `current_version` 对应版本，客户端会提示签名 Manifest 缓存缺失。
后台发布版本时，选择整个安装根目录，例如 `D:\SimCAE\`，不要只选择 `D:\SimCAE\bin`。这样服务端会把 `bin/SimCAE.exe`、`Licenses/`、`installerResources/` 等完整结构写进 Manifest。
## 七、你：运行和联调
基础联调步骤：
1. 确认服务端正在运行。
2. 确认 `bin\config\app_config.json` 中 `client_token`、`license_key`、`current_version` 正确，并确认 `Launcher.exe` 已用正确的 `config/server_config.json` 重新编译。
3. 双击 `bin\Launcher.exe`。
4. 首次启动时如果 `license_key` 为空，按弹窗输入后台创建的 License；SDK 会把它保存到注册表。
5. 成功进入业务主程序后，回到后台查看设备、升级日志、下载日志。
6. 在后台发布更高版本，例如从 `1.0.0` 发布到 `1.0.1`。
7. 再次启动 `Launcher.exe`，验证升级、健康确认和回滚逻辑。
联调目录建议：
```text
D:\SimCAE_Release\
C:\Users\<你的用户名>\Desktop\SimCAE_Release\
```
如果安装在 `C:\Program Files\...`、`D:\...` 或其他普通用户不一定可写的目录，SDK 的普通配置值会写入当前用户注册表，不需要修改 `app_config.json`。`client_identity.dat`、`local_state.json`、`version_policy.dat`、更新缓存和 Manifest 缓存也会写入当前用户数据目录，不再默认写到安装目录。
Windows 用户数据目录类似：`%LOCALAPPDATA%\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\`。因此日常启动、首次授权、保存设备身份、保存策略、防回滚状态和下载缓存不应再触发管理员权限确认框。只有真正要替换安装目录里的 EXE/DLL 等程序文件时，才需要保证安装目录可写，或让安装器/Updater 具备相应权限。
## 八、维护者：生成某个产品的最终客户端包
SDK 是给接入方开发使用的。最终给用户安装或分发时，可以从已经联调过的 Release 目录生成最终客户端包。
在 Windows PowerShell 中执行：
```powershell
cd C:\Users\admin\Desktop\update-client
.\scripts\package-client.ps1 `
-SourceDir .\out\bin\Release `
-ConfigFile .\config\app_config.json `
-OutputDir .\dist\UpdateClient `
-ZipFile .\dist\UpdateClient.zip
```
`package-client.ps1` 会检查：
- 配置文件必填字段是否完整。
- 主程序、Launcher、Updater、Bootstrap 是否存在。
- 是否混入 Debug DLL、PDB、ILK。
- 当前版本是否已有签名 Manifest 缓存。脚本会优先从当前用户数据目录读取：
`%LOCALAPPDATA%\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\update\manifest_cache`。
同时兼容旧版 Release 目录里的 `update\manifest_cache`。
- 是否存在重复主程序。
生成结果：
```text
dist/
UpdateClient/
UpdateClient.zip
```
Linux 最终客户端包生成方式：
```bash
cd /home/laluo/project/update-client
bash ./scripts/package-client.sh \
--source-dir /path/to/SimCAE \
--config-file /path/to/SimCAE/bin/config/app_config.json \
--output-dir ./dist/UpdateClient-linux \
--archive ./dist/UpdateClient-linux.tar.gz
```
Linux 打包脚本会检查：
- `app_config.json` 必填字段是否完整。
- 主程序、Launcher、Updater、Bootstrap 是否存在。
- 是否混入 Debug 产物。
- 当前版本是否已有签名 Manifest 缓存。脚本会优先从当前用户数据目录读取：
`$XDG_DATA_HOME/Marsco/UpdateClientSDK/installations/<安装目录SHA256>/update/manifest_cache`，
未设置 `XDG_DATA_HOME` 时通常是 `~/.local/share/Marsco/UpdateClientSDK/installations/<安装目录SHA256>/update/manifest_cache`。
同时兼容旧版 Release 目录里的 `update/manifest_cache`。
- 是否存在重复主程序。
Linux 下如果程序安装在 `/opt`、`/usr/local` 等普通用户不可写目录，升级器无法像 Windows UAC 那样自动提权修改安装目录。正式部署前建议二选一：
1. 把软件安装到当前用户有写权限的目录，例如用户 home 下的应用目录。
2. 由安装器创建专用目录和权限，让运行用户对软件目录有写入权限。
## 九、常见错误
1. 直接启动业务主程序提示 ticket 错误：应从 `Launcher.exe` 启动。
2. 首次启动保存配置/状态文件失败：如果目录不可写，SDK 会弹出管理员权限确认框；用户取消或当前账号没有管理员权限时仍会失败。
3. 首次启动设备登记失败：检查编译进 qrc 的 `config/server_config.json`、`client_token`、`license_key`、服务端 License 状态。
4. 提示 License 错误或过期：在后台确认 License 是否存在、是否被禁用或删除、是否超过最大设备数。
5. 策略或 Manifest 验签失败：检查 `config/manifest_public_key.pem` 是否和服务端私钥匹配。
6. 提示 signed manifest cache missing：先在后台发布一次 `current_version` 对应版本，并让客户端拿到该版本 Manifest。
7. 升级后回滚：检查业务程序是否在 `health_check_timeout_ms` 内写入健康标记。
8. 发布失败提示主程序不在根目录：服务端 `.env` 中 `RELEASE_MAIN_EXECUTABLE` 要和平台匹配。Windows 通常是 `bin/SimCAE.exe`；Linux 通常是 `bin/SimCAE`。
9. 启动时提示 `无法定位程序输入点 ... Qt5*.dll`：通常是 Qt DLL 被不同版本覆盖或混用。恢复业务软件原始 Qt DLL，并重新打包 SDK；SimCAE 场景下不要使用 `-IncludeQtRuntime`。
1. 客户门户登录失败：检查客户门户账号是否已激活、客户是否生效、密码是否正确。
2. 检查更新没有结果：检查后台发布是否已发布、发布包是否可用、产品编码、渠道和平台参数是否一致。
3. 下载 401：检查发布包中的 `config/app_config.json` 是否由服务端生成，`client_token` 是否和服务器 `.env` 中的 `SIMCAE_CLIENT_TOKEN` 一致。
4. Manifest 校验失败：检查服务端 Manifest 是否被篡改、发布包 SHA-256 是否和实际文件一致。
5. 强制签名失败：确认 `manifest_public_key.pem` 与服务端私钥匹配；如果服务端暂未启用签名，测试环境可先把 `require_manifest_signature` 设为 `false`。
6. 启动主程序失败：检查 `main_executable` 和 `install_root` 是否指向真实文件。
Docs/02-编译环境和第三方依赖说明.md
+43 -145
View File
@@ -1,175 +1,73 @@
# 客户端编译环境和第三方依赖说明
# SimCAE Hub 客户端编译环境和第三方依赖说明
`thirdparty/` 是本机依赖目录，已经被 `.gitignore` 忽略，不会提交到 Git。
本文说明 `update-client` 的 Qt/C++ 客户端编译环境。客户端保留 Launcher / Updater / Bootstrap 机制，依赖 Qt、CMake 和 OpenSSL。
当前客户端构建依赖：
## 1. 通用要求
1. Qt 5.15.2 或兼容的 Qt 5 版本
2. OpenSSL
| 依赖 | 要求 |
| --- | --- |
| CMake | 建议 3.20 或更高版本 |
| C++ | C++17 |
| Qt | Qt 5，至少需要 Core、Network、Gui、Widgets |
| OpenSSL | 用于 Manifest RSA-SHA256 验签 |
| 编译器 | Windows 推荐 Visual Studio 2022 x64，Linux 推荐 gcc/g++ |
Windows 下推荐使用 Qt 5.15.2 msvc2019_64 和 OpenSSL-Win64；Linux 下使用系统安装的 Qt/OpenSSL 开发包。
项目已提供 CMake Preset：
先看结论：
| Preset | 平台 | 用途 |
| --- | --- | --- |
| `x64-debug` | Windows | Debug 编译 |
| `x64-release` | Windows | Release 编译 |
| `linux-x64-debug` | Linux | Debug 编译 |
| `linux-x64-release` | Linux | Release 编译 |
- Windows：配置 Qt 环境变量，把 OpenSSL 复制到 `thirdparty/OpenSSL-Win64`。
- Linux：用 apt 安装 Qt/OpenSSL 开发包。
- `thirdparty/` 只放本机依赖，不提交 Git。
## 2. Windows 环境
## 1. Qt 配置
建议安装：
### Windows
1. Visual Studio 2022，勾选 Desktop development with C++。
2. Qt 5 x64，版本可以与当前团队环境保持一致。
3. CMake。
4. OpenSSL x64。
Qt 路径由本机环境变量提供。你需要在 Windows 环境变量里配置 Qt 路径，让 CMake 的 `find_package(Qt5 ...)` 能找到 Qt。
推荐配置用户环境变量 `CMAKE_PREFIX_PATH`：
如果 Qt 没有加入环境变量，可以在编译前指定 `CMAKE_PREFIX_PATH` 或 `Qt5_DIR`。示例：
```powershell
[Environment]::SetEnvironmentVariable("CMAKE_PREFIX_PATH", "C:\Qt\5.15.2\msvc2019_64", "User")
$env:CMAKE_PREFIX_PATH = "C:\Qt\5.15.2\msvc2019_64"
```
设置完成后，重新打开 PowerShell 或 Visual Studio。
OpenSSL 可以放在 `update-client/thirdparty/OpenSSL-Win64`，也可以在配置时通过 `SIMCAE_OPENSSL_ROOT` 指向自定义目录。
如果只想对当前 PowerShell 窗口临时生效：
## 3. Linux 环境
```powershell
$env:CMAKE_PREFIX_PATH="C:\Qt\5.15.2\msvc2019_64"
```
也可以配置更精确的 `Qt5_DIR`：
```powershell
[Environment]::SetEnvironmentVariable("Qt5_DIR", "C:\Qt\5.15.2\msvc2019_64\lib\cmake\Qt5", "User")
```
`CMAKE_PREFIX_PATH` 和 `Qt5_DIR` 二选一即可，推荐使用 `CMAKE_PREFIX_PATH`。
一般不需要把 `C:\Qt\5.15.2\msvc2019_64\bin` 加入 `Path`。项目构建后会通过 `windeployqt` 复制运行所需的 Qt DLL。
### Linux
Linux 下需要安装 Qt5 开发包，让 CMake 能找到 `Qt5::Core`、`Qt5::Network`、`Qt5::Gui`、`Qt5::Widgets`。
Ubuntu/Debian 示例：
Ubuntu 示例：
```bash
sudo apt update
sudo apt install -y build-essential cmake qtbase5-dev qttools5-dev-tools libssl-dev
sudo apt install -y build-essential cmake qtbase5-dev qttools5-dev qttools5-dev-tools libssl-dev
```
如果 Qt 安装在自定义目录，可以临时设置：
Linux 下通常直接使用系统 OpenSSL；如需指定自定义 OpenSSL，可用 CMake 变量配置。
```bash
export CMAKE_PREFIX_PATH=/path/to/Qt/5.x/gcc_64
```
## 4. 编译输出
## 2. OpenSSL 配置
Windows Release 可执行文件输出目录：
### Windows
`update-client/out/bin/Release`
OpenSSL 默认放在：
Windows CMake 构建目录：
```text
thirdparty/OpenSSL-Win64
```
`update-client/out/build/x64-release`
推荐目录结构：
Linux Release 可执行文件输出目录以当前 CMake Preset 和构建脚本为准，SDK 打包时通过 `--source-dir` 指定。
```text
thirdparty/
OpenSSL-Win64/
include/
openssl/
lib/
VC/
x64/
MD/
MDd/
```
实际打包 SDK 前，应确认 Release 输出目录中至少包含：
复制命令示例：
1. `Launcher`
2. `Updater`
3. `Bootstrap`
4. 可选的示例 `MainApp`
```powershell
cd C:\Users\admin\Desktop\update-client
mkdir thirdparty
Copy-Item "C:\Program Files\OpenSSL-Win64" ".\thirdparty\OpenSSL-Win64" -Recurse
```
最终客户软件包里的 `config/app_config.json` 和 `config/manifest_public_key.pem` 由服务端在发布包上传时生成；`server_config.json` 会编译进 EXE 作为兜底地址，不需要进入 SDK 包。
如果 OpenSSL 不放在 `thirdparty/`，可以在配置 CMake 时手动指定：
```powershell
cmake -S . -B out\build\x64-Debug `
-G "Visual Studio 17 2022" `
-A x64 `
-DSIMCAE_OPENSSL_ROOT="C:\Program Files\OpenSSL-Win64"
```
### Linux
Linux 下 CMake 会通过 `find_package(OpenSSL REQUIRED)` 查找系统 OpenSSL。通常安装 `libssl-dev` 即可，不需要 `thirdparty/OpenSSL-Win64`。
## 3. Windows 重新配置和编译
如果之前配置过 CMake，建议先删除旧缓存：
```powershell
cd C:\Users\admin\Desktop\update-client
Remove-Item out\build -Recurse -Force
```
重新配置：
```powershell
cmake -S . -B out\build\x64-Debug `
-G "Visual Studio 17 2022" `
-A x64
```
编译：
```powershell
cmake --build out\build\x64-Debug --config Debug
```
## 4. Linux 重新配置和编译
如果之前配置过 CMake，建议先删除旧缓存：
```bash
cd ~/project/update-client
rm -rf out/build/linux-x64-debug out/build/linux-x64-release
```
Debug 构建：
```bash
cmake --preset linux-x64-debug
cmake --build --preset linux-x64-debug
```
Release 构建：
```bash
cmake --preset linux-x64-release
cmake --build --preset linux-x64-release
```
Linux 构建时会自动使用 `config/app_config.linux.example.json` 作为输出目录里的默认 `config/app_config.json`，可执行程序名不带 `.exe`。
## 5. 提交注意事项
不要提交下面这些内容：
```text
thirdparty/
.vs/
out/
build/
dist/
App/
*.exe
*.dll
*.lib
*.pdb
```
这些都属于本机依赖、构建产物或打包产物，不应该进 Git。
SDK 打包和客户端功能验证见 `01-客户端接入打包部署指南.md`。