53 lines
5.6 KiB
Markdown
53 lines
5.6 KiB
Markdown
---
|
|
id: T-623
|
|
title: 自动升级受限 HTTP 临时兼容
|
|
phase: 8
|
|
deps: [T-619]
|
|
status: DONE
|
|
created: 2026-07-13
|
|
---
|
|
|
|
## 问题 / 背景
|
|
|
|
当前自动升级下载层只接受 HTTPS。版本接口返回 HTTP 安装包地址时，客户端会在下载前以“新版下载地址必须使用 HTTPS”中止，无法进入已经具备的大小、SHA-256、zip 和 manifest 校验流程。
|
|
|
|
正式发布仍应使用 HTTPS；本任务的临时兼容目标是支持对象存储、CDN、文件分发服务等外链，因此不能把安装包下载域名限定为版本接口域名。自动升级会替换本地程序文件，HTTP 可能被监听、阻断或篡改，因此可信根必须来自 HTTPS 版本接口返回的 hash，并继续执行现有全部完整性校验。
|
|
|
|
## 方案
|
|
|
|
1. 保留 HTTPS 为默认下载协议和长期发布要求。`APP_UPDATE_CHECK_URL` 必须继续使用受信任域名的 HTTPS；HTTP 兼容只作用于版本接口返回的安装包 `download_url`，不放宽版本接口。
|
|
2. 在 `app/update_installer.py` 集中定义可删除的临时 HTTP 下载策略，不增加普通用户 GUI 开关。安装包地址允许任意公网 HTTP/HTTPS 域名和公网 IP，不维护下载域名、端口或路径白名单；拒绝空主机、账号信息、`file://` 等其他协议以及本机、环回、链路本地、保留、组播和内网地址。
|
|
3. 重构下载地址校验，基于解析后的 scheme、hostname、port 和地址类型判断，不使用字符串前缀。域名外链在连接前解析地址，解析结果包含非公网地址时拒绝；公网 IP 外链可以使用。DNS 解析失败按普通下载失败处理，不放宽为可访问内网。
|
|
4. 外链常见的跨域 CDN/对象存储重定向必须可用：HTTP 与 HTTPS 可以跨公网主机、端口和路径跳转，每一次重定向目标及响应最终 URL 都重新执行公网 HTTP/HTTPS 校验。任何一步落到本机、内网、非 HTTP(S) 协议或带账号信息的地址都立即拒绝。
|
|
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 外链继续保留，不重新增加下载域名限制。
|
|
|
|
## 验收要点
|
|
|
|
- HTTPS 安装包沿用原流程，下载、校验、暂存、替换和重启行为不变。
|
|
- 任意公网域名或公网 IP 的 HTTP/HTTPS 安装包外链可以进入下载流程，并且只有通过现有大小、SHA-256、zip 安全和 manifest 校验后才能生成 `pending.json`。
|
|
- 外链跨域、跨端口以及 HTTP/HTTPS 之间的重定向可用；每一跳和最终响应地址都会复核，落到本机、内网、非 HTTP(S) 协议或带账号信息的地址时拒绝。
|
|
- HTTP 下载内容被替换、截断、hash 不匹配或缺少 hash/大小时，当前程序目录与 `data/` 不变，不启动独立更新器。
|
|
- 强制升级窗口显示中文临时通道提示；不向普通用户提供关闭校验或添加任意 HTTP 地址的入口。
|
|
|
|
## 测试要求
|
|
|
|
- 扩展 `tests/test_update_installer.py`，覆盖不同公网域名和公网 IP 的 HTTP/HTTPS 地址、跨域和跨协议重定向、内网/本机/非 HTTP(S) 拒绝、最终 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 版本检查接口，不接受用户在客户端手工输入下载源，不增加设置页开关；下载外链只能来自 HTTPS 版本接口的发布元数据。
|
|
- 不移除或弱化 SHA-256、声明大小、安全解压、manifest、事务替换、健康确认、失败回滚和版本熔断。
|
|
- 不引入跳过证书验证、自签名证书信任、增量更新或静默后台升级。
|
|
- 不修改五个业务 Tab、CDP、AI、Excel、SQLite 业务数据或蝦皮更新流程。
|
|
|
|
## 执行记录
|
|
|
|
- 2026-07-13：自动升级安装包地址由固定 HTTPS 域名白名单改为任意公网 HTTP/HTTPS 外链；初始地址、跨域/跨协议重定向和最终响应统一解析并拒绝本机、内网、保留地址、账号信息及非 HTTP(S) 协议。
|
|
- 2026-07-13：保留声明大小、整包 SHA-256、安全解压、包内manifest、事务替换和健康回滚全部校验；强制升级窗口只在初始地址为 HTTP 时显示中文临时通道提示。
|
|
- 2026-07-13：补齐公网域名、公网 IP、HTTP 完整暂存、跨域/跨协议跳转、最终地址复核、内网拒绝、hash 篡改和 GUI 提示测试，并同步架构、版本接口与打包文档。
|
|
- 2026-07-13：为隔离工作区既有提示词/版本号改动，在独立干净 worktree 验证通过：Ruff、Python 3.10 compileall、完整 unittest 436 项及 `git diff --check` 全绿；未连接真实发布外链执行在线升级。
|