docs: 修正 T-623 支持公网外链

2026-07-13 16:09:45 +08:00
parent 55daf3648d
commit 9a458ee195
1 changed files with 10 additions and 11 deletions
@@ -11,36 +11,35 @@ created: 2026-07-13

 当前自动升级下载层只接受 HTTPS。版本接口返回 HTTP 安装包地址时，客户端会在下载前以“新版下载地址必须使用 HTTPS”中止，无法进入已经具备的大小、SHA-256、zip 和 manifest 校验流程。

-正式发布仍应使用 HTTPS；本任务只为当前发布服务器增加可撤销的临时 HTTP 兼容，不把自动升级改成接受任意 HTTP 地址。自动升级会替换本地程序文件，HTTP 可能被监听、阻断或篡改，因此必须由 HTTPS 版本接口返回可信 hash，并继续执行现有全部完整性校验。
+正式发布仍应使用 HTTPS；本任务的临时兼容目标是支持对象存储、CDN、文件分发服务等外链，因此不能把安装包下载域名限定为版本接口域名。自动升级会替换本地程序文件，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 必须再次执行相同校验。
+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 白名单和对应分支，不把它扩展为长期配置能力。
+6. 强制升级窗口识别初始下载地址使用 HTTP 时，使用中文提示“当前使用临时 HTTP 通道下载，安装前仍会校验完整性”；诊断日志只记录协议、是否经过重定向和公网地址校验结果，不输出带查询参数的完整下载地址。
+7. 在 `docs/update-check.md`、`docs/packaging.md`、`docs/04-architecture.md` 标记该策略为临时兼容。服务端及外链恢复 HTTPS 后，应通过独立任务删除 HTTP 分支；HTTPS 外链继续保留，不重新增加下载域名限制。

 ## 验收要点

 - HTTPS 安装包沿用原流程，下载、校验、暂存、替换和重启行为不变。
- `http://cm.833729.com/media/downloads/<文件>.zip` 可以进入下载流程，并且只有通过现有大小、SHA-256、zip 安全和 manifest 校验后才能生成 `pending.json`。
- 任意其他 HTTP 域名、IP、内网地址、非 80 端口、带账号信息地址及 `/media/downloads/` 之外的路径均在下载前被拒绝。
- HTTPS 到 HTTP 的重定向始终拒绝；临时 HTTP 同源跳转和升级到受信任 HTTPS 可用，跨域/跨端口/越界路径跳转拒绝。
+- 任意公网域名或公网 IP 的 HTTP/HTTPS 安装包外链可以进入下载流程，并且只有通过现有大小、SHA-256、zip 安全和 manifest 校验后才能生成 `pending.json`。
+- 外链跨域、跨端口以及 HTTP/HTTPS 之间的重定向可用；每一跳和最终响应地址都会复核，落到本机、内网、非 HTTP(S) 协议或带账号信息的地址时拒绝。
 - HTTP 下载内容被替换、截断、hash 不匹配或缺少 hash/大小时，当前程序目录与 `data/` 不变，不启动独立更新器。
 - 强制升级窗口显示中文临时通道提示；不向普通用户提供关闭校验或添加任意 HTTP 地址的入口。

 ## 测试要求

- 扩展 `tests/test_update_installer.py`，覆盖允许的 HTTP 地址、所有来源拒绝路径、HTTPS 降级重定向、HTTP 同源/升级重定向、最终 URL 复核、大小/hash 不匹配及成功暂存。
+- 扩展 `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 版本检查接口，不接受任意用户输入的下载源，不增加设置页开关。
+- 不允许 HTTP 版本检查接口，不接受用户在客户端手工输入下载源，不增加设置页开关；下载外链只能来自 HTTPS 版本接口的发布元数据。
 - 不移除或弱化 SHA-256、声明大小、安全解压、manifest、事务替换、健康确认、失败回滚和版本熔断。
 - 不引入跳过证书验证、自签名证书信任、增量更新或静默后台升级。
 - 不修改五个业务 Tab、CDP、AI、Excel、SQLite 业务数据或蝦皮更新流程。