alibabacloud-cdn-refresh-preload

CDN 刷新与预热诊断

诊断 CDN 刷新与预热问题：“刷新后内容未更新”“预热失败”“缓存未清除”“URL 刷新未生效”“目录刷新后仍显示旧内容”。

核心方法：首先查询刷新/预热任务记录以确认任务状态，然后根据刷新类型（文件/目录/预热）沿不同的诊断分支进行排查。

可观测性

所有 OpenAPI 调用（通过 aliyun CLI 执行）都包含：

• User-Agent：--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}
• SKILL_NAME：alibabacloud-cdn-refresh-preload
• session-id：每个诊断会话生成的 32 位十六进制字符串

前提条件

1. Python 3.11+ 和 aliyun CLI — 必需：aliyun cdn describe-refresh-tasks 和 aliyun sts assume-role 均通过 aliyun CLI 调用（不直接进行 HTTP 签名）。无需外部 Python SDK 依赖。

2. 阿里云凭证 — aliyun CLI 默认凭证链会自动解析凭证（环境变量或 ~/.aliyun/config.json）。不要显式读取、打印或传递 AK/SK/STS 令牌。

3. 目标输入：URL（要诊断的资源）和 UID（阿里云账号 UID）。UID 可以省略 — 默认通过 aliyun sts get-caller-identity 获取调用方账号。先自动填充，再询问：如果可以推导出 UID 或角色名称，绝不要向用户询问。

   自动填充声明要求：每当自动填充任何参数（UID、域名、URL 或角色名称）时，Agent MUST 在回复或报告元数据中明确声明。例如：“UID 通过 sts:GetCallerIdentity 自动推导：1772241626973633”或“域名通过 DescribeUserDomains 自动发现：tofirae.com”或“URL 从刷新任务记录中自动提取：https://tofirae.com/1.png”。此声明为必填项，必须出现在最终输出中。

   URL 自动补全：如果用户只提供域名（未提供 URL），该技能会查询该域名的任务记录，并自动提取最近的 URL。如果既未提供 URL，也未提供域名，该技能会查询所有任务记录，并自动提取最近的 URL。这适用于用户未提供特定 URL 的“信息不完整”场景。

身份验证：身份核验

aliyun CLI 默认凭证链会自动解析凭证（环境变量或 ~/.aliyun/config.json）。不要显式读取、打印或传递 AK/SK/STS 令牌。

SKILL_DIR=~/.qoderwork/skills/alibabacloud-cdn-refresh-preload

# Verify caller identity and derive the caller UID (auto-cached)
# --uid is informational only (recorded in the report for traceability); credentials always come from the CLI default credential chain
# --role-name defaults to cseesadiagnosticrole if omitted; do not ask the user for it
cd $SKILL_DIR && python3 scripts/sts_token.py --json

sts_token.py 仅执行身份核验和 UID 推导 — 不携带、打印或传递凭证。

身份核验失败：如果 sts_token.py 失败，则表示账号尚未获得调查权限。请引导客户通过 RAM 控制台授权。

注意：sts_token.py 仅执行身份核验（通过 aliyun sts get-caller-identity 加上嵌套角色检测提示）；它绝不会调用 aliyun sts assume-role。如果运行时已注入诊断角色会话（调用方 Arn 为 assumed-role/cseesadiagnosticrole/...），脚本只需依赖 aliyun CLI 默认凭证链 — 无需额外授权步骤。

诊断流程

步骤 1：查询刷新/预热任务记录

# Mode 1: URL provided (existing behavior)
# uid omitted -> auto-derived via aliyun sts get-caller-identity
cd $SKILL_DIR && python3 scripts/cdn_refresh_preload.py --url <URL>

# Mode 2: Domain-only (auto-extract URL from task records)
cd $SKILL_DIR && python3 scripts/cdn_refresh_preload.py --domain <DOMAIN>

# Mode 3: No params (auto-extract most recent URL from all task records)
cd $SKILL_DIR && python3 scripts/cdn_refresh_preload.py

结果	下一步
未找到任务记录	场景 R4：未执行操作或入口有误
找到任务，但状态为 Failed	场景 R5：任务执行失败
找到任务，状态为 Complete（文件刷新）	步骤 2a
找到任务，状态为 Complete（目录刷新）	步骤 2b
找到任务，状态为 Complete（预热）	步骤 2c

步骤 2a：文件刷新已完成但未生效

1. 比较刷新 URL 与用户实际测试的 URL。两者不一致 = 场景 R1。
2. 远程缓存验证（步骤 3）：
   • MISS = 刷新已生效，问题可能出在客户端/浏览器缓存
   • HIT = 检查 Age 响应头；如果旧缓存仍然存在 = 场景 R6

步骤 2b：目录刷新已完成，但未生效

1. 使用 If-Modified-Since / If-None-Match 标头探测绑定的源站（步骤 4）：
   • 源站返回 304 = 场景 R2：源站资源未变化，CDN 保留旧缓存
   • 源站返回 200 且内容有变化 = 继续调查
2. 验证远程缓存（步骤 3）
3. 问题仍然存在 = 场景 R6（兜底）

步骤 2c：预热已完成，但未生效

1. 验证远程缓存（步骤 3）：
   • HIT = 预热已生效
   • MISS = 继续
2. 探测绑定的源站，检查源站的 Cache-Control / 状态码（步骤 4）：
   • 源站返回 no-cache / no-store / private = 场景 R3
   • 源站返回非 200 状态码 = 场景 R3
   • 源站正常返回 200 且带有缓存标头 = 场景 R6（兜底）

