huawei-cloud-cdn-abnormal-status-code-analysis

CDN 异常状态码分析

概述

此技能用于诊断华为云 CDN 加速域名上的异常 HTTP 状态码（4xx / 5xx）。 全程只读：所有操作都是查询（GET 统计数据 / GET 配置 / GET 日志下载链接 / 只读获取日志）。 针对任何 4xx/5xx 异常，此技能会回答四个问题：

1. 是否存在异常，规模有多大？ — 统计指定时间窗口内 4xx/5xx 的数量和占比。
2. 具体是什么状态码、何时出现、来自边缘还是源站？ — 深入查询具体状态码和时间段，并通过回源（bs_*）状态统计区分边缘生成还是源站生成。
3. 涉及哪些用户、位置和路径？ — 查询排名靠前的 IP/路径/UA/referer，以及客户端 IP 数量（刷量还是实际用户）。
4. 根因和取证情况如何？ — 缩小范围，定位到边缘配置规则或源站问题，再通过访问日志锁定具体请求。

主要功能：

• 通过一条命令（bs_status_code_*）区分边缘和源站：result={} ⇒ 边缘生成；非空 ⇒ 源站生成。
• 覆盖完整的 4xx/5xx 状态码：400/401/403/404/405/406/408/410/412/416/429/499/495/496/500/501/502/503/504/505/530….
• 只读日志辅助脚本 scripts/fetch_cdn_log.py 可下载并解压 CDN 日志，并将异常状态码对应的行提取为 JSON。
• 提供结构化诊断报告，包含状态码 → 根因决策树，以及控制台/工单修复边界（不执行 CLI 写操作）。

工具：hcloud CLI（KooCLI）+ Python 日志辅助脚本（scripts/fetch_cdn_log.py）。 核心原则：只读诊断；不修改配置。

触发条件

当用户输入符合以下任一条件时使用（用户表述层面，支持双语）：

语言	触发示例（用户表述）
中文	「CDN 域名 403 突然变多，帮我查一下」「为什么最近一直 502」「4xx/5xx 状态码异常分析」「这个问题是边缘还是回源？帮忙区分一下」「业务异常码排查」「CDN 限流/封禁排查」「状态码异常」
英文	"403 spike on my CDN domain" / "root-cause a 5xx burst" / "status code analysis" / "is this edge or origin?" / "abnormal status codes during daily inspection"

关键词触发（也列于 frontmatter description 中）：状态码异常, 业务异常码, 4xx, 5xx, 403, 404, 502, 503, 504, status code, abnormal status, CDN异常, 边缘/回源, 限流, status code analysis, edge vs origin.

相近情形 / 不要使用

以下情形不要使用此技能：

情形	应采取的措施
域名尚未接入华为云 CDN	先确认 CDN 接入情况 / 域名是否存在；非 CDN 的 HTTP 问题不在处理范围内
用户希望修改 CDN 配置 / 刷新 / 预热 / 封禁 URL / 启用或禁用域名	拒绝 — 此技能为只读；引导用户前往 CDN 控制台或手动使用 hcloud CLI（参见禁止操作）
仅分析带宽 / 流量，不关注状态码	不属于此技能的范围（没有需要解释的 4xx/5xx 异常）
用户在聊天中粘贴 AK/SK 或要求配置凭证	拒绝 — 参见身份验证；发送安全配置模板并等待
与 CDN 语义无关的非 CDN 业务异常（ECS / ELB / OBS / 应用层问题）	引导至相关服务技能

⛔ 禁止的操作（安全限制）

此技能严格禁止所有非 GET（写入／修改／删除）CDN 操作，即使用户提出请求也不例外。

总计：55 项禁止操作（24 项 POST + 25 项 PUT + 6 项 DELETE）。

完整的 55 项禁止的非 GET 操作及其风险说明，请参阅 references/prohibited-operations.md。

代表性禁止操作（完整列表见参考文档）：

