docs(client): 整理SDK打包文档

2026-09-08 18:14:58 +08:00
parent 8dfef45bc4
commit 613607475e
5 changed files with 137 additions and 79 deletions
@@ -6,15 +6,18 @@ SimCAE Hub 客户端文档入口
 建议先按这个顺序阅读：

 1. 01-客户端接入打包部署指南.md
-   说明客户端运行链路、配置字段、打包方式和人工验证方法。
+   说明客户端运行链路、配置字段、安装目录口径和接入限制。

 2. 02-编译环境和第三方依赖说明.md
   说明 Windows 和 Linux 下编译 Qt/C++ 客户端需要的工具、Qt、OpenSSL 和 CMake 命令。

-3. ../config/server_config.json
+3. ../打包成SDK.md
+   说明如何从 update-client 编译产物生成给 SIMCAE 开发者使用的 SDK 包。
+
+4. ../config/server_config.json
   编译进客户端资源的服务端地址配置，当前测试服务器是 http://192.168.1.158:18000。

-4. ../scripts/ReadMe.txt
+5. ../scripts/ReadMe.txt
   SDK 打包脚本和客户安装包打包脚本的简短说明。

-客户端能力、接口链路、配置字段和接入限制统一看 01 文档。当前不包含邮箱、支付、告警、灰度发布等页面上没有的业务模块；崩溃报告作为旧系统兼容后端接口保留，具体看项目根目录的 使用教学.md。
+客户端能力、接口链路、配置字段和接入限制统一看 01 文档。当前不包含邮箱、支付、告警、灰度发布等页面上没有的业务模块；崩溃报告作为旧系统兼容后端接口保留，具体看项目根目录的 项目细节.md。
@@ -11,7 +11,7 @@
 3. 在线检查更新、Manifest 拉取、受控下载、SHA-256 校验。
 4. Manifest 签名验签、临时文件、断点重试、安装前后完整性校验。

-邮箱、支付、灰度、告警等页面上没有的能力不属于当前范围。崩溃报告是 SimCAE Hub 保留的旧系统兼容后端接口，不属于 Launcher / Updater / Bootstrap 的更新链路；接入方需要崩溃上报时，按 `使用教学.md` 里的崩溃报告接口说明调用。
+邮箱、支付、灰度、告警等页面上没有的能力不属于当前范围。崩溃报告是 SimCAE Hub 保留的旧系统兼容后端接口，不属于 Launcher / Updater / Bootstrap 的更新链路；接入方需要崩溃上报时，按项目根目录 `项目细节.md` 里的崩溃报告接口说明调用。

 ## 2. 客户端程序组成

@@ -68,79 +68,15 @@

 如果换服务器，可以改完该文件后重新编译客户端；正式客户包通常由服务端写入 `api_base_url`，不需要把 `server_config.json` 暴露给客户。

-## 5. 编译
+## 5. 编译和打包 SDK

-Windows Release 编译：
+客户端编译、带 Qt 和不带 Qt 两种 SDK 打包方式、输出目录、输出 ZIP 文件名，统一维护在 [../打包成SDK.md](../打包成SDK.md)。

-```powershell
-cd update-client
-cmake --preset x64-release
-cmake --build --preset x64-release
-```
+本文件只说明 SDK 在客户软件里的接入位置和运行逻辑，不重复维护打包命令。

-Linux Release 编译：
+SDK 包不会包含最终 `app_config.json`、`server_config.json`、`server_config.qrc` 或 `manifest_public_key.pem`。这些最终配置在完整客户软件包或 Qt IFW 交付包上传到 SimCAE Hub 后由服务端生成。