步骤 3：验证远程缓存

cd $SKILL_DIR && python3 scripts/cdn_probe.py 'curl -ksI "<URL>"'

重点关注：X-Cache（HIT/MISS）、Age、Via、Cache-Control、Last-Modified、ETag。

如果 HTTPS 探测因 SSL/TLS 握手错误而失败（例如，curl 退出代码 35），请使用 http:// 协议重试同一探测；HTTP 响应仍会携带 CDN 缓存标头（X-Cache/Age）。

所有探测命令（dig/curl/openssl）都必须通过 scripts/cdn_probe.py 执行，切勿直接在 Shell 中运行 dig 或 curl。

步骤 4：探测绑定的源站（可选，由 Agent 使用 curl/dig 执行）

此技能中的脚本不会自动获取源站配置（所有脚本都是基于 CLI 的只读查询）。Agent 必须先手动获取源站地址：

• 向客户询问源站 IP/域名，或
• 使用 cdn_probe.py 'dig <accelerated domain>' 检查 DNS 解析结果作为线索。

所有探测命令（dig/curl/openssl）都必须通过 scripts/cdn_probe.py 执行，切勿直接在 Shell 中运行 dig 或 curl。

然后从步骤 3 的响应中提取 Last-Modified 和 ETag，并运行绑定的源站探测：

cd $SKILL_DIR && python3 scripts/cdn_probe.py 'curl -ksI -H "Host: <CDN domain>" -H "If-Modified-Since: <Last-Modified>" -H "If-None-Match: <ETag>" --resolve <origin host>:443:<origin IP> "https://<origin host>/<path>"'

重点关注：源站返回 304（资源未变化）还是 200（资源已变化）。同时检查 Cache-Control、Pragma、Set-Cookie。

如果无法获取源站地址，请跳过此步骤，并根据步骤 2/3 的结果得出结论。

步骤 5：输出诊断报告

按照 references/report-template.md 生成报告。

故障场景

R1：刷新 URL 不匹配

文件刷新已完成，但用户仍看到旧内容。提交的刷新 URL 与访问的 URL 不匹配（协议、路径、参数）。解决方法：使用完全一致的 URL 重新提交。

R2：目录刷新（过期模式）+ 源站返回 304

目录刷新使用“过期”模式。CDN 向源站验证；源站返回 304（未变化），CDN 因此保留旧缓存。解决方法：使用“强制删除”模式，或由源站更新 Last-Modified/ETag。请参阅 references/cache-rules.md。

R3：源站的无缓存策略导致预热失败

源站返回 no-cache / no-store / private / 非 200 状态码 / Set-Cookie。CDN 遵循源站策略，不缓存内容。解决方法：调整源站的 Cache-Control，或使用 CDN 控制台覆盖设置。请参阅 references/cache-rules.md。

R4：没有任务记录

用户称已完成刷新/预热，但找不到记录。解决方法：确认域名/URL 和操作入口。

R5：任务执行失败

任务状态为 Failed。解决方法：检查 URL 格式、域名配置、HTTPS 证书和源站可达性。

R6：节点缓存未同步（兜底）

任务状态为 Complete，源站正常，但特定节点仍返回旧内容。解决方法：等待后重试，或绑定特定节点 IP 以定位异常节点。需要升级至 PE 处理。

限制

• 只读操作：只查询任务记录并执行诊断；绝不提交刷新/预热操作。
• 解决方案必须有证据支撑：只能基于已验证的产品功能或官方文档。
• 参考资料：references/cache-rules.md，了解 CDN 缓存优先级规则和状态码缓存行为。

可用脚本

脚本	用途
scripts/cdn_refresh_preload.py	查询刷新/预热任务记录，验证缓存命中状态
scripts/cdn_probe.py	在本地执行诊断命令（curl/dig/openssl）
scripts/sts_token.py	验证调用方身份，并通过默认凭证链获取 UID

本地探测

所有外部探测命令均通过 cdn_probe.py 在本地执行。所有探测命令（dig/curl/openssl）都必须通过 scripts/cdn_probe.py 执行，切勿直接在 shell 中运行 dig 或 curl。

cd $SKILL_DIR && python3 scripts/cdn_probe.py '<command>'

标准探测：DNS（dig）、HTTPS（curl -ksI）、SSL 证书（openssl）、直接源站测试（curl -ksI -H "Host: <CDN domain>"）。有关结果路由，请参阅 references/probe-result-routing.md。

错误处理

错误	原因	解决方法
未找到凭证	未配置默认凭证链	配置 aliyun CLI 默认凭证链（运行 aliyun configure）
身份验证失败（sts get-caller-identity）	沙盒凭证缺失或无效	检查运行时凭证配置；默认凭证链正常工作时无需额外授权
API 错误（Forbidden / InvalidParameter / Throttling / InternalError）	OpenAPI 在查询时返回错误	记录错误，跳过受影响的查询，继续执行其余诊断步骤，并仍然输出报告
API 返回空任务列表	回溯时间范围内没有刷新/预热任务	延长 --days 或验证域名/URL
探测命令超时	网络不可达或命令挂起	重试或检查本地网络连接

如果打包脚本反复出现 API 错误，请通过直接调用 aliyun cdn describe-refresh-tasks CLI 进行验证，以区分服务端故障和脚本问题。