docs: 落 T-623 自动升级临时 HTTP 兼容

2026-07-13 16:06:30 +08:00
parent 6e485a7d88
commit 55daf3648d
1 changed files with 50 additions and 0 deletions
@@ -0,0 +1,50 @@
+---
+id: T-623
+title: 自动升级受限 HTTP 临时兼容
+phase: 8
+deps: [T-619]
+status: TODO
+created: 2026-07-13
+---
+
+## 问题 / 背景
+
+当前自动升级下载层只接受 HTTPS。版本接口返回 HTTP 安装包地址时，客户端会在下载前以“新版下载地址必须使用 HTTPS”中止，无法进入已经具备的大小、SHA-256、zip 和 manifest 校验流程。
+
+正式发布仍应使用 HTTPS；本任务只为当前发布服务器增加可撤销的临时 HTTP 兼容，不把自动升级改成接受任意 HTTP 地址。自动升级会替换本地程序文件，HTTP 可能被监听、阻断或篡改，因此必须由 HTTPS 版本接口返回可信 hash，并继续执行现有全部完整性校验。
+
+## 方案
+
+1. 保留 HTTPS 为默认下载协议和长期发布要求。`APP_UPDATE_CHECK_URL` 必须继续使用受信任域名的 HTTPS；HTTP 兼容只作用于版本接口返回的安装包 `download_url`，不放宽版本接口。
+2. 在 `app/update_installer.py` 集中定义可删除的临时 HTTP 下载策略，不增加普通用户 GUI 开关。第一版只允许精确来源 `http://cm.833729.com:80`，且路径必须位于 `/media/downloads/` 下；拒绝任意第三方域名、IP 地址、内网/本机地址、非默认端口、账号信息和其他协议。
+3. 重构下载地址校验，使 HTTPS 继续按现有受信任域名白名单校验，HTTP 只有命中临时来源和路径白名单时才通过。URL 判断不得只使用字符串前缀，必须基于解析后的 scheme、hostname、port 和规范化 path。
+4. 重定向按原始请求来源约束：HTTPS 可以跳转到受信任 HTTPS，但禁止从 HTTPS 降级到 HTTP；临时 HTTP 只允许同一白名单来源内跳转，或升级到受信任 HTTPS，不允许跨主机、跨端口或跳出允许路径。响应最终 URL 必须再次执行相同校验。
+5. HTTP 与 HTTPS 使用完全相同的自动安装硬校验：`size_bytes` 必须有效，zip 整包 SHA-256 必须为 64 位十六进制且严格匹配，包格式/更新器协议必须匹配，安全解压与包内 manifest 逐文件大小/hash 校验必须全部通过。缺少任一自动安装字段时不得因 HTTP 兼容而降级安装。
+6. 强制升级窗口识别临时 HTTP 下载时，使用中文提示“当前使用临时 HTTP 通道下载，安装前仍会校验完整性”；诊断日志只记录协议和白名单命中结果，不输出带查询参数的完整下载地址。
+7. 在代码常量和 `docs/update-check.md`、`docs/packaging.md`、`docs/04-architecture.md` 标记该策略为临时兼容。服务端恢复 HTTPS 安装包地址后，应通过独立任务删除 HTTP 白名单和对应分支，不把它扩展为长期配置能力。
+
+## 验收要点
+
+- HTTPS 安装包沿用原流程，下载、校验、暂存、替换和重启行为不变。
+- `http://cm.833729.com/media/downloads/<文件>.zip` 可以进入下载流程，并且只有通过现有大小、SHA-256、zip 安全和 manifest 校验后才能生成 `pending.json`。
+- 任意其他 HTTP 域名、IP、内网地址、非 80 端口、带账号信息地址及 `/media/downloads/` 之外的路径均在下载前被拒绝。
+- HTTPS 到 HTTP 的重定向始终拒绝；临时 HTTP 同源跳转和升级到受信任 HTTPS 可用，跨域/跨端口/越界路径跳转拒绝。
+- HTTP 下载内容被替换、截断、hash 不匹配或缺少 hash/大小时，当前程序目录与 `data/` 不变，不启动独立更新器。
+- 强制升级窗口显示中文临时通道提示；不向普通用户提供关闭校验或添加任意 HTTP 地址的入口。
+
+## 测试要求
+
+- 扩展 `tests/test_update_installer.py`，覆盖允许的 HTTP 地址、所有来源拒绝路径、HTTPS 降级重定向、HTTP 同源/升级重定向、最终 URL 复核、大小/hash 不匹配及成功暂存。
+- 扩展升级窗口测试，确认只有临时 HTTP 下载显示中文提示，HTTPS 文案和行为不回归。
+- 运行 `python -m ruff check app tests main.py`、`python -m compileall app main.py`、`python -m unittest discover -s tests` 和 `git diff --check`。
+
+## 边界（不改什么）
+
+- 不允许 HTTP 版本检查接口，不接受任意用户输入的下载源，不增加设置页开关。
+- 不移除或弱化 SHA-256、声明大小、安全解压、manifest、事务替换、健康确认、失败回滚和版本熔断。
+- 不引入跳过证书验证、自签名证书信任、增量更新或静默后台升级。
+- 不修改五个业务 Tab、CDP、AI、Excel、SQLite 业务数据或蝦皮更新流程。
+
+## 执行记录
+
+- 尚未执行。