cmshoppe/docs/tasks/T-623.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-623	自动升级受限 HTTP 临时兼容	8	T-619	TODO	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 业务数据或蝦皮更新流程。

执行记录

• 尚未执行。