chengma/cmshoppe
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(update): accept cmhub release metadata contract

Browse Source
This commit is contained in:
chengma
2026-07-13 17:17:25 +08:00
parent 74b98cd123
commit 0d7a4c1b56
8 changed files with 99 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/update-check.md
+6 -9
View File
@@ -25,10 +25,10 @@
| `download_url` | string(URL) | 安装包外链；优先 HTTPS，T-623 临时兼容任意公网 HTTP/HTTPS 地址 |
| `sha256` | string | zip 的 SHA-256；自动安装时必须是 64 位十六进制且不可为空 |
| `size_bytes` | integer | zip 的准确字节数；自动安装时必须大于 0 |
| `package_format` | string | 自动安装固定为 `cmshopee-portable-v1` |
| `updater_protocol` | integer | 发布包要求的更新器协议版本，当前为 `1` |
| `min_updater_protocol` | integer | 可安装此包的最低更新器协议，当前为 `1` |
| `release_notes` / `message` | string | 升级说明，显示在强制升级弹窗里。客户端取 `message` 或 `release_notes` |
| `published_at` | string | 服务端发布时间；客户端当前不参与强制判定 |
`package_format`、`updater_protocol`、`min_updater_protocol` 不是 cmhub 版本接口字段。客户端使用内置 `cmshopee-portable-v1` 和当前更新器协议构造安装元数据，下载后再以包内 `package-manifest.json` 验证真实格式和协议；不兼容的包仍会在替换程序前拒绝。
版本号比较用**语义化数字段比较**（`compare_versions`，逐段比数字），不是字符串字典序：`0.1.10 > 0.1.9`。
@@ -55,7 +55,7 @@ T-617 已提供独立无控制台更新器和事务回滚能力：更新器从
## 五、发版约定（服务端据此控制）
自动安装使用的全部字段必须放在同一个 `release` 对象内，不得把版本取自一个对象、hash 取自另一个对象。构建脚本生成的 `release/release-metadata.json` 是服务端录入模板；发布人员补公网 HTTP/HTTPS `download_url`、强制策略和中文发布说明，不得手工改写 hash、大小、包格式或协议版本。正式发布仍应优先使用 HTTPS；HTTP 只用于外链暂时无法提供 HTTPS 的兼容期。
自动安装使用的全部字段必须放在同一个 `release` 对象内，不得把版本取自一个对象、hash 取自另一个对象。构建脚本生成的 `release/release-metadata.json` 提供版本、zip SHA-256 和准确大小；发布人员录入公网 HTTP/HTTPS `download_url`、强制策略和中文发布说明，不得手工改写 hash 或大小。正式发布仍应优先使用 HTTPS；HTTP 只用于外链暂时无法提供 HTTPS 的兼容期。
| 想要的效果 | 服务端返回 |
| --- | --- |
@@ -75,9 +75,6 @@ T-617 已提供独立无控制台更新器和事务回滚能力：更新器从
"download_url": "https://cm.833729.com/media/downloads/%E8%9D%A6%E7%9A%AE%E5%9C%88%E5%84%AA%E5%8C%96%E5%8A%A9%E6%89%8B0.1.1.zip",
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"size_bytes": 123456789,
"package_format": "cmshopee-portable-v1",
"updater_protocol": 1,
"min_updater_protocol": 1,
"release_notes": "优化了ai模块的生图的功能",
"published_at": "2026-07-08T14:30:26.935549+08:00",
"force_update": true
@@ -121,11 +118,11 @@ T-617 已提供独立无控制台更新器和事务回滚能力：更新器从
- `download_url` 里的中文可用 URL 编码（如 `%E8%9D%A6...`），系统浏览器能正确打开。
- 版本检查接口 `APP_UPDATE_CHECK_URL` 必须保持受信任 HTTPS；只有它返回的 `download_url` 可以在 T-623 兼容期使用公网 HTTP 外链。客户端不提供手工输入下载地址或关闭校验的入口。
- 若将来要"非强制也温和提示（可跳过、不阻断）"，需在客户端加一个非强制分支，另立任务。
- 空 `sha256` 只兼容 T-544 的人工下载引导，绝不能进入自动安装。自动安装无论使用 HTTP 还是 HTTPS，都必须同时校验 `size_bytes`、整包 SHA-256、包格式、更新器协议和包内manifest。
- 空 `sha256` 只兼容 T-544 的人工下载引导，绝不能进入自动安装。自动安装无论使用 HTTP 还是 HTTPS，都必须同时校验接口 `size_bytes`、整包 SHA-256，以及客户端内置格式/协议对应的包内manifest。
- `manifest_signature` 与 `signature_algorithm` 是预留字段；当前未启用数字签名，不能将 SHA-256 描述为发布者身份认证。
## 八、引导版本与灰度发布
仍只有T-544“浏览器下载”能力的旧客户端无法凭空获得独立更新器，必须先人工覆盖一个同时包含T-615至T-619代码和 `cmshopee-updater.exe` 的引导版本。后续自动发布先以非强制方式灰度确认接口字段、下载和manifest，再开启 `force_update` 或提高 `min_supported_version`。发布包的 `updater_protocol` / `min_updater_protocol` 必须与引导版本兼容。
仍只有T-544“浏览器下载”能力的旧客户端无法凭空获得独立更新器，必须先人工覆盖一个同时包含T-615至T-619代码和 `cmshopee-updater.exe` 的引导版本。后续自动发布先以非强制方式灰度确认接口字段、下载和manifest，再开启 `force_update` 或提高 `min_supported_version`。包内manifest的 `updater_protocol` / `min_updater_protocol` 必须与引导版本兼容，cmhub 版本接口无需重复返回。
更新器启动新版后等待健康标记：`process_started` 表示基础导入、Qt和版本核对完成；`main_window_ready` 表示数据目录、必要初始化和主窗口显示完成，此时才清理成功备份；`environment_blocked` 表示数据目录、配置或Chrome等本地环境需用户处理，保留新版且不误回滚。无已知标记、版本不符、早期退出或健康等待超时会恢复旧版并写失败版本熔断记录。