photo-live/infra/deploy/cdn-checklist.md

阿里云全球 CDN 接入核对单（P5-prep Task 3）

全部步骤「待凭证执行」：本清单只固化决策与命令样例，不预设任何已执行 状态。凭证/域名到位（G5）后按 T5 逐项勾选。关联：RUNBOOK.md §5.3（无 CDN 基线的缓存故障排查）、总纲 P5 行、docs/plans/2026-09-21-P5-真实环境接入.md T5。

0. 前置决策：图片加速三选一（重要架构核对，登记为 P5 决策项）

现状（代码事实）：图片一律走 OSS presigned GET 直链（S3 兼容 SigV4 签名， SIGNED_URL_TTL_SECONDS=900s；variants 内容寻址键 photoId+规格，公开列表每次 现签 thumb.url / browse.url）。若 CDN 图片域名开启 CDN 自己的 URL 鉴权， 客户端 URL 将出现「CDN 签名参数 + OSS 签名参数」双层签名：CDN 校验自己的鉴权 参数后回源时带原 query 请求 OSS，OSS 再验自己的签名——两层参数互不冲突但 缓存键含全部 query，每个 900s 签名版本各成一册缓存，命中率崩塌；若为命中率 忽略 query，鉴权语义又互相残废。三个候选方案：

方案	内容	评估
a) 图片域名 CDN 仅缓存不鉴权	关 CDN 鉴权 + 忽略 query 参数缓存，依赖「OSS presign 过期」兜底	失效语义劣化：presign 过期只约束回源，CDN 缓存内对象在 TTL 内仍可命中；忽略 query 后鉴权退化为「对象键不可猜」（cuid 随机，强度可接受但低于签名）；隐藏照片失效窗口 = CDN 缓存 TTL，需配合主动失效。仅缓存静态 variants 可接受，收益有限
b) CDN 鉴权 + 回源 OSS 私有桶	图片域名开 CDN URL 鉴权（B 型），回源用阿里云「CDN 授权访问 OSS 私有 Bucket」（§2），服务端 presignGet 改签 CDN 鉴权 URL	正解但需改造：签名安全模型从「OSS SigV4」迁到「CDN 鉴权」，packages/storage 的 presignGet 需按环境切换签名后端（或双签并存灰度）；改造量集中在 storage 适配层 + 契约（URL 形态变化对前端透明，仍是无差别 URL 字符串）。图片加速收益明确后采用
c) 【推荐起步】保持 presigned 直链 + CDN 仅加速 viewer 静态资源	只建 viewer 域名加速区（§1 Zone 1），图片域名 Zone（§1 Zone 2）暂不接入	最小改动、签名安全模型不变、零代码；图片加速收益（900s 内重复读同图省回源带宽）先观察 OSS 流量账单再评估 b

推荐：c 起步，图片流量账单 / 海外首屏时延数据到位后按 b 改造（a 不推荐， 失效语义与鉴权强度双损）。已登记为 P5 决策项（T5 内定案）。

1. 添加加速域名（待凭证执行；两 Zone）

#	加速域名	业务	源站	状态
Zone 1	<ov viewer 域名>（如 photo.example.com）	viewer/admin SPA 静态 + /v1/ API 透传	ov 服务器 OpenResty 公网 IP（源站协议 https 回源 8089 需开白名单）	☐ 待凭证执行
Zone 2	<图片域名>（如 img.example.com，CNAME 至同一 OSS 桶）	OSS 图片加速	OSS Bucket（私有，需 §2 回源授权）	☐ 待凭证执行（方案 c 起步 = 本 Zone 暂缓创建）

每个 Zone 通用步骤（控制台：CDN → 域名管理 → 添加域名，业务类型「图片小 文件」/「小文件下载」；全球加速 = 不限区域或选「全球」）：