-```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\SimCAEHubUpdateClientSDK `
-  -ZipFile .\dist\SimCAEHubUpdateClientSDK.zip `
-  -SdkVersion 0.1.0
-```
-
-执行成功后会生成：
-
-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
-```
-
-执行成功后会生成：
-
-1. 展开目录：`update-client\dist\SimCAEHubUpdateClientSDK-with-qt`
-2. 对外提供的 SDK 压缩包：`update-client\dist\SimCAEHubUpdateClientSDK-with-qt.zip`
-
-其中 `-OutputDir` 是脚本整理 SDK 的展开目录，`-ZipFile` 是最终要交给接入方的 SDK 压缩包。接入方没有单独准备 Qt 运行库时，优先使用带 Qt runtime 的压缩包。
-
-Linux 示例：
-
-```bash
-cd update-client
-./scripts/package-sdk.sh \
-  --source-dir ./out/linux/bin \
-  --output-dir ./dist/SimCAEHubUpdateClientSDK-linux \
-  --archive ./dist/SimCAEHubUpdateClientSDK-linux.tar.gz \
-  --sdk-version 0.1.0
-```
-
-Linux 如需带上 Qt runtime，追加 `--include-qt-runtime`。
-
-SDK 包不会包含最终 `app_config.json`、`server_config.json`、`server_config.qrc` 或 `manifest_public_key.pem`。这些最终配置在完整客户软件包上传到 SimCAE Hub 后由服务端生成。
-
-## 7. 客户安装包配置
+## 6. 客户安装包配置

 接入方应把以下文件放到客户软件目录的根目录或 `bin/` 目录：

@@ -150,7 +86,7 @@ SDK 包不会包含最终 `app_config.json`、`server_config.json`、`server_con
 4. `MainApp` 或真实业务主程序
 5. `config/` 目录，可以先为空

-### 7.1 标准目录结构和路径口径
+### 6.1 标准目录结构和路径口径

 更新系统不要求必须放在客户软件根目录。它可以放在 `SimCAE/` 根目录，也可以放在 `SimCAE/bin/` 目录。关键是让客户端配置里的 `install_root` 和服务端 Manifest 文件路径使用同一套口径。

@@ -248,7 +184,7 @@ SimCAE/

 `install_root` 由服务端根据 Launcher 所在位置自动判断：更新系统在软件根目录时写 `.`，在 `bin/` 目录时写 `..`。

-## 8. 运行数据位置
+## 7. 运行数据位置

 Windows 运行数据目录：

@@ -264,7 +200,7 @@ Linux 运行数据目录：

 Manifest 缓存保存在运行数据目录下的 `update/manifest_cache`。

-## 9. 常见问题
+## 8. 常见问题

 1. 客户门户登录失败：检查客户门户账号是否已激活、客户是否生效、密码是否正确。
 2. 检查更新没有结果：检查后台发布是否已发布、发布包是否可用、产品编码、渠道和平台参数是否一致。
