huawei-cloud-cdn-dns-resolution-diagnosis

CDN DNS 解析诊断

概述

此技能用于诊断 CDN 域名的 DNS 解析问题。它通过 hcloud CLI 查询 CDN 域名详情以获取预期的 CNAME，通过 scripts/dns_resolve.py（dnspython）探测域名的实际 DNS 解析结果并收集 IP 列表，再通过 ShowIpInfo/v2 验证 IP 归属，以确定域名是否已正确解析到华为云 CDN，帮助用户找出 DNS 配置异常、解析未生效、误报等问题的根本原因。

主要功能：

• 域名权限验证和 CNAME 获取（ShowDomainDetailByName）
• DNS 解析探测并获取 IP 列表（python scripts/dns_resolve.py，JSON 输出中 {result, data, error_msg} 包含 data.resolved_ips）
• IP 归属检查（ShowIpInfo/v2，最多 20 个 IP）
• 误报识别（对于部分解析场景，提示进行多地域探测）
• 生成结构化诊断报告并提供修复建议

工具：hcloud CLI（KooCLI）+ python scripts/dns_resolve.py（dnspython >= 2.1） 探测超时：10 秒（通过 dns_resolve.py --timeout 10 强制执行） IP 查询上限：20 个 IP 核心原则：只读诊断，不更改配置

适用范围

适用范围内：此技能仅用于诊断 CDN 域名的 DNS 解析 问题，包括：

• 验证域名是否属于当前账号，并获取预期的 CNAME（ShowDomainDetailByName）
• 探测域名实际的 A 记录解析结果（python scripts/dns_resolve.py，dnspython）
• 验证解析出的 IP 是否属于华为云 CDN（ShowIpInfo/v2，每次调用最多 20 个 IP）
• 检测“部分解析 / 误报”场景，并生成包含修复建议的结构化诊断报告

适用范围外：

• ❌ 不执行写入 / 修改 / 删除操作（此技能为只读；请参阅 ⛔ Prohibited Operations 中的 55 项禁止操作）
• ❌ 不更改 DNS 记录或 CDN 配置，不刷新 / 预热缓存
• ❌ 不诊断其他问题：HTTPS 证书、回源失败、域名归属验证（请通过“相关技能”部分转交）
• ❌ 不处理需要更改配置的请求（拒绝执行，并引导用户使用控制台或手动运行 hcloud CLI）

适用场景：

• DNS 解析失败 / CNAME 未生效 / 解析超时
• 域名解析到非华为云 IP / 解析结果与预期的 CNAME 不一致
• DNS 配置异常排查、误报调查（部分地域切换）

触发条件

触发短语：“DNS解析诊断”“DNS异常”“域名解析失败”“CDN解析异常”“DNS配置”“DNS diagnosis”“resolution diagnosis”“CDN 域名解析”“DNS resolution issue”。

用户表述示例——用户提出以下类似请求时，请使用此技能：

1. “帮我看看 www.example.com 为什么解析不到华为云 CDN”（为什么 www.example.com 没有解析到华为云 CDN？）
2. “CNAME 配置了但没生效，域名还是没解析到 CDN”（已配置 CNAME，但没有生效；域名仍未解析到 CDN）
3. “DNS 解析超时了，怎么排查”（DNS 解析超时了；该如何排查？）
4. “解析出来的 IP 不是华为云的，是什么问题”（解析出的 IP 不属于华为云；是什么问题？）
5. “这个域名 DNS 解析异常，帮我诊断一下”（这个域名的 DNS 解析异常；请帮我诊断）

如果用户的请求属于近似场景（证书 / 回源 / 归属 / 配置变更），请转交给相应技能或拒绝处理——请参阅近似场景 / 请勿使用。

易混淆场景 / 不要使用

请勿在以下场景中使用此技能；请按所示方式处理：