禁止的操作	CLI 示例	原因
❌ 创建域名	CreateDomain (v1/v2), CreateDomainByDuplicate	写入操作，会创建生产资源
❌ 删除域名	DeleteDomain (v1/v2)	不可逆
❌ 修改域名配置	hcloud CDN UpdateDomainFullConfig / UpdateBlackWhiteList / UpdateRefer / UpdateResponseHeader / UpdateOriginHost / UpdateCacheRules / UpdateHttpsInfo	写入操作，会影响生产流量
❌ 启用／禁用域名	EnableDomain (v1/v2), DisableDomain (v1/v2)	写入操作，会影响生产流量
❌ 刷新／预热	hcloud CDN CreateRefreshTasks / CreatePreheatingTasks	写入操作，会更改缓存
❌ 修改计费模式	SetChargeModes	会产生财务影响
❌ 验证域名所有者	hcloud CDN VerifyDomainOwner	写入操作
❌ 设置统计配置／开启导出	SetStatsConfig / ExportStatsOpen	写入操作

如果用户请求执行禁止的操作，请拒绝并告知： “根据安全限制，此技能仅执行只读诊断，不会运行任何写入／删除操作。 如需更改 CDN 配置，请使用华为云 CDN 控制台或手动运行相关的 hcloud 命令——此技能不会执行这些操作。 完整的 55 项禁止操作列表记录在 references/prohibited-operations.md 中。”

架构

CDN Abnormal Status Code Analysis (read-only)
├── ListDomains/v2                       (target domain → domain_id)
├── ShowDomainStats/v2
│   ├── summary  http_code_2xx..5xx + req_num    → quantify 4xx/5xx volume + ratio
│   └── detail   status_code_4xx/5xx             → exact code + time array
├── ShowDomainStats/v2  bs_status_code_4xx/5xx    → ★ edge vs origin fork ★
├── ShowBandwidthCalc / ListDomainClientStats      → traffic-spike / 刷量 correlation
├── Top-N family                                    → who / where / what path
├── Root cause fork
│   ├── origin side: ShowOriginHost / ShowDomainDetail / ShowHistoryTasks / TopOriginUrl
│   └── edge side:   ShowDomainFullConfig / ShowRefer / ShowBlackWhiteList /
│                    ListRuleDetails / ListBanUrl / ListAccessControlTask /
│                    ShowResponseHeader / ShowCertificatesHttpsInfo
├── ShowLogs/v2 + python scripts/fetch_cdn_log.py  → per-request forensics (JSON)
├── ShowIpInfo/v2                                   → client/edge IP attribution
└── generate diagnosis report

API 调用预算

步骤	API／脚本	速率限制	预计耗时
1	hcloud CDN ListDomains/v2 --cli-region={region}	—	<2s
2	hcloud CDN ShowDomainStats/v2 --cli-region={region}（summary + detail + bs）	5/s	<3s
3	Top-N 系列 + ListDomainClientStats	2-5/s	<5s
4	hcloud CDN ShowDomainFullConfig/v2 --cli-region={region} + Show* config	—	<5s
5	hcloud CDN ShowLogs/v2 --cli-region={region} + python scripts/fetch_cdn_log.py	—	≤ 30s

预计总耗时：< 45 秒（日志较多的时间窗口可能需要更长时间）。

KooCLI 命令格式标准

hcloud CDN <Operation> --cli-region=<region> [--key=value ...]

• 服务名称：CDN（大写）。操作名称：PascalCase（例如，ShowDomainStats/v2）。
• 区域参数：--cli-region=<region>。CDN 支持 cn-north-1（北京）和 ap-southeast-1（新加坡）；结果不受区域影响。 建议统一使用：cn-north-1。（CDN 不支持 cn-north-4。）
• 参数格式：--key=value（使用等号，不加空格）。不支持以空格分隔的格式。
• 输出：追加 --cli-output=json，以便进行机器解析。

前置条件

预检查：hcloud（KooCLI）>= 3.2.0 — hcloud version。如果未安装，请参阅 references/cli-installation-guide.md。

预检查：Python >= 3.8 — python --version。scripts/fetch_cdn_log.py 需要此版本。

预检查：Python requests >= 2.25 — python -c "import requests; print('ok')"。日志辅助脚本通过 requests 下载。 如果未安装：pip install requests>=2.25

预检查：hcloud 凭据 — hcloud configure list。如果凭据无效，请停止并引导用户安全地配置。切勿读取、回显或打印 AK/SK；切勿要求用户在聊天中粘贴 AK/SK。

