ci(release): 发版后自动预热 CDN 缓存

实测发现 CDN 接入后仍慢的真因：阿里云 CDN 对大文件按分片缓存，未被请求
过的分片不在缓存中，首批用户退化为实时回源而受源站带宽限制。同一文件
同一节点（RTT 5ms）实测：已缓存分片 10.5MB/s、未缓存分片仅 106KB/s，
相差约 95 倍——预热不是可选优化，而是大文件分发的必要步骤。

- release.yml 在安装包同步至源站后调用阿里云 PushObjectCache 预热
  .exe 与 .blockmap；latest.yml/json 按设计不缓存故无需预热
- 仅在 DOWNLOAD_BASE_URL 与 ALIYUN_ACCESS_KEY_ID 均配置时执行，
  未配置则跳过；continue-on-error 确保预热失败不推翻已成功的发布
- 元数据步骤加 id/output 复用解析出的文件名，避免重复解析 latest.yml
- 技术方案文档补充预热章节与诊断提示（勿只看 X-Cache: HIT 下结论，
  文件头部分片可能已 HIT 而中段仍需回源）

Author: Aparencia

.github/workflows/release.yml

@@ -104,6 +104,7 @@ jobs:
       # latest.json 供官网下载页动态展示版本/直链；latest.yml 供 electron-updater
       # ---------------------------------------------------------------
       - name: Generate latest.json for website
+        id: meta
         run: |
           YML=release-windows-latest/latest.yml
           VERSION=$(grep -m1 '^version:' "$YML" | awk '{print $2}')
@@ -114,6 +115,8 @@ jobs:
           printf '{"version":"%s","fileName":"%s","size":%s,"sha256":"%s","releaseDate":"%s"}\n' \
             "$VERSION" "$FILE" "$SIZE" "$SHA256" "$DATE" > release-windows-latest/latest.json
           cat release-windows-latest/latest.json
+          # 供下方 CDN 预热步骤拼接 URL
+          echo "file=$FILE" >> "$GITHUB_OUTPUT"
 
       - name: Ensure downloads directory on server
         uses: appleboy/ssh-action@v1
@@ -157,3 +160,37 @@ jobs:
             ls -t -- *.exe 2>/dev/null | tail -n +4 | while read -r f; do
               rm -f -- "$f" "$f.blockmap"
             done
+
+      # ---------------------------------------------------------------
+      # CDN 预热：大文件在 CDN 上按分片缓存，未被请求过的分片不在缓存中，
+      # 首批用户会退化为实时回源而受源站带宽限制。
+      # 实测：已缓存分片 10.5MB/s，未缓存分片仅 106KB/s（相差约 95 倍），
+      # 故预热不是可选优化而是大文件分发的必要步骤。
+      # 预热为异步任务，API 返回后后台继续拉取，此处不等待完成。
+      # ---------------------------------------------------------------
+      - name: Prefetch CDN cache
+        # 仅在已切换至 CDN 且配置了预热凭证时执行；未配置则跳过
+        if: ${{ secrets.DOWNLOAD_BASE_URL != '' && secrets.ALIYUN_ACCESS_KEY_ID != '' }}
+        # 预热失败不应推翻已成功的发布，仅标记警告
+        continue-on-error: true
+        env:
+          ALIBABA_CLOUD_ACCESS_KEY_ID: ${{ secrets.ALIYUN_ACCESS_KEY_ID }}
+          ALIBABA_CLOUD_ACCESS_KEY_SECRET: ${{ secrets.ALIYUN_ACCESS_KEY_SECRET }}
+          DOWNLOAD_BASE_URL: ${{ secrets.DOWNLOAD_BASE_URL }}
+          FILE_NAME: ${{ steps.meta.outputs.file }}
+        run: |
+          set -eo pipefail
+          curl -sL https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz -o /tmp/aliyun.tgz
+          tar -xzf /tmp/aliyun.tgz -C /tmp
+
+          BASE="${DOWNLOAD_BASE_URL%/}"
+          # 预热安装包与 blockmap（差量更新依赖）；
+          # latest.yml/json 按设计不缓存，且仅几百字节，无需预热
+          OBJECTS="$BASE/$FILE_NAME"$'\n'"$BASE/$FILE_NAME.blockmap"
+          echo "Prefetching:"
+          echo "$OBJECTS"
+
+          /tmp/aliyun cdn PushObjectCache \
+            --region cn-hangzhou \
+            --ObjectPath "$OBJECTS" \
+            --Area domestic

docs/knowledge/solutions/2026-07-installer-cdn-distribution.md