用户请求	正确处理方式
HTTPS 证书错误／证书过期或无效／HTTPS 访问失败（DNS 解析正常）	转交给 huawei-cloud-cdn-certificate-diagnosis
页面返回 502/504／源站拉取失败（已解析到 Huawei Cloud CDN）	转交给 huawei-cloud-cdn-origin-diagnosis
域名无法添加到 CDN／无法接入 CDN／所有权验证失败	转交给 huawei-cloud-cdn-domain-ownership-verification
用户要求修改 CDN 配置、删除域名、刷新／预热缓存或执行任何其他写入操作	拒绝（此技能为只读）并引导用户前往 CDN 控制台或手动使用 hcloud CLI
用户要求修改 DNS 记录（CNAME/A 记录）	拒绝并引导用户前往 DNS 服务控制台

关于与其他技能进行多方向诊断，请参阅相关技能；三个相关技能彼此独立且均为只读，并可按任意顺序 链式调用。

⛔ 禁止的操作（安全约束）

无论用户提出何种请求，此技能都严格禁止执行所有非 GET（写入／修改／删除）CDN 操作。

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

如需查看全部 55 项禁止的非 GET 操作及其风险说明，请参阅 references/prohibited-operations.md。

部分禁止操作（完整列表请参阅参考文档）：

禁止的操作	API/命令	原因
❌ 创建域名	CreateDomain (v1/v2)、CreateDomainByDuplicate	写入操作；会创建生产资源
❌ 删除域名	DeleteDomain (v1/v2)	不可撤销；会从 CDN 中移除域名
❌ 修改域名配置	UpdateDomainFullConfig (v1/v2)、UpdateDomainOrigin、UpdateCacheRules 等	写入操作；可能影响生产流量
❌ 启用／禁用域名	EnableDomain (v1/v2)、DisableDomain (v1/v2)	会影响生产流量
❌ 修改计费模式	SetChargeModes	会产生财务影响；需要明确授权
❌ 创建刷新／预热任务	CreateRefreshTasks (v1/v2)、CreatePreheatingTasks (v1/v2)	写入操作；会影响边缘缓存
❌ 修改 DNS 配置	任何 DNS 写入操作（例如 nsupdate）	写入操作；可能影响全球解析

如果用户请求执行禁止的操作，你必须拒绝并告知： “根据安全约束，此技能不允许执行写入／删除／修改操作。此技能仅用于 DNS 解析诊断。请使用 Huawei Cloud CDN 控制台、DNS 服务 控制台，或手动运行 hcloud CLI 进行配置更改。全部 55 项禁止操作均已记录在 references/prohibited-operations.md 中。”

架构

CDN DNS Resolution Diagnosis
├── hcloud configure list              (Credential validation)
├── ShowDomainDetailByName             (Domain permission validation + obtain CNAME)
├── python scripts/dns_resolve.py      (DNS resolution probe, JSON output)
│      --domain <domain_name>
│      [--timeout 10]
│   ├── data.resolved_ips non-empty     → Continue to Step 3
│   └── data.resolved_ips empty / error → Not resolved, generate report
├── ShowIpInfo/v2 --ips=<IP1,IP2>      (IP attribution check, up to 20 IPs)
│   ├── All belongs=true               → Resolved to Huawei Cloud
│   ├── All belongs=false              → Not resolved to Huawei Cloud
│   └── Mixed belongs                  → Partial resolution + false positive prompt
└── Generate diagnosis report

API 调用预算

步骤	API/命令	速率限制	预计耗时
1	hcloud configure list	—	<1s
2	ShowDomainDetailByName	—	<2s
3	python scripts/dns_resolve.py	—	≤10s
4	ShowIpInfo/v2	—	<2s

预计总耗时：< 15 秒

KooCLI 命令格式规范

所有 hcloud CDN 命令均遵循以下格式规范：

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

格式规则：

• 服务名称：CDN（大写）
• 操作名称：PascalCase（例如 ShowDomainDetailByName、ShowIpInfo/v2）
• 区域参数：--cli-region=<region>（建议使用，CDN 请使用 cn-north-1）
• 参数格式：--key=value（使用等号，不留空格）

示例：