⚠️ hcloud 参数格式：所有参数都必须使用 --key=value。

⚠️ CDN 区域：统一使用 cn-north-1（CDN 不支持 cn-north-4）。

⚠️ 时间/区间规则：时间 = 毫秒时间戳，[start,end) 左闭右开； interval=300（≤2d，每 5 分钟一个数据点）/ 3600（≤7d，每小时一个数据点）/ 86400（≤31d，CST 0:00 数据点）。 status_code_*（边缘）和 bs_status_code_*（源站）不能在同一个查询中混用。

身份验证

• 禁止：读取、回显或打印 AK/SK；要求用户在聊天中输入 AK/SK；使用明文执行 hcloud configure set；接受用户粘贴的 AK/SK。
• 允许：仅从环境变量或当前启用的 CLI 配置文件中读取凭据。
• 如果用户粘贴 AK/SK，请停止、拒绝，并提供安全配置模板（export HUAWEICLOUD_SDK_AK=... / HUAWEICLOUD_SDK_SK=...），然后等待。
• 验证：hcloud configure list — 确认存在有效的配置文件；否则停止。

IAM 权限策略

请参阅 references/iam-policies.md。最低要求：cdn:*:query*（以及 cdn:configuration:queryDomains）和用于日志取证的 cdn:log:*。 此技能严格只读：无需或不包含创建/更新/删除/刷新/封禁权限。

核心命令

命令	用途	关键参数
hcloud configure list	检查凭据	无
hcloud CDN ListDomains/v2 --cli-region=<region>	列出域名 → domain_id	—
hcloud CDN ShowDomainStats/v2 --cli-region=<region> --action=summary|detail --domain_name=<d> --stat_type=<t> --start_time=<ms> --end_time=<ms> --interval=<s>	量化 / 定位状态码	--action、--stat_type、--interval
hcloud CDN ShowBandwidthCalc --cli-region=<region> --domain_name=<d> --calc_type=bw_peak --start_time=<ms> --end_time=<ms>	带宽峰值（与流量突增关联）	--calc_type
hcloud CDN ListDomainClientStats --cli-region=<region> --domain_name=<d> --stat_type=ip_num --start_time=<ms> --end_time=<ms>	客户端 IP 数量（刷量还是实际用户）	--stat_type=ip_num
hcloud CDN ListCdnDomainTopIps --cli-region=<region> --domain_name=<d> --stat_type=req_num --start_time=<ms> --end_time=<ms>	Top-N 深入分析（TopIps；Path/OriginUrl/Refers/Uas 用法相同；仅支持 req_num，不支持状态码）	--stat_type=req_num
hcloud CDN ShowDomainFullConfig/v2 --cli-region=<region> --domain_name=<d>	完整边缘配置（auth/refer/ip_filter/ua/…）	—
hcloud CDN ShowRefer --cli-region=<region> --domain_id=<id>	Referer 防盗链配置	--domain_id
hcloud CDN ShowBlackWhiteList --cli-region=<region> --domain_id=<id>	IP 黑名单 / 白名单	--domain_id
hcloud CDN ListRuleDetails --cli-region=<region> --domain_name=<d>	规则引擎拦截规则	—
hcloud CDN ListBanUrl --cli-region=<region> --start_time=<ms> --end_time=<ms> --page_number=1 --page_size=50	被封禁的 URL（可能需要工单白名单）	时间范围
hcloud CDN ListAccessControlTask --cli-region=<region> --start_time=<ms> --end_time=<ms> --limit=100	封禁 / 解封任务（可能需要工单白名单）	时间范围
hcloud CDN ShowOriginHost --cli-region=<region> --domain_id=<id>	回源 HOST	--domain_id
hcloud CDN ShowResponseHeader --cli-region=<region> --domain_id=<id>	响应头 / 错误页面配置	--domain_id
hcloud CDN ShowDomainDetail --cli-region=<region> --domain_id=<id>	域名详情（源站 / 状态 / CNAME）	--domain_id
hcloud CDN ShowHistoryTasks/v2 --cli-region=<region> --file_type=file --page_number=1 --page_size=50	刷新 / 预热历史记录	—
hcloud CDN ShowCertificatesHttpsInfo/v2 --cli-region=<region> --domain_name=<d>	HTTPS 证书（49x/TLS）	--domain_name
hcloud CDN ShowLogs/v2 --cli-region=<region> --domain_name=<d> --start_time=<ms> --end_time=<ms> --page_size=100	日志下载链接（单个域名，≤30 天）	--domain_name
python scripts/fetch_cdn_log.py --url <link> [--status 403,502,503,504] [--timeout 30] [--max-lines 200]	获取并解压日志，提取异常行（输出 JSON）	--url、--status
hcloud CDN ShowIpInfo/v2 --cli-region=<region> --ips=<ip1>,<ip2>	IP 归属查询（≤20 个）	--ips

