diff --git a/Docs/00-先读我-客户端文档入口.txt b/Docs/00-先读我-客户端文档入口.txt index 066b467..f052228 100644 --- a/Docs/00-先读我-客户端文档入口.txt +++ b/Docs/00-先读我-客户端文档入口.txt @@ -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。 diff --git a/Docs/01-客户端接入打包部署指南.md b/Docs/01-客户端接入打包部署指南.md index 81e67da..c21e304 100644 --- a/Docs/01-客户端接入打包部署指南.md +++ b/Docs/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. 检查更新没有结果：检查后台发布是否已发布、发布包是否可用、产品编码、渠道和平台参数是否一致。 diff --git a/Docs/02-编译环境和第三方依赖说明.md b/Docs/02-编译环境和第三方依赖说明.md index 04e8353..211c674 100644 --- a/Docs/02-编译环境和第三方依赖说明.md +++ b/Docs/02-编译环境和第三方依赖说明.md @@ -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`。 diff --git a/scripts/ReadMe.txt b/scripts/ReadMe.txt index 152845f..7a14b87 100644 --- a/scripts/ReadMe.txt +++ b/scripts/ReadMe.txt @@ -25,7 +25,7 @@ SimCAE Hub 的 Go API。 SDK 打包命令、两种打包模式、参数含义和输出位置，统一看： -../Docs/01-客户端接入打包部署指南.md +../打包成SDK.md 生成 SDK 后，把 Launcher、Updater、Bootstrap 和必要运行库放进业务软件 根目录或 bin 目录，再把完整软件目录压缩上传到 SimCAE Hub 管理后台的 diff --git a/打包成SDK.md b/打包成SDK.md new file mode 100644 index 0000000..fc96836 --- /dev/null +++ b/打包成SDK.md @@ -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、客户配置和运行状态提交进仓库。