# Correct
hcloud CDN ShowDomainDetailByName --cli-region=<region> --domain_name=www.example.com

# Incorrect (space-separated)
hcloud CDN ShowDomainDetailByName --cli-region <region>

前置条件

前置条件检查：需要 Huawei Cloud CLI（hcloud / KooCLI）>= 3.2.0 运行 hcloud version 验证版本。如果尚未安装或版本过低， 请参阅 references/cli-installation-guide.md。

hcloud version

前置条件检查：需要 Python >= 3.8 和 dnspython >= 2.1 DNS 解析探测通过 python scripts/dns_resolve.py 运行，依赖 dnspython 库（>= 2.1）。如果导入失败，探测将以代码 2 退出，并输出 data.error.reason = "missing_library" JSON。使用 pip install dnspython>=2.1 安装。 请参阅 references/cli-installation-guide.md。

python -c "import dns.resolver; print('dnspython ok')"

前置条件检查：已配置 hcloud 凭证

执行 CDN 操作前，必须验证 hcloud 凭证已配置：

hcloud configure list

如果没有有效凭证，请停止操作并指导用户配置凭证。

⚠️ hcloud 参数格式要求

hcloud（KooCLI）的所有参数都必须使用 --param=value 格式（以等号连接）；不支持以空格分隔的格式。

✅ 正确：hcloud CDN ShowDomainDetailByName --cli-region=<region>

❌ 错误：hcloud CDN ShowDomainDetailByName --cli-region <region>

⚠️ CDN API 区域要求

CDN API 仅支持两个区域：cn-north-1（北京）和 ap-southeast-1（新加坡）。 查询结果不受区域影响（CDN 是全球服务）。 建议使用：cn-north-1。

⚠️ IP 查询限制

ShowIpInfo/v2 每次调用最多查询 20 个 IP。如果 dns_resolve.py 在 data.resolved_ips 中返回的 IP 超过 20 个，则仅取前 20 个，并在报告中注明。

---

身份验证

前置条件检查：需要 Huawei Cloud 凭证

安全规则（必须遵守）：

• 禁止读取、回显或打印 AK/SK 值

• 禁止要求用户在对话中直接输入 AK/SK

• 禁止使用 hcloud configure set 传递明文凭证值

• 禁止接受用户在对话中直接提供的 AK/SK

• 仅允许从环境变量或已配置的 CLI 配置文件中读取凭证

⚠️ 重要：处理用户提供的凭证

如果用户尝试直接提供 AK/SK（例如：“我的 AK 是 xxx，SK 是 yyy”）：

• 立即停止——不要执行任何命令

• 礼貌地拒绝，并返回以下消息：

为保障账户安全，请勿在对话中直接提供 Huawei Cloud Access Key ID 和 Access Key Secret。

配置完成后，请重试您的请求。

• 凭证配置完成前，不要继续执行任何 Huawei Cloud 操作

检查 CLI 配置：

hcloud configure list

检查输出是否包含有效配置（AK/SK、IAM 等）。

如果没有有效凭证，请在此处停止。

---

IAM 权限策略

确保 IAM 用户拥有所需权限。详情请参阅 references/iam-policies.md。

最低所需权限：

• cdn:*:query* — 此技能使用的所有 CDN 查询类操作（ListDomains/v2、ShowDomainDetailByName、ShowIpInfo/v2）
• cdn:configuration:queryDomains — 列出 CDN 域名（与通配符权限一并明确列出）

ShowIpInfo/v2（IP 归属查询）是查询类只读接口，已包含在 cdn:*:query* 权限中；无需单独的 IP 信息操作权限。

核心命令

此技能中使用的所有 hcloud CDN 命令和探测命令速查：