Top-N 系列的 stat_type 仅支持 flux / req_num（不支持状态码）——需结合 ShowDomainStats / 日志交叉参考。

参数确认

参数	必填	说明	默认值	示例
domain_name	是	要诊断的 CDN 加速域名	—	www.example.com
domain_id	是（部分按 ID 调用的 Show* 操作需要）	来自 ListDomains/v2	—	d3aaa521…
--cli-region	是	CDN 区域	cn-north-1	cn-north-1
时间范围	是	[start,end) 毫秒时间戳，需与间隔点对齐	—	最近 7 天
--status（日志辅助工具）	否	要提取的状态码	403,404,499,500,502,503,504,530	403,502

用户确认清单：

• 已提供目标域名
• 用户了解这是只读诊断
• 用户了解日志获取超时为 30 秒

核心工作流

开始任何诊断步骤前，必须先指定目标域名。

• 如果用户未提供目标域名，请询问域名，并等待用户回复后再开始。
• 只有在用户不知道域名或要求你查询时，才通过 hcloud CDN ListDomains/v2 列出账户的域名，并请用户选择一个。
• 未经用户明确提供域名，绝不要开始诊断：不要猜测域名，不要回退到示例／默认域名，也不要自行从列表中选择域名。

步骤 1：发现与量化 — 查找 4xx/5xx、大小和流量关联

📄 详细步骤 → references/task-discovery.md

步骤 2：定位与分支 — 精确代码 + 时间 + 边缘／源站

📄 详细步骤 → references/task-localize.md

步骤 3：分布情况 — Top-N + 客户端 IP 数量

📄 详细步骤 → references/task-distribution.md

步骤 4：根因 — 根据步骤 2 的分支，排查源站侧（4A）／边缘侧（4B）

📄 详细步骤 → references/task-rootcause.md

步骤 5：单个请求取证 — 获取日志 + IP 归因

📄 详细步骤 → references/task-forensics.md

步骤 6：报告 — 决策树 + 修复范围界定

📄 详细步骤 → references/task-report.md

常见问题（问答）

详细的故障排查说明和完整的错误代码参考见 references/troubleshooting.md。

Q1：为什么 ListBanUrl / ListAccessControlTask 会返回 CDN.0004？

A：这两个查询 API 需要工单白名单；它们仍属于查询类 GET 操作。 记录错误，不要绕过限制，继续收集其他证据，并在报告中标记“通过 CLI 未确认”。

Q2：为什么 ShowDomainStats 返回空结果？

A：可能是时间窗口内没有流量、未出现该状态码，或时间戳与统计间隔未对齐 （interval=86400 要求使用 CST 0:00 时间点）。扩大时间窗口（例如 31 天），对齐时间点， 并确认域名有流量，然后重试。

Q3：可以在同一个查询中组合 status_code_* 和 bs_status_code_* 吗？

A：不可以。 边缘统计和回源统计必须通过两次独立的 ShowDomainStats/v2 调用执行。

Q4：为什么 Top-N 结果中没有状态码？

A：Top-N 系列（TopIps/Path/OriginUrl/Refers/Uas）的 stat_type 仅支持 flux/req_num，没有 状态码维度。使用 Top-N 初步筛选可疑 IP／路径，然后通过 ShowLogs / ShowDomainStats 交叉核对实际状态码。

Q5：为什么 ShowLogs 返回 logs: [] / total: 0？

A：可能是没有日志文件覆盖该时间窗口、时间窗口未采用左闭右开区间／未按小时对齐，或该域名 在该时段没有流量。将时间对齐到整小时的 CST 时间点，扩大时间窗口，并确认有流量，然后重试。

