feat: 支持 Linux 客户端打包与跨平台运行
This commit is contained in:
+99
-2
@@ -66,6 +66,46 @@ dist/
|
||||
- `-IncludeDemoMainApp`：把仓库里的 Demo 主程序 `MainApp.exe` 也打进 SDK，方便演示。
|
||||
- `-IncludeQtRuntime`：把 Qt 运行库也打进 SDK。只有业务软件本身不带 Qt 时才建议使用。
|
||||
|
||||
Linux SDK 打包方式：
|
||||
|
||||
```bash
|
||||
cd /home/laluo/project/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
|
||||
```
|
||||
|
||||
Linux SDK 包里核心程序名不带 `.exe`：
|
||||
|
||||
```text
|
||||
dist/
|
||||
UpdateClientSDK-linux/
|
||||
SimCAE自动升级SDK接入说明_v0.1.docx
|
||||
sdk_manifest.json
|
||||
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
|
||||
UpdateClientSDK-linux.tar.gz
|
||||
```
|
||||
|
||||
## 三、你：把 SDK 放进业务软件目录
|
||||
|
||||
假设业务软件目录是：
|
||||
@@ -145,8 +185,11 @@ D:\SimCAE_SDK\scripts\install-sdk.ps1 `
|
||||
- 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 会同时删除 `config/client_identity.dat` 和 `config/version_policy.dat`，避免继续使用旧 License、旧设备身份或旧版本策略；如果安装目录不可写，会弹出管理员权限确认框。
|
||||
- 如果检测到 `app_config.json` 确实发生变化，SDK 会同时删除 `config/client_identity.dat`、`config/version_policy.dat` 和 `config/local_state.json`，避免继续使用旧 License、旧设备身份、旧版本策略或旧防回滚状态；如果安装目录不可写，会弹出管理员权限确认框。
|
||||
- 正常启动成功后，不要删除 `client_identity.dat`、`version_policy.dat`、`local_state.json`。它们分别用于本地设备身份、离线策略和防回滚/防时间倒退，删除后会影响离线启动或导致重新授权。
|
||||
- 注册表按安装目录隔离；同一台电脑上多个安装目录不会互相覆盖配置。
|
||||
- 注册表位置为 `HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config`。
|
||||
|
||||
@@ -217,6 +260,35 @@ main / WinMain 开头，创建主窗口之前
|
||||
|
||||
真正接入业务软件时，把这些启动检查逻辑移植到业务主程序。用户入口应改成 `Launcher.exe`，不要让用户直接双击 `SimCAE.exe`。
|
||||
|
||||
重要：业务主程序校验 ticket 时，必须使用 SDK 当前运行配置里的动态值，不要直接从 `app_config.json` 读取 `device_id`。
|
||||
|
||||
原因是 `app_config.json` 是部署源文件，网页生成时 `device_id` 通常为空；真正的设备 ID 是 `Launcher.exe` 首次向服务端登记后写入当前用户注册表的。`Launcher.exe` 生成 ticket 时使用的是注册表里的真实 `device_id`。如果业务主程序从 `app_config.json` 读取空的 `device_id` 来校验，就会出现：
|
||||
|
||||
```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` 完全来自同一套运行配置。
|
||||
|
||||
## 六、你：准备服务端数据
|
||||
|
||||
首次联调前，服务端至少要准备这些内容：
|
||||
@@ -286,6 +358,31 @@ dist/
|
||||
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 缓存。
|
||||
- 是否存在重复主程序。
|
||||
|
||||
Linux 下如果程序安装在 `/opt`、`/usr/local` 等普通用户不可写目录，升级器无法像 Windows UAC 那样自动提权修改安装目录。正式部署前建议二选一：
|
||||
|
||||
1. 把软件安装到当前用户有写权限的目录，例如用户 home 下的应用目录。
|
||||
2. 由安装器创建专用目录和权限，让运行用户对软件目录有写入权限。
|
||||
|
||||
## 九、常见错误
|
||||
|
||||
1. 直接启动业务主程序提示 ticket 错误：应从 `Launcher.exe` 启动。
|
||||
@@ -295,5 +392,5 @@ dist/
|
||||
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` 默认是 `bin/SimCAE.exe`，发布目录要选择包含 `bin/SimCAE.exe` 的安装根目录。
|
||||
8. 发布失败提示主程序不在根目录：服务端 `.env` 中 `RELEASE_MAIN_EXECUTABLE` 要和平台匹配。Windows 通常是 `bin/SimCAE.exe`；Linux 通常是 `bin/SimCAE`。
|
||||
9. 启动时提示 `无法定位程序输入点 ... Qt5*.dll`：通常是 Qt DLL 被不同版本覆盖或混用。恢复业务软件原始 Qt DLL，并重新打包 SDK；SimCAE 场景下不要使用 `-IncludeQtRuntime`。
|
||||
|
||||
Reference in New Issue
Block a user