命令	用途	关键参数
hcloud configure list	检查凭证配置	无
hcloud CDN ShowDomainDetailByName --cli-region=<region> --domain_name=<domain>	验证域名权限并获取 CNAME	--domain_name
python scripts/dns_resolve.py --domain <domain_name> [--timeout 10]	DNS 解析探测；以 {result, data, error_msg} 封装格式输出 JSON，其中包含 data.resolved_ips、data.duration_ms、data.error	--domain（必填），--timeout（默认值为 10）
hcloud CDN ShowIpInfo/v2 --cli-region=<region> --ips=<IP1,IP2>	查询 IP 归属（最多 20 个 IP）	--ips

注意：

• 所有 hcloud 命令都应使用 --cli-region=<region>
• dns_resolve.py 通过 --timeout 10（默认值）强制设置 10 秒超时；在标准输出中返回单个 JSON 对象（以 {result, data, error_msg} 封装；业务字段位于 data 中）
• ShowIpInfo/v2 的 --ips 参数接受多个以英文逗号分隔的 IP，最多 20 个
• 如果 dns_resolve.py 在 data.resolved_ips 中返回超过 20 个 IP，只查询前 20 个，并在报告中注明

参数确认

开始诊断前，先与用户确认以下参数：

参数	必填	描述	默认值	示例
domain_name	是	要诊断的 CDN 加速域名	无	www.example.com
--cli-region	是	华为云区域	cn-north-1	cn-north-1

用户确认清单：

• 已提供目标域名
• 用户了解这是只读诊断操作
• 用户了解 dns_resolve.py 探测会强制设置 10 秒超时
• 用户了解 IP 归属查询上限为 20 个 IP

---

核心工作流

开始任何诊断步骤前，必须提供目标域名。

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

步骤 1：凭证验证和域名权限检查

检查 hcloud 凭证是否可用，并通过 ShowDomainDetailByName 验证域名是否属于当前账户，同时获取 CNAME。

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

步骤 2：DNS 解析探测

通过 python scripts/dns_resolve.py --domain <domain_name> [--timeout 10] 解析域名，并解析 JSON 封装对象 {result, data, error_msg} 中的 data.resolved_ips 字段，以获取实际 IP 列表。

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

步骤 3：IP 归属检查

通过 ShowIpInfo/v2 查询 IP 归属，以确定域名是否已解析到华为云 CDN。

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

步骤 4：生成诊断报告

汇总探测结果并生成结构化文本诊断报告。

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

步骤 5：交付报告和修复建议

向用户输出诊断报告，并根据状态提供具体的修复建议（例如配置 CNAME、等待 DNS 生效、多区域探测等）。

---

相关技能（多方向诊断）

此技能专注于 DNS 解析诊断。同一个 CDN 域名可能在其他方向也存在问题。此技能的诊断完成后，或者用户的问题涉及以下任一方向时，请参考相应技能，对其他方向进行同步诊断：

方向	相关技能	使用时机
🔒 HTTPS 证书	huawei-cloud-cdn-certificate-diagnosis	DNS 解析正常，但浏览器报告证书错误、证书过期/无效，或 HTTPS 访问失败
✅ 域名所有权验证	huawei-cloud-cdn-domain-ownership-verification	无法通过 CDN 添加/访问域名，或所有权验证失败（DNS TXT / 验证文件）
🔄 源站（回源）	huawei-cloud-cdn-origin-diagnosis	DNS 解析到华为云 CDN，但页面返回 502/504 或回源失败

使用流程：交付 DNS 诊断报告后，如果用户的问题也符合上述任一行（例如 HTTPS 访问失败、无法验证域名所有权或回源错误），请在结束诊断前调用对应方向的技能。这三项技能相互独立且均为只读；可以按任意顺序串联使用。

交叉引用说明：

• 此技能中的 dns_resolve.py 使用主机的系统 DNS 解析器，且不提供 --resolver 参数。若要针对特定解析器进行测试，请切换系统 DNS 解析器（例如 8.8.8.8 / 114.114.114.114），然后重新运行 python scripts/dns_resolve.py --domain <domain_name> --timeout 10，详见 references/task-ip-attribution.md。
• 上述技能是独立的技能包；请勿从此技能直接调用它们的内部脚本，而应调用技能本身。

---

常见问题解答（FAQ）

