feat: 支持 Linux 客户端打包与跨平台运行

2026-07-14 08:39:41 +00:00
parent c960d3b04d
commit f703ab0302
27 changed files with 1249 additions and 417 deletions
@@ -9,7 +9,7 @@
   面向接入和部署，说明 SDK 是什么、怎么放到业务软件目录、app_config.json 怎么填、如何打包。

 2. 第三方依赖说明.md
-   面向编译环境，说明 Qt、OpenSSL、thirdparty/ 和 CMake 环境变量怎么配置。
+   面向编译环境，说明 Windows/Linux 下 Qt、OpenSSL、thirdparty/ 和 CMake 环境变量怎么配置。

 3. ../i18n/ReadMe.txt
   面向国际化维护，说明新增 tr() 文案后如何更新 .ts、生成 .qm，以及 .qrc 如何内嵌翻译资源。
@@ -21,10 +21,13 @@
 客户端配置说明
 ==============

-config/app_config.json 是部署配置源文件。Launcher / Updater / MainApp 启动时会把它同步到当前 Windows 用户的注册表，后续运行配置优先从注册表读取。
+config/app_config.json 是部署配置源文件。Launcher / Updater / MainApp 启动时会把它同步到当前用户的 QSettings 配置区；Windows 下对应注册表，Linux 下对应用户配置文件。后续运行配置优先从 QSettings 读取。
 如果 config/app_config.json 内容被修改，下一次启动时会按解析后的 JSON 内容 SHA256 判断变化并重新导入注册表。
-注册表位置：HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config。
-如果检测到 app_config.json 发生变化，SDK 会删除 config/client_identity.dat 和 config/version_policy.dat，避免继续使用旧授权身份或旧策略；目录不可写时会弹出管理员权限确认框。
+非空 app_config.json 成功导入注册表后会自动清空为 {}，文件保留不删除，方便下次直接粘贴管理后台生成的新配置。
+Windows 注册表位置：HKEY_CURRENT_USER\Software\Marsco\UpdateClientSDK\installations\<安装目录SHA256>\config。
+Linux 配置位置由 Qt QSettings 决定，通常在当前用户 home 目录的 .config/Marsco/UpdateClientSDK.conf 一类路径下。
+如果检测到 app_config.json 发生变化，SDK 会删除 config/client_identity.dat、config/version_policy.dat 和 config/local_state.json，避免继续使用旧授权身份、旧策略或旧防回滚状态；目录不可写时会弹出管理员权限确认框。
+正常启动成功后不要删除这些状态文件，它们用于本地身份、离线策略和安全状态。
 首次运行时如果该文件不存在且发现旧 client.ini，会自动迁移。

 接入新软件时通常需要修改：
@@ -35,7 +38,7 @@ config/app_config.json 是部署配置源文件。Launcher / Updater / MainApp
 4. launcher_executable、updater_executable、bootstrap_executable。
 5. health_check_timeout_ms：升级后等待业务程序健康确认的毫秒数，最小 1000。

-完整格式参考 update-client/config/app_config.example.json。
+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 发布打包：
@@ -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`。
@@ -4,11 +4,15 @@

 当前客户端构建依赖：

-1. Qt 5.15.2 msvc2019_64
-2. OpenSSL-Win64
+1. Qt 5.15.2 或兼容的 Qt 5 版本
+2. OpenSSL
+
+Windows 下推荐使用 Qt 5.15.2 msvc2019_64 和 OpenSSL-Win64；Linux 下使用系统安装的 Qt/OpenSSL 开发包。

 ## 1. Qt 配置

+### Windows
+
 Qt 路径由本机环境变量提供。你需要在 Windows 环境变量里配置 Qt 路径，让 CMake 的 `find_package(Qt5 ...)` 能找到 Qt。

 推荐配置用户环境变量 `CMAKE_PREFIX_PATH`：
@@ -35,8 +39,27 @@ $env:CMAKE_PREFIX_PATH="C:\Qt\5.15.2\msvc2019_64"

 一般不需要把 `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 示例：
+
+```bash
+sudo apt update
+sudo apt install -y build-essential cmake qtbase5-dev qttools5-dev-tools libssl-dev
+```
+
+如果 Qt 安装在自定义目录，可以临时设置：
+
+```bash
+export CMAKE_PREFIX_PATH=/path/to/Qt/5.x/gcc_64
+```
+
 ## 2. OpenSSL 配置

+### Windows
+
 OpenSSL 默认放在：

 ```text
@@ -74,7 +97,11 @@ cmake -S . -B out\build\x64-Debug `
  -DSIMCAE_OPENSSL_ROOT="C:\Program Files\OpenSSL-Win64"
 ```

-## 3. 重新配置和编译
+### Linux
+
+Linux 下 CMake 会通过 `find_package(OpenSSL REQUIRED)` 查找系统 OpenSSL。通常安装 `libssl-dev` 即可，不需要 `thirdparty/OpenSSL-Win64`。
+
+## 3. Windows 重新配置和编译

 如果之前配置过 CMake，建议先删除旧缓存：

@@ -97,7 +124,32 @@ cmake -S . -B out\build\x64-Debug `
 cmake --build out\build\x64-Debug --config Debug
 ```

-## 4. 提交注意事项
+## 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. 提交注意事项

 不要提交下面这些内容：