Q6：如何处理 fetch_cdn_log.py 错误？

A：参见 references/troubleshooting.md 中的错误代码表（9 个 error.reason 值： connect_timeout / connect_failed / http_error / bad_gzip / invalid_url / invalid_timeout / invalid_max_lines / invalid_status / missing_library）。软失败以 0 退出（包含 JSON error）， 参数错误／缺少库时以 2 退出。常见解决方法：增大 --timeout（≤60），重新运行 ShowLogs/v2 以 刷新已过期的链接，或运行 python -m pip install requests>=2.25。

Q7：为什么 CDN 查询会返回 403 Insufficient permission？

A：IAM 用户缺少 CDN 只读权限范围。根据 references/iam-policies.md，授予 cdn:*:query*（以及用于日志取证的 cdn:configuration:queryDomains 和 cdn:log:*）。 绝不要提升至任何写入操作权限。

已知问题和限制

限制	说明
ShowLogs/v2	仅支持单个域名；时间跨度 ≤ 30 天
Top-N stat_type	仅支持 flux/req_num；没有状态码维度（需要交叉核验）
ListDomainClientStats	ip_num 仅支持 1 天粒度（CST 0:00）；独立访客指标支持 5 分钟粒度
ListBanUrl / ListAccessControlTask	需要工单白名单（CDN.0004）；记录后继续
日志解析	fetch_cdn_log.py 解析华为云官方 14 字段日志格式；包含空格的字段（time、user_agent）会保留为一个词元 / 引用格式（官方文档）
CDN 区域	仅支持 cn-north-1 / ap-southeast-1；建议统一使用 cn-north-1；不支持 cn-north-4

错误代码速查

错误	含义	操作
CDN.0004	不在工单白名单中（ListBanUrl / ListAccessControlTask）	记录、继续，并标记为“通过 CLI 未确认”
cli-region的值不支持	CDN 不支持该区域	使用 --cli-region=cn-north-1（或 ap-southeast-1）
403 Insufficient permission	IAM 缺少 CDN 只读权限范围	授予 cdn:*:query*（+ cdn:log:*）；绝不提升权限

故障模式

详细故障排查见 references/troubleshooting.md。每个任务步骤的退出条件均为自检项。

已知故障模式和恢复策略

故障模式	症状	恢复策略（重试 / 回退 / 降级 / 报告）
区域不受支持	cli-region的值不支持，提示仅支持 cn-north-4/ru-moscow-1	切换到 --cli-region=cn-north-1（或 ap-southeast-1）
CDN.0004 白名单限制	ListBanUrl / ListAccessControlTask 返回“不在白名单中”	降级：记录为通过 CLI 未确认，继续收集其他证据，并在报告中标记；不要绕过限制
结果为空	ShowDomainStats 返回 {}	重试：扩大时间窗口（31 天），对齐到区间时间点（86400 时为 CST 0:00），确认是否有流量
边缘 / 源站混合查询	同时传入 status_code_* 和 bs_status_code_* 会报错	拆分为两次 ShowDomainStats/v2 调用
Top-N 没有状态码	Top-N 仅返回请求数	交叉核验：通过 ShowLogs / ShowDomainStats 确认实际状态码
ShowLogs 未返回链接	logs: [] / total: 0	重试：对齐到 CST 整点时间，扩大时间窗口，并确认该窗口内有流量
日志下载失败	fetch_cdn_log.py 的 error.reason 为 connect_timeout / connect_failed / http_error / bad_gzip	重试 / 刷新：增大 --timeout（≤60），重新运行 ShowLogs/v2 以刷新过期链接，并检查 gzip
权限被拒绝	查询返回 403 Insufficient permission	检查 IAM 只读权限范围（cdn:*:query* + cdn:log:*）；绝不提升权限以执行写操作

错误传播和处理协议（fetch_cdn_log.py）

• exit 0：探测完整运行结束（包括软失败——HTTP 非 200、结果为空、gzip 格式错误、超时）；会向调用方输出 JSON error.reason。
• exit 2：参数错误或缺少依赖库（requests）。
• error.reason 枚举（9 个值）：connect_timeout / connect_failed / http_error / bad_gzip / invalid_url / invalid_timeout / invalid_max_lines / invalid_status / missing_library。

