feat: 优化客户端配置和跨平台支持
This commit is contained in:
+17
-7
@@ -8,7 +8,7 @@
|
||||
| --- | --- |
|
||||
| 重新生成给别人用的 SDK 包 | 二、维护者：生成 SDK 包 |
|
||||
| 把 SDK 放到 SimCAE 或其他业务软件目录 | 三、你：把 SDK 放进业务软件目录 |
|
||||
| 从后台生成 `app_config.json` | 四、你：生成并填写 app_config.json |
|
||||
| 从后台生成 `app_config.json` 和 qrc 服务端配置 | 四、你：生成并填写客户端配置 |
|
||||
| 给业务主程序接入启动保护代码 | 五、你：业务主程序接入要求 |
|
||||
| 验证升级、回滚、健康检查 | 六、你：联调测试 |
|
||||
| 生成最终交付给用户的客户端包 | 七、维护者：生成最终客户端包 |
|
||||
@@ -23,6 +23,7 @@ SDK 核心程序：
|
||||
- `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 签名公钥，用来验证服务端发布包没有被篡改。
|
||||
|
||||
## 二、维护者：生成 SDK 包
|
||||
@@ -178,7 +179,7 @@ D:\SimCAE_SDK\scripts\install-sdk.ps1 `
|
||||
|
||||
注意：SimCAE 自己已经带有 Qt 运行库。SDK 的 Launcher/Updater 应复用 SimCAE 的 `Qt5*.dll`、`platforms/`、`imageformats/` 等目录。不要把另一套 Qt DLL 覆盖到 `SimCAE\bin`，否则可能出现“无法定位程序输入点”一类错误。
|
||||
|
||||
## 四、你：生成并填写 app_config.json
|
||||
## 四、你：生成并填写客户端配置
|
||||
|
||||
最推荐的方式是在服务端管理后台生成客户端配置：
|
||||
|
||||
@@ -188,11 +189,13 @@ D:\SimCAE_SDK\scripts\install-sdk.ps1 `
|
||||
4. 创建 License。
|
||||
5. 在“客户端配置生成”区域选择应用、渠道、License 和主程序名。
|
||||
6. 点击生成配置。
|
||||
7. 复制生成的 JSON，覆盖 `D:\SimCAE\bin\config\app_config.json`。
|
||||
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 编进程序。
|
||||
- Launcher / Updater / MainApp 启动时会计算 `app_config.json` 解析后的 JSON 内容 SHA256；如果 JSON 内容和上次导入时不同，就把文件里的配置重新写入当前 Windows 用户的注册表。
|
||||
- 后续运行时优先从注册表读取配置，不再每次直接读 JSON。
|
||||
- 运行过程中产生的动态值，例如首次输入的 `license_key`、服务端返回的 `device_id`、升级后的 `current_version`，会写入注册表。
|
||||
@@ -213,7 +216,6 @@ D:\SimCAE_SDK\scripts\install-sdk.ps1 `
|
||||
- `client_protocol`：客户端协议号，当前建议为 `3`。
|
||||
- `launch_token`：本机启动票据 HMAC 密钥。服务端生成配置时会填默认值；正式部署建议按项目统一修改。
|
||||
- `license_key`：管理后台创建 License 后生成的授权码。为空时首次启动 `Launcher.exe` 会弹窗让用户输入并保存到注册表；如果授权错误或过期，也会提示重新输入。
|
||||
- `api_base_url`：服务端 API 地址，例如 `http://192.168.229.128:8000`。
|
||||
- `client_token`：服务端 `.env` 中的 `CLIENT_API_TOKEN`，必须和服务端一致。
|
||||
- `device_id`：设备 ID。一般可以留空，首次启动时 SDK 会向服务端登记并写入注册表。
|
||||
- `install_root`：被更新的安装根目录相对 `Launcher.exe` 所在目录的位置。SDK 放在 `bin` 时填 `..`。
|
||||
@@ -232,7 +234,6 @@ D:\SimCAE_SDK\scripts\install-sdk.ps1 `
|
||||
"client_protocol": "3",
|
||||
"launch_token": "SimCAE_Launch_Token_2026_ChangeMe_32Bytes",
|
||||
"license_key": "MARSCO-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
|
||||
"api_base_url": "http://192.168.229.128:8000",
|
||||
"client_token": "SimCAEClientToken2026",
|
||||
"request_timeout_ms": "5000",
|
||||
"temp_folder": "update_temp",
|
||||
@@ -248,6 +249,14 @@ D:\SimCAE_SDK\scripts\install-sdk.ps1 `
|
||||
}
|
||||
```
|
||||
|
||||
对应的 `config/server_config.json` 示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"api_base_url": "http://192.168.229.128:8000"
|
||||
}
|
||||
```
|
||||
|
||||
## 五、你：业务主程序需要配合什么
|
||||
|
||||
当前安全模式下，业务主程序需要配合两件事：
|
||||
@@ -309,6 +318,7 @@ TicketHelper::consumeAndVerify(
|
||||
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 缓存缺失。
|
||||
|
||||
@@ -319,7 +329,7 @@ TicketHelper::consumeAndVerify(
|
||||
基础联调步骤：
|
||||
|
||||
1. 确认服务端正在运行。
|
||||
2. 确认 `bin\config\app_config.json` 中 `api_base_url`、`client_token`、`license_key`、`current_version` 正确。
|
||||
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. 成功进入业务主程序后，回到后台查看设备、升级日志、下载日志。
|
||||
@@ -398,7 +408,7 @@ Linux 下如果程序安装在 `/opt`、`/usr/local` 等普通用户不可写目
|
||||
|
||||
1. 直接启动业务主程序提示 ticket 错误：应从 `Launcher.exe` 启动。
|
||||
2. 首次启动保存配置/状态文件失败：如果目录不可写，SDK 会弹出管理员权限确认框；用户取消或当前账号没有管理员权限时仍会失败。
|
||||
3. 首次启动设备登记失败：检查 `api_base_url`、`client_token`、`license_key`、服务端 License 状态。
|
||||
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。
|
||||
|
||||
Reference in New Issue
Block a user