chore: prepare repository for submodule split
This commit is contained in:
+69
-10
@@ -17,12 +17,63 @@ SDK 核心程序：
|
||||
1. 在服务端管理后台创建应用，例如 `app_id=your_app_id`。
|
||||
2. 创建或确认渠道，例如 `stable`。
|
||||
3. 创建 License，把生成的 `license_key` 填到客户端配置。
|
||||
4. 把业务程序和依赖 DLL 放到同一个发布目录。
|
||||
5. 把 SDK 的 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` 和运行时 DLL 放到该目录。
|
||||
6. 把 `config/app_config.example.json` 复制成 `config/app_config.json` 并修改字段。
|
||||
4. 把业务软件完整安装目录作为发布根目录，例如 `SimCAE\`，其中主程序位于 `bin\SimCAE.exe`。
|
||||
5. 把 SDK 的 `Launcher.exe`、`Updater.exe`、`Bootstrap.exe` 放到 `SimCAE\bin\` 目录，和 `SimCAE.exe` 同级。不要覆盖 SimCAE 自带的 `Qt5*.dll` 和 Qt 插件目录。
|
||||
6. 把 `config/app_config.example.json` 复制成 `SimCAE\bin\config\app_config.json` 并修改字段。
|
||||
7. 用户入口改成 `Launcher.exe`，不要直接双击业务主程序。
|
||||
8. 在管理后台发布新版本时，选择包含业务主程序和 SDK 运行时的干净 Release 根目录。
|
||||
|
||||
## 安装目录写权限要求
|
||||
|
||||
当前 SDK 会在 `Launcher.exe` 所在目录下写入运行时状态文件。SDK 放在 `SimCAE\bin` 时，这些文件实际位于 `SimCAE\bin` 下，例如：
|
||||
|
||||
```text
|
||||
config/app_config.json
|
||||
config/client_identity.dat
|
||||
config/local_state.json
|
||||
config/version_policy.dat
|
||||
update/
|
||||
update_temp/
|
||||
```
|
||||
|
||||
所以联调和普通运行时，`Launcher.exe` 所在目录必须允许当前 Windows 用户写入。不要直接把联调目录放在 `C:\Program Files\...` 后用普通用户启动；该目录默认禁止普通程序写文件，会导致首次启动报错，例如 `cannot save installation id`。
|
||||
|
||||
推荐联调目录：
|
||||
|
||||
```text
|
||||
D:\SimCAE_Release\
|
||||
C:\Users\<你的用户名>\Desktop\SimCAE_Release\
|
||||
```
|
||||
|
||||
如果最终产品必须安装到 `C:\Program Files\SimCAE\bin`，需要额外设计管理员提权、Windows 服务，或把运行时状态迁移到 `ProgramData` / `AppData`。当前交付版本默认按“安装目录可写”的模式工作。
|
||||
|
||||
## SimCAE 目录结构建议
|
||||
|
||||
SimCAE 当前安装目录是根目录下有 `bin/`、`Licenses/`、`installerResources/` 等子目录。SDK 推荐放在 `bin/` 目录，和 `SimCAE.exe` 同级；后台发布时仍选择整个安装根目录：
|
||||
|
||||
```text
|
||||
SimCAE/
|
||||
bin/
|
||||
Launcher.exe
|
||||
Updater.exe
|
||||
Bootstrap.exe
|
||||
SimCAE.exe
|
||||
config/
|
||||
app_config.json
|
||||
manifest_public_key.pem
|
||||
update/
|
||||
manifest_cache/
|
||||
Qt5Core.dll
|
||||
...
|
||||
Licenses/
|
||||
installerResources/
|
||||
maintenancetool.exe
|
||||
```
|
||||
|
||||
这种模式下，后台“发布新版本”时选择整个 `SimCAE/` 目录，服务端会检查 `bin/SimCAE.exe` 是否存在，并把整个安装结构写入 Manifest。客户端配置里 `install_root` 填 `..`，表示被更新的安装根目录是 `bin` 的上一级；升级事务、下载缓存和 Manifest 缓存仍放在 `SimCAE\bin\update`。
|
||||
|
||||
注意：SimCAE 自己已经带有 Qt 运行库。SDK 的 Launcher/Updater 应使用和 SimCAE 兼容的 Qt 编译，并复用 SimCAE 的 `Qt5*.dll`、`platforms/`、`imageformats/` 等目录。不要把另一套 Qt DLL 覆盖到 `SimCAE\bin`，否则会出现“无法定位程序输入点”一类错误。
|
||||
|
||||
## app_config.json 关键字段
|
||||
|
||||
```json
|
||||
@@ -39,6 +90,7 @@ SDK 核心程序：
|
||||
"request_timeout_ms": "5000",
|
||||
"temp_folder": "update_temp",
|
||||
"device_id": "",
|
||||
"install_root": "..",
|
||||
"main_executable": "SimCAE.exe",
|
||||
"launcher_executable": "Launcher.exe",
|
||||
"updater_executable": "Updater.exe",
|
||||
@@ -59,7 +111,8 @@ SDK 核心程序：
|
||||
- `client_token`：服务端 `.env` 中的 `CLIENT_API_TOKEN`，默认交付包已填 `SimCAEClientToken2026`。
|
||||
- `license_key`：管理后台创建 License 后返回的密钥；模板里先留空，创建授权后再填。
|
||||
- `launch_token`：本机启动票据 HMAC 密钥，模板已给默认值，可试跑；正式交付建议改成你自己的 32 字符以上随机字符串。
|
||||
- `main_executable`：业务主程序文件名，默认填 `SimCAE.exe`；如果你的主程序不是这个名字，这里同步修改。
|
||||
- `install_root`：安装根目录相对 `Launcher.exe` 所在目录的位置。SDK 放在 `bin` 时填 `..`。
|
||||
- `main_executable`：业务主程序相对 `Launcher.exe` 所在目录的路径，SimCAE 默认填 `SimCAE.exe`。
|
||||
- `health_check_timeout_ms`：升级后等待业务程序写健康标记的时间。
|
||||
|
||||
## 业务主程序需要配合什么
|
||||
@@ -92,15 +145,19 @@ cd client
|
||||
-SdkVersion 0.1.0
|
||||
```
|
||||
|
||||
默认生成的 SDK 不包含 Qt 运行库，避免覆盖业务软件自带的 Qt。只有在接入的软件本身不带 Qt，且你确认要让 SDK 自带一套 Qt 运行库时，才额外添加 `-IncludeQtRuntime`。
|
||||
|
||||
生成结果：
|
||||
|
||||
```text
|
||||
dist/UpdateClientSDK/
|
||||
README.md
|
||||
SimCAE自动升级SDK接入说明_v0.1.docx
|
||||
sdk_manifest.json
|
||||
bin/
|
||||
config/
|
||||
app_config.json
|
||||
manifest_public_key.pem
|
||||
scripts/
|
||||
samples/
|
||||
```
|
||||
|
||||
把 `UpdateClientSDK.zip` 发给接入方即可。
|
||||
@@ -123,7 +180,9 @@ cd client
|
||||
## 常见错误
|
||||
|
||||
1. 直接启动业务主程序提示 ticket 错误：应从 `Launcher.exe` 启动。
|
||||
2. 首次启动设备登记失败：检查 `api_base_url`、`client_token`、`license_key`、服务端 License 状态。
|
||||
3. 策略或 Manifest 验签失败：检查 `config/manifest_public_key.pem` 是否和服务端私钥匹配。
|
||||
4. 升级后回滚：检查业务程序是否在 `health_check_timeout_ms` 内写入健康标记。
|
||||
5. 发布失败提示主程序不在根目录：选择发布目录时要选择业务主程序所在目录，而不是上层或下层目录。
|
||||
2. 首次启动提示 `cannot save installation id`：当前目录不可写，常见于 `C:\Program Files\...`；请换到可写目录联调，或用管理员权限/提权方案。
|
||||
3. 首次启动设备登记失败：检查 `api_base_url`、`client_token`、`license_key`、服务端 License 状态。
|
||||
4. 策略或 Manifest 验签失败：检查 `config/manifest_public_key.pem` 是否和服务端私钥匹配。
|
||||
5. 升级后回滚：检查业务程序是否在 `health_check_timeout_ms` 内写入健康标记。
|
||||
6. 发布失败提示主程序不在根目录：选择发布目录时要选择业务主程序所在目录，而不是上层或下层目录。
|
||||
7. 启动时提示 `无法定位程序输入点 ... Qt5*.dll`：通常是 Qt DLL 被不同版本覆盖或混用。恢复业务软件原始 Qt DLL，并重新打包 SDK；SimCAE 场景下不要使用 `-IncludeQtRuntime`。
|
||||
|
||||
Reference in New Issue
Block a user