输出前自检

• 报告是否包含所有必需部分（Summary / Distribution / Root Cause / Conclusion / Remediation boundary）？
• 每项结论是否都有证据（配置状态 / bs 判定 / 日志行 / 规则列表）？
• 未确认的项目（例如被 CDN.0004 阻止的项目）是否标记为“通过 CLI 未确认”？
• 报告是否避免建议由此技能执行任何写操作？（必须是）

输出格式

此技能有两个输出约定。

1. 诊断报告（纯文本）

报告模板：references/task-report.md。必需的章节和字段：

章节	必需字段
标头	分析时间（ISO8601）、目标域名、区域
摘要	异常状态码集合、异常时间窗口（CST）、数量 / 比例、边缘节点来源判定（bs_status_code_<X> 为空 → 边缘节点 / 非空 → 源站）
分布	Top IP/URL/UA/Referer、客户端判定（少数 IP 突发 / 多个真实用户，含 ip_num/req_num）、带宽峰值
根因	候选机制、证据、已排除项、无法通过 CLI 确认的事项
结论	状态（边缘节点生成 / 源站生成 / 部分生成）、建议、修复边界（仅通过 CDN 控制台或手动使用 hcloud CLI 执行写操作）

2. fetch_cdn_log.py JSON（结构化）

架构：references/related-apis.md。顶层字段：

字段	类型	说明
url	string	日志下载链接
http_status	int	下载 HTTP 状态码
byte_size	int	下载的字节数
status_filter	int[]	状态码筛选集合
rows[]	object[]	匹配的行（字段枚举：status（int 100-599）、cache_status（HIT/MISS）、time、……），包括 client_ip、url、user_agent、edge_node_ip
count	int	匹配的行数
duration_ms	int	耗时
error	object/null	null 或 {reason, message}（原因枚举——参见失败模式）

输出示例（fetch_cdn_log.py JSON 摘录）

{"status":403,"client_ip":"120.46.140.45","url":"/index.html","cache_status":"HIT","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64)","edge_node_ip":"39.136.130.12","time":"[10/Aug/2026:15:55:13 +0800]"}

输出中绝不能包含的内容

• AK/SK 和任何凭据（参见身份验证）
• 内部 / 敏感地址和客户私人信息（仅输出诊断所需的字段）
• 原始完整日志文本（仅输出提取的行字段）
• 超出证据范围的结论（未经确认的事项必须标记为“未经确认”）

参考资料

文档	说明
task-discovery.md	步骤 1：发现和量化
task-localize.md	步骤 2：定位确切代码 + 边缘节点 / 源站分流
task-distribution.md	步骤 3：Top-N / 客户端分布
task-rootcause.md	步骤 4：源站侧（4A）/ 边缘节点侧（4B）根因
task-forensics.md	步骤 5：逐请求日志取证
task-report.md	步骤 6：诊断报告 + 决策树
prohibited-operations.md	全部 55 项禁止的非 GET 操作（POST/PUT/DELETE）
dataflow-diagram.md	Mermaid 数据流图
related-apis.md	API/CLI 参考 + stat_type + 状态码映射
iam-policies.md	IAM 最小权限策略
verification-method.md	验证方法
acceptance-criteria.md	验收标准清单
troubleshooting.md	故障排查
cli-installation-guide.md	CLI 安装指南

更新日志 / 版本历史

版本	日期	维护者	变更
v1.0.0	2026-08-10	cdn-ops	首次发布：只读的 6 步诊断工作流（发现 / 定位 / 分发 / 根因分析 / 取证 / 报告）、55 项禁止操作、fetch_cdn_log.py 日志取证辅助工具、14 份参考文档

版本管理遵循 SemVer（major.minor.patch）；当前 frontmatter 中的 version: 1.0.0。每次重大变更时，都要在 表格中追加一行，并更新 frontmatter 中的 version。 维护者：cdn-ops。如果此技能依赖的 CDN 查询 API（例如 ShowLogs/v2、bs_status_code_* 统计数据）被弃用 / 停用或行为发生变化，请相应更新 references/related-apis.md 和 references/troubleshooting.md。