@@ -36,6 +36,8 @@
 $env:CMAKE_PREFIX_PATH = "C:\Qt\5.15.2\msvc2019_64"
 ```

+如果 Qt 安装在别的位置，只改这一行。
+
 OpenSSL 可以放在 `update-client/thirdparty/OpenSSL-Win64`，也可以在配置时通过 `SIMCAE_OPENSSL_ROOT` 指向自定义目录。

 ## 3. Linux 环境
@@ -70,4 +72,4 @@ Linux Release 可执行文件输出目录以当前 CMake Preset 和构建脚本

 最终客户软件包里的 `config/app_config.json` 和 `config/manifest_public_key.pem` 由服务端在发布包上传时生成；`server_config.json` 会编译进 EXE 作为兜底地址，不需要进入 SDK 包。

-SDK 打包和客户端功能验证见 `01-客户端接入打包部署指南.md`。
+SDK 打包见 `../打包成SDK.md`，客户端运行链路和接入限制见 `01-客户端接入打包部署指南.md`。
@@ -25,7 +25,7 @@ SimCAE Hub 的 Go API。

 SDK 打包命令、两种打包模式、参数含义和输出位置，统一看：

-../Docs/01-客户端接入打包部署指南.md
+../打包成SDK.md

 生成 SDK 后，把 Launcher、Updater、Bootstrap 和必要运行库放进业务软件
 根目录或 bin 目录，再把完整软件目录压缩上传到 SimCAE Hub 管理后台的
@@ -0,0 +1,117 @@
+# Hub 更新客户端打包成 SDK
+
+本文只说明如何从 `SIMCAE/update-client` 生成给 SIMCAE 开发者使用的 SDK 包。SIMCAE 如何拿这个 SDK 打客户安装器和交付包，见项目根目录的 [客户端部署.md](../../客户端部署.md)。
+
+## 一、SDK 包含什么
+
+SDK 用来把 Hub 更新客户端接入 SIMCAE 安装包。
+
+| 内容 | 作用 |
+| --- | --- |
+| `Launcher.exe` | 客户日常启动入口，检查整包更新并启动主程序 |
+| `Updater.exe` | 拉取 Manifest、下载发布包、校验 SHA-256、准备安装 |
+| `Bootstrap.exe` | 替换运行中文件时接管安装 |
+| Qt 运行库 | 可选，给没有单独 Qt 运行环境的接入方使用 |
+| 文档 | 说明客户端目录结构、配置字段和接入方式 |
+
+SDK 不包含最终客户配置文件，例如 `app_config.json`、`server_config.json`、`server_config.qrc`、`manifest_public_key.pem`。这些文件由服务端在上传客户软件包或 Qt IFW 交付包时生成或注入。
+
+## 二、编译 Release
+
+先进入 SIMCAE 仓库下的 `update-client` 目录。如果当前已经在 SIMCAE 仓库根目录：
+
+```powershell
+cd .\update-client
+```
+
+然后执行：
+
+```powershell
+cmake --preset x64-release
+cmake --build --preset x64-release
+```
+
+编译完成后，Release 产物通常位于 `out/bin/Release`。
+
+检查核心程序：
+
+```powershell
+Test-Path .\out\bin\Release\Launcher.exe
+Test-Path .\out\bin\Release\Updater.exe
+Test-Path .\out\bin\Release\Bootstrap.exe
+```
+
+预期都返回 `True`。
+
+## 三、打包不带 Qt 运行库的 SDK
+
+适用于接入方已经有 Qt 运行环境，或希望自己控制 Qt DLL 的情况。
+
+```powershell
+.\scripts\package-sdk.ps1 `
+  -SourceDir .\out\bin\Release `
+  -OutputDir .\dist\SimCAEHubUpdateClientSDK `
+  -ZipFile .\dist\SimCAEHubUpdateClientSDK.zip `
+  -SdkVersion 0.1.0
+```
+
+输出：
+
+| 输出 | 说明 |
+| --- | --- |
+| `dist\SimCAEHubUpdateClientSDK` | SDK 展开目录 |
+| `dist\SimCAEHubUpdateClientSDK.zip` | 可交给 SIMCAE 开发者的 SDK 压缩包 |
+
+## 四、打包带 Qt 运行库的 SDK
+
+适用于接入方不想单独准备 Qt DLL，或者希望拿到后能直接放进安装包。
+
+```powershell
+.\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\SimCAEHubUpdateClientSDK-with-qt` | 带 Qt 运行库的 SDK 展开目录 |
+| `dist\SimCAEHubUpdateClientSDK-with-qt.zip` | 推荐交给 SIMCAE 开发者的 SDK 压缩包 |
+
+## 五、打包后检查
+
+```powershell
+Test-Path .\dist\SimCAEHubUpdateClientSDK-with-qt\bin\Launcher.exe
+Test-Path .\dist\SimCAEHubUpdateClientSDK-with-qt\bin\Updater.exe
+Test-Path .\dist\SimCAEHubUpdateClientSDK-with-qt\bin\Bootstrap.exe
+Test-Path .\dist\SimCAEHubUpdateClientSDK-with-qt.zip
+```
+
+预期都返回 `True`。
+
+## 六、不要提交的内容
+
+`SIMCAE/update-client/.gitignore` 已忽略这些本地内容：
+
+- `thirdparty/`
+- `out/`
+- `dist/`
+- `*.exe`
+- `*.dll`
+- `*.zip`
+- `config/app_config.json`
+- `config/client_identity.dat`
+- `config/local_state.json`
+- `config/version_policy.dat`
+
+提交前看一下：
+
+```powershell
+git status --short
+```
+
+不要把本地依赖、编译产物、SDK ZIP、客户配置和运行状态提交进仓库。