@@ -91,13 +91,50 @@ const DOWNLOAD_BASE = (
 
 1. 阿里云 CDN 添加加速域名，如 `dl.entropydecrease.com`；
 2. **业务类型**选「大文件下载加速」；
-3. **源站**填 ECS 公网 IP，**回源 Host 填 `entropydecrease.com`**——这样命中 nginx 现有 `server_name`，**无需改动 nginx 配置，也无需为子域申请证书**（CDN 侧可免费签发 HTTPS 证书）；
-4. 缓存规则：
+3. **源站**填 ECS 公网 IP，**端口必须选 443（不能选 80）**——nginx 的 80 端口是纯 `return 301` 重定向，回源到 80 只会拿到重定向而非文件内容；
+4. **回源 Host 填 `entropydecrease.com`**——命中 nginx 现有 `server_name`，**无需改动 nginx 配置，也无需为子域申请证书**（CDN 侧可免费签发 HTTPS 证书，并以回源 Host 作 SNI）；
+5. 缓存规则：
    - `.exe` / `.blockmap` → 长缓存（如 30 天，文件名含版本号，天然唯一）
    - `.yml` / `.json` → **不缓存**（更新元数据必须实时；源站已设 `Cache-Control: no-cache`）
-5. DNS 添加 CNAME 指向 CDN 提供的地址；
-6. 在 GitHub 仓库 Secrets 添加 `DOWNLOAD_BASE_URL = https://dl.entropydecrease.com`；
-7. 触发官网部署与一次发版，验证生效。
+6. DNS 添加 CNAME 指向 CDN 提供的地址；
+7. 在 GitHub 仓库 Secrets 添加
+   `DOWNLOAD_BASE_URL = https://dl.entropydecrease.com/downloads`
+   ⚠️ **必须带 `/downloads` 路径**：安装包位于 nginx 的 `/downloads/` 下，而前端与
+   electron-updater 均以 `{BASE}/文件名` 拼接。若 BASE 不带该路径，回源会变成
+   `/文件名`，nginx 会去官网根目录寻找而返回 404。
+8. 触发官网部署与一次发版，验证生效。
+
+## 预热：大文件分发的必要步骤（非可选优化）
+
+阿里云 CDN 对大文件采用**分片缓存**，只有被请求过的分片才进入缓存。未预热时，首批用户会退化为**实时回源**，速度被源站带宽拖垮——此时 CDN 几乎毫无效果。
+
+**实测对比（同一文件、同一节点、RTT 5ms）**：
+
+| 分片状态 | 速率 | 172MB 耗时 |
+|---------|------|-----------|
+| 已缓存（HIT） | **10.5 MB/s** | **约 16 秒** |
+| 未缓存（回源） | 106 KB/s | 约 27 分钟 |
+
+相差约 **95 倍**。因此每次发版必须预热新版本，否则“接了 CDN 却仍然很慢”。
+
+### 已在 CI 中自动化
+
+`release.yml` 在同步安装包至源站后调用阿里云 `PushObjectCache` 接口预热：
+
+```yaml
+- name: Prefetch CDN cache
+  if: ${{ secrets.DOWNLOAD_BASE_URL != '' && secrets.ALIYUN_ACCESS_KEY_ID != '' }}
+  continue-on-error: true          # 预热失败不推翻已成功的发布
+  run: |
+    /tmp/aliyun cdn PushObjectCache --region cn-hangzhou \
+      --ObjectPath "$OBJECTS" --Area domestic
+```
+
+要点：
+- 预热对象仅需 `.exe` 与 `.blockmap`；`latest.yml/json` 按设计不缓存且仅几百字节，无需预热。
+- 预热是**异步任务**，API 返回后后台继续拉取，CI 不等待完成。
+- 预热会从源站回源拉取全量文件，**会占用 ECS 带宽**，可能短暂影响 API；属一次性行为。
+- 需额外两个 Secrets：`ALIYUN_ACCESS_KEY_ID` / `ALIYUN_ACCESS_KEY_SECRET`，建议专用 RAM 用户仅授予 CDN 刷新预热权限。
 
 ## 优缺点
 
@@ -122,6 +159,9 @@ OSS/存储侧可忽略（保留 3 个版本约 0.5GB）。流量稳定后可购
 
 ## 注意事项
 
+- **不预热等于 CDN 白接**：大文件按分片缓存，未预热时首批用户实时回源，速度与直连源站无异（实测 106KB/s vs 已缓存 10.5MB/s）。诊断时切勿只看 `X-Cache: HIT` 就下结论——文件头部分片可能已 HIT 而中段仍需回源，应分别测量不同偏移量的 Range 速率。
+- **采购防踩坑**：本方案**不需要 OSS**，切勿购买「OSS 资源包」（尤其是「标准-同城冗余存储」容量包，与下载速度无关）。若要预付，应选「CDN/全站加速/ESA 资源包 → CDN/DCDN 下行流量 → 全国通用（中国内地）」。资源包**额度可叠加**，故先买最小规格、用完再加即可，无需预估准确；资源包过期不退。
+- **买包不等于费用封顶**：资源包用完后会**自动转为按量付费**，故费用预警与防盗链仍属必选。
 - **必须先设防再上线**：费用预算提醒 + 资源用量预警 + Referer 防盗链 + 单 IP 频次限制；可选用量封顶。公开大文件按量计费若被恶意刷取，账单会飙升。
 - **`latest.yml` 绝不可被 CDN 缓存**：否则客户端长期读到旧版本，表现为「明明发布了新版却检测不到更新」。
 - **存量客户端更新源已固化**：已安装版本的 `app-update.yml` 指向旧地址，故切换 CDN 后 **ECS 与 GitHub 两侧资产仍需继续发布**，不可下线。