• 添加域名 + 选择业务类型 + 源站信息（Zone 1 填 ov 服务器 IP；Zone 2 选 OSS 域名源站）
• CNAME 解析（DNS 服务商把域名 CNAME 到 CDN 分配的 *.w.kunlun*.com）
• HTTPS：申请/绑定证书 + 开启「强制 HTTPS」+（可选）HTTP/2
• 回源 Host 按默认（Zone 2 回源 Host = OSS 桶域名，控制台自动处理）

2. 源站 = OSS 私有 Bucket 回源授权（仅 Zone 2 / 方案 b 时需要；待凭证执行）

阿里云 CDN 回源私有 OSS 需授权二选一：

方式	操作	适用
方式一：控制台一键 OSS 授权	CDN 控制台源站配置时点「授权」，按提示同意创建 AliyunCDNDefaultRole（云账号级，授予 CDN 读 OSS 权限）	最快，个人账号推荐
方式二：自定义 RAM 角色	RAM 控制台创建角色（受信实体=CDN）+ 最小权限策略（仅目标桶 oss:GetObject）+ CDN 源站配置选该角色	多项目共用账号、需权限隔离时

• 按 §0 决策结果确定是否执行本节（方案 c 起步则整节跳过）

3. URL 鉴权选型（仅 Zone 2 / 方案 b；待凭证执行）

型式	URL 形态	特点
A 型	md5(<uri>-<timestamp>-<rand>-<uid>-<key>) 拼接，时间戳进 MD5 不可读	更防猜测，但排障时无法从 URL 直接看出过期时刻
B 型【推荐】	http://…/<uri>-<timestamp>-<md5hash>，时间戳明文	时间戳在 URL 可读可调试（一眼判过期）；CDN 控制台配置简单（主备 key 各一个）；鉴权粒度与 A 型同级

推荐 B 型理由：现场排障（观众报「图裂」）能直接从 URL 读出时间戳判断是否过期 窗口问题；主备 key 支持平滑轮换。与现有 presigned GET 的关系：方案 b 下 presignGet 输出从 OSS SigV4 URL 改为 CDN B 型鉴权 URL（§0 表格）；方案 c 下 无任何 URL 鉴权变更（Zone 1 静态资源不鉴权，本来就公开）。

• 若定案方案 b：Zone 2 配置 B 型鉴权 + 主备 key（openssl rand -hex 32）
• 服务端 presignGet 签名后端改造排期（storage 适配层 + 测试）

4. 缓存规则表（Zone 1；待凭证执行）

原则：源站 photo-live-web 已对内容寻址路径发 Cache-Control: immutable （infra/deploy/nginx.conf.template），CDN 遵循源站头即可，无需重配长 TTL。 计划占位稿中的「/assets/ 7d」按此修正为遵循源站 immutable（内容寻址键允许， 发新版 = 新 URL，无失效问题）。