完整故障排查指南：references/troubleshooting.md。

问题	快速解决方案
Q1：“未配置凭据”	交互式运行 hcloud configure，或设置环境变量 HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SK，然后运行 hcloud configure list 进行验证
Q2：ShowDomainDetailByName 返回 404 / CDN.0171	该域名不属于当前账户，或尚未接入 CDN；请检查拼写和账户，或使用 hcloud CDN ListDomains/v2 --cli-region=<region> --page_size=100 列出已接入的域名
Q3：403 权限被拒绝	确认 IAM 用户具有 CDN 查询权限（cdn:*:query*，以及 cdn:configuration:queryDomains）；如需授权，请联系主账户管理员（参见 references/iam-policies.md）
Q4：dns_resolve.py 返回 dns_timeout	检查本地网络和 DNS 配置；切换系统 DNS 解析器（例如 8.8.8.8 / 114.114.114.114），然后重试 python scripts/dns_resolve.py --domain <domain> --timeout 10
Q5：missing_library（退出代码 2）	安装 dnspython：pip install dnspython>=2.1（推荐：python -m pip install dnspython>=2.1），然后重试

已知限制

• dns_resolve.py 不提供 --resolver 参数：要进行多区域/多 DNS 服务器探测，必须切换系统 DNS 解析器并重新运行（参见 troubleshooting.md）
• 仅探测 A 记录：不解析 AAAA，也不会直接查询 CNAME 链
• 每次调用 ShowIpInfo/v2 最多查询 20 个 IP；超出的 IP 会被截断，并在报告中注明
• CDN API 仅支持两个区域：cn-north-1 和 ap-southeast-1；查询结果与区域无关，建议使用 cn-north-1

错误代码速查

错误代码 / error.reason	含义	处理方式
200	成功	继续下一步
403	权限不足	中止并提示授权（见 Q3）
404 / CDN.0171	域名不属于当前账号	中止并提示确认所有权（见 Q2）
dns_nxdomain	域名不存在	报告 NXDOMAIN；检查拼写和权威 DNS
dns_no_answer	没有 A 记录	报告“没有 A 记录”；检查 A/CNAME 配置
dns_timeout	探测超时	标记为超时并返回部分结果（见 Q4）
missing_library	缺少 dnspython	中止并提示安装（见 Q5）

---

故障模式

各步骤的异常处理详情请参阅对应的任务文档；以下是完整流程中故障模式和恢复策略的摘要。

#	故障模式	检测点	恢复策略
1	未配置或已过期的凭据	步骤 1 hcloud configure list	中止；引导用户运行 hcloud configure 或配置环境变量，然后重试
2	未找到域名（404 / CDN.0171）	步骤 1 ShowDomainDetailByName	中止；提示确认域名所有权
3	权限不足（403）	步骤 1 ShowDomainDetailByName	中止；提示联系管理员授予 cdn:*:query*（+ cdn:configuration:queryDomains）
4	API 调用失败（500 / 网络错误）	步骤 1 / 步骤 3	降级处理：仅输出探测结果，并在报告中注明“API 查询失败；请手动核验 IP 归属”
5	域名未解析（data.resolved_ips 为空）	步骤 2 JSON	跳过步骤 3；报告“域名未解析”+ CNAME 修复建议
6	探测超时（dns_timeout）	步骤 2 JSON	标记为“探测超时”；返回部分结果；建议切换 DNS 解析器后重试
7	NXDOMAIN / NoAnswer	步骤 2 JSON	生成相应的结论报告；检查域名拼写和 A 记录配置
8	缺少 dnspython（missing_library，退出码 2）	步骤 2 导入自检	中止；提示安装 dnspython>=2.1
9	IP 超过 20 个	步骤 2 → 步骤 3 之前	仅查询前 20 个，并在报告中注明“实际解析到 N 个 IP；仅核验了前 20 个”
10	归属混杂（belongs=true 的 IP 仅占部分）	步骤 3 ShowIpInfo/v2	得出“部分解析 / 疑似误报”的结论；提示进行多区域核验
11	步骤 3 返回的 cdn_ips 为空	步骤 3 响应	保守得出“未解析到华为云”的结论；报告 Fail 并提示手动核验

