Merge branch 'dev': CDN 交付经验沉淀

Author: Aparencia

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

@@ -148,6 +148,40 @@ const DOWNLOAD_BASE = (
 - 预热会从源站回源拉取全量文件，**会占用 ECS 带宽**，可能短暂影响 API；属一次性行为。
 - 需额外两个 Secrets：`ALIYUN_ACCESS_KEY_ID` / `ALIYUN_ACCESS_KEY_SECRET`，建议专用 RAM 用户仅授予 CDN 刷新预热权限。
 
+## 最终交付结果（实测）
+
+| 阶段 | 单连接速率 | 172MB 耗时 |
+|------|-----------|-----------|
+| 最初（ECS 直连） | 140 KB/s | **20.5 分钟** |
+| 阶段 0（nginx 调参 + BBR） | 148 KB/s | 约 20 分钟（几乎无改善）|
+| CDN 回源 ECS、未预热 | 145 KB/s | 约 20 分钟 |
+| **CDN + OSS + 已预热** | **88.7 MB/s** | **1.94 秒** |
+
+提升约 **630 倍**。关键认识：前三行说明**光接 CDN 不够**——源站带宽与预热缺一不可。
+
+### 终态链路
+
+```
+发版 → 构建 → ┌─ GitHub Release（备用源 / 存量客户端更新源）
+              ├─ ECS /downloads/（兜底）
+              └─ OSS（CDN 源站）→ 自动预热
+                        ↓
+官网 & electron-updater → dl.entropydecrease.com（CDN）
+```
+
+## CI 实现陷阱（均已踩中并修复）
+
+以下四个错误都**无法在本地预验证**，只有通过 CI 实际运行才会显现，共消耗了四个版本号（v0.28.7–v0.28.10）：
+
+| # | 错误 | 现象 | 正确做法 |
+|---|------|------|---------|
+| 1 | `if:` 中使用 `secrets` 上下文 | **整个 workflow 无法解析**，所有触发 0 秒报错、workflow 名退化为文件路径 | `secrets` 仅可用于 `env`/`with`/`run`；先注入 job 级 `env`，`if` 中用 `env.*` |
+| 2 | `-c.publish.0.url=` 覆盖 electron-builder 配置 | `ValidationError: configuration.publish should be one of these` | 数组索引语法会被解析成对象 `{publish:{0:{url}}}`；改为直接改写配置文件（sed 行锚定） |
+| 3 | `aliyun oss cp -i/-k` 传凭证 | `ERROR: unknown flag -i` | 新版 CLI 已移除该短参数；改用 `aliyun configure set --profile` 写入凭证 |
+| 4 | `gh release view` 未指定仓库 | `failed to run git: not a git repository` | release job 不做 checkout，`gh` 无法推断仓库；必须设 `GH_REPO` |
+
+**教训**：涉及外部 CLI 参数与 CI 表达式限制时，应**先查证确切用法再动手**，而非依赖惯例假设；每次试错都会消耗一个版本号并可能产生空 Release。
+
 ## 优缺点
 
 | 优点 | 缺点 |
@@ -159,6 +193,8 @@ const DOWNLOAD_BASE = (
 
 ## 成本参考
 
+### CDN 侧（用户下载流量）
+
 按 172MB/次（≈0.168GB）估算，国内 CDN 首档约 0.2–0.24 元/GB（**实际以控制台阶梯价为准**）：
 
 | 月下载量 | 流量 | 预估月费 |
@@ -167,12 +203,34 @@ const DOWNLOAD_BASE = (
 | 200 次 | 34 GB | 约 8 元 |
 | 1000 次 | 168 GB | 约 40 元 |
 
-OSS/存储侧可忽略（保留 3 个版本约 0.5GB）。流量稳定后可购买流量包，单价降至约 0.1–0.12 元/GB。
+### OSS 侧（源站）
+
+| 费用项 | 单价 | 实际量 | 月费 |
+|--------|------|--------|------|
+| 标准存储 | 0.12 元/GB/月 | 0.5 GB（保留 3 版） | 约 0.06 元 |
+| **CDN 回源流出流量** | **0.15 元/GB** | 预热节点数 × 包大小 | 几元 |
+| CI 上传（上行流量） | **免费** | — | 0 |
+| 请求次数 | 极低 | 极少 | 可忽略 |
+
+回源流量主要由**预热**产生（每节点各拉一份），按 30 节点估：
+
+| 每月发版数 | 回源流量 | 月费 |
+|-----------|---------|------|
+| 3 次 | 15.5 GB | 约 2.3 元 |
+| 10 次 | 52 GB | 约 7.8 元 |
+
+> 降低这笔开销的有效手段是**减少无必要的发版**（纯 CI 修复用 `ci:`/`chore:` 类型提交，不触发 semantic-release），而不是买流量包。
+
+### 采购结论
+
+整套方案**只需买 CDN 下行流量包**（最小 50GB 约 8.4 元/年，额度可叠加）。**OSS 侧存储包与流量包均无需购买**——用量太小，按量付费永远更便宜且无过期浪费风险。
 
 ## 注意事项
 
+- **免费证书 90 天到期**：CDN 加速域名的免费 DV 证书有效期仅 90 天，到期前需重新申请并在 HTTPS 配置中替换，否则 `https://dl.…` 全面不可用（官网下载与自动更新同时断链）。
+- **源站切换后回源 Host 必须跟着变**：源站为 ECS 时回源 Host 填主域（命中 nginx `server_name`）；改为 OSS 后必须改为“源站域名”，否则 OSS 认不出 Bucket。私有 Bucket 还需开启「**OSS 私有 Bucket 回源**」，否则 403。
 - **不预热等于 CDN 白接**：大文件按分片缓存，未预热时首批用户实时回源，速度与直连源站无异（实测 106KB/s vs 已缓存 10.5MB/s）。诊断时切勿只看 `X-Cache: HIT` 就下结论——文件头部分片可能已 HIT 而中段仍需回源，应分别测量不同偏移量的 Range 速率。
-- **采购防踩坑**：本方案**不需要 OSS**，切勿购买「OSS 资源包」（尤其是「标准-同城冗余存储」容量包，与下载速度无关）。若要预付，应选「CDN/全站加速/ESA 资源包 → CDN/DCDN 下行流量 → 全国通用（中国内地）」。资源包**额度可叠加**，故先买最小规格、用完再加即可，无需预估准确；资源包过期不退。
+- **采购防踩坑**：需要的是 **OSS Bucket（创建免费、按量计费）**，而**不是任何 OSS 资源包**。切勿购买「OSS 存储包」（尤其是「标准-同城冗余存储」容量包，与下载速度无关）或 OSS 流量包——存储仅 0.5GB、回源流量每月几 GB，按量付费每月不到十元。唯一值得预付的是「CDN/全站加速/ESA 资源包 → CDN/DCDN 下行流量 → 全国通用（中国内地）」。资源包**额度可叠加**，故先买最小规格、用完再加即可；资源包过期不退。
 - **买包不等于费用封顶**：资源包用完后会**自动转为按量付费**，故费用预警与防盗链仍属必选。
 - **必须先设防再上线**：费用预算提醒 + 资源用量预警 + Referer 防盗链 + 单 IP 频次限制；可选用量封顶。公开大文件按量计费若被恶意刷取，账单会飙升。
 - **`latest.yml` 绝不可被 CDN 缓存**：否则客户端长期读到旧版本，表现为「明明发布了新版却检测不到更新」。