路径	CDN 缓存策略	依据
/embed/v1/*	遵循源站：immutable 一年	版本目录即内容版本（nginx 同规则）
/assets/*、/admin/assets/*	遵循源站：immutable 一年	vite 内容寻址产物
/、/index.html、/admin/、/admin/index.html、SPA 回退路径	不缓存（no-cache，每次回源）	发布新版必须立即生效，HTML 引用新 hash 的 assets
/v1/*（API/WS）	不缓存 + 透传 x-request-id 头	动态 API；WS 经 CDN 需在 CDN 侧确认支持或对 /v1/realtime 单独跳过 CDN（建议 DNS 直连源站，见 §7 注意）

• 按上表在 CDN 控制台配置缓存规则（HTML/回退路径显式 no-cache 兜底—— 源站对 index.html 未显式发 no-cache 头，CDN 侧补齐这道保险）
• 验证：curl -sI https://<域名>/ | grep -i cache 确认未命中缓存

5. 失效 / 预热 API 样例（待凭证执行）

阿里云 CDN OpenAPI 需 AccessKey 签名（ACS3-HMAC-SHA256），raw curl 组签名繁琐， 推荐 aliyun CLI 形态（aliyun CLI 配置凭证后即用；curl 等价样例在凭证到位 后按官方签名文档补齐——本节全部待凭证执行）：

# 隐藏照片 → 失效该照片全部 variants 路径（对象键含 photoId 与内容版本；
# 方案 b 下才需要——variants 是 immutable 缓存，隐藏 = 主动失效 + 公开 API 404 双保险）
# 多 URL 用换行分隔（RefreshObjectCatches/PreloadObjectCaches 的 ObjectPath 约定）
aliyun cdn RefreshObjectCaches \
  --ObjectPath "$(printf '%s\n%s' \
    'https://<图片域名>/photo-live/prod/albums/<albumId>/variants/<photoId>/<version>/thumb.jpg' \
    'https://<图片域名>/photo-live/prod/albums/<albumId>/variants/<photoId>/<version>/browse.jpg')" \
  --ObjectType File

# 新活动发布 → 预热首页与首屏静态资源（viewer 域名，降低冷缓存首访时延）
aliyun cdn PreloadObjectCaches \
  --ObjectPath "$(printf '%s\n%s' \
    'https://<viewer域名>/assets/<新版本hash>.js' \
    'https://<viewer域名>/assets/<新版本hash>.css')"

# 目录级失效（发版后 SPA HTML 变更；范围大时用，注意每日失效配额）
aliyun cdn RefreshObjectCaches --ObjectPath "https://<viewer域名>/" --ObjectType Directory

• 隐藏照片失效窗口验证（方案 b 时）：上传 → 公开可读 → 隐藏 → 立即请求 variants URL：公开 API 应 404（PHOTO_NOT_PUBLIC），CDN 失效执行完成后 图片 URL 应 403/404；失效前的窗口 = 设计允许的失效窗口（对齐 P4a 契约决策与 RUNBOOK §5.3，CDN 侧窗口上限 = 失效 API 生效延迟，需实测 登记进 RUNBOOK）
• 发版后预热纳入发布检查单（RUNBOOK §1 增补一行，待 CDN 实际接入后回填）

6. 冷缓存测试点（海外多地域时延记录表模板）

各地域单点拨测（冷缓存 = 首次请求回源；建议每地域 curl 3 次取中位），模板：

地域（测试点）	测试方式	冷缓存 TTFB/总时延	热缓存复测	时间	备注
新加坡	curl -s -o /dev/null -w '%{time_starttransfer} %{time_total}\n' https://<viewer域名>/	___ / ___	___	___
东京	同上	___ / ___	___	___
法兰克福	同上	___ / ___	___	___
美西（硅谷）	同上	___ / ___	___	___
美东（弗吉尼亚）	同上	___ / ___	___	___
国内对照（杭州）	同上	___ / ___	___	___	不走全球 CDN 国内段时的对照基线

可选公共拨测源：阿里云云监控站点监控（多地域）、第三方（如 GTmetrix / WebPageTest） 留档截图。记录表随 T5 产出归档进 P5 验收记录。

7. 注意事项与边界

• WS（/v1/realtime）不适合过 CDN：长连接透传稳定性依赖 CDN 支持；建议 viewer 前端 WS 地址直连源站域名（或单独一个不接 CDN 的子域），CDN 只加速 静态与普通 API。核对前端 realtime 连接 URL 的构造（P5 T4/T5 联合验证项）。
• Zone 1 源站是 ov 服务器 OpenResty：CDN 回源 IP 段需加入 OpenResty 白名单 （1Panel 防火墙），并确认回源走 https（证书已就绪）。
• 速率/配额：CDN 每日失效/预热有配额（控制台可见），发版高频期优先用文件级 精确失效；目录级失效作为兜底。
• 全部步骤执行前保持「无 CDN」基线可用（RUNBOOK §5.3），CDN 故障时 DNS 切回 直连即回滚（T8 演练项之一）。