自检：生成最终报告前，确认所有必需字段均已填写（Analysis Time / Target Domain / Expected CNAME / DNS Resolution / Diagnosis Items / Conclusion / Suggestion）；核验方法请参阅 references/verification-method.md。

---

输出格式

最终输出：结构化文本诊断报告。完整报告模板、字段映射、示例输出和示例：references/task-report-generation.md。

==================== CDN DNS Resolution Diagnosis Report ====================
Analysis Time: <ISO 8601 time>
Target Domain: <domain>
Expected CNAME: <CDN expected CNAME>

--- DNS Resolution ---
Resolved IPs: <IP1, IP2, ...>
IP Count: <count>

--- Diagnosis Items ---
[Domain Permission Check]: ✅ Pass / ❌ Fail / ⚠️ Warning
  Detail: <detail>
[DNS Resolution Probe]: ✅ Pass / ❌ Fail / ⚠️ Warning
  Detail: <detail>
  Resolved IPs: <IP list>
[IP Attribution Check]: ✅ Pass / ❌ Fail / ⚠️ Warning / N/A
  Detail: <X/Y IPs belong to Huawei Cloud CDN>

--- Conclusion ---
Status: <overall status>
Suggestion: <remediation suggestion>

必填字段：

字段	说明
Analysis Time	ISO 8601（例如，2026-08-12T10:00:00+08:00）
Target Domain	要诊断的域名（由用户输入）
Expected CNAME	第 1 步中获取的 CDN 预期 CNAME
DNS Resolution	dns_resolve.py 的 data.resolved_ips 中的 IP 列表及数量
Diagnosis Items	按步骤顺序排列的诊断项：名称 + 状态 + 详情
Conclusion / Suggestion	总体结论和具体的修复建议

状态枚举：

标记	含义	使用场景
✅ Pass	通过	探测结果符合预期
❌ Fail	失败	探测结果不符合预期
⚠️ Warning	警告	超时、结果不完整或疑似误报
N/A	不适用	未执行此步骤（例如，域名无法解析时跳过 IP 归属检查）

探测 JSON 契约（输出结构）：dns_resolve.py 会在标准输出中以 {result, data, error_msg} 信封格式输出单个 JSON 对象；业务字段位于 data.* （data.resolved_ips / data.duration_ms / data.error）。data.error.reason 枚举值：dns_nxdomain / dns_no_answer / dns_timeout / missing_library / invalid_domain / invalid_timeout / unexpected_probe_error。请参阅 references/task-dns-resolve.md。

禁止内容：报告绝不能包含 AK/SK 或任何明文凭据，不能泄露其他客户的域名，也不能包含内部 URL / API 内部信息；仅允许包含诊断结论和修复建议。

---

版本历史（更新日志）

版本	日期	变更
1.0.0	2026-08-12	初始版本：CDN 域名 DNS 解析诊断（权限检查 + DNS 探测 + IP 归属检查 + 诊断报告）

• 负责人：cdn-ops
• 版本管理政策：重大行为变更（命令、输出契约、工作流调整）会提升次版本号并记录在此处；纯文档修复会提升补丁版本号。

---

参考资料

文档	说明
task-permission-check.md	第 1 步：凭据验证和域名权限检查
task-dns-resolve.md	第 2 步：DNS 解析探测
task-ip-attribution.md	第 3 步：IP 归属检查
task-report-generation.md	第 4 步：生成诊断报告
prohibited-operations.md	全部 55 项禁止的非 GET 操作（POST/PUT/DELETE）
dataflow-diagram.md	Mermaid 数据流图
related-apis.md	API 和 CLI 命令参考
iam-policies.md	IAM 权限策略
verification-method.md	验证方法
cli-installation-guide.md	CLI 安装指南
troubleshooting.md	故障排查
acceptance-criteria.md	验收标准清单