先建立排错的前提理解并发验证模型DNS劫持检测API并不是单点查询而是把同一域名同时发给 AliDNS、DNSPod、360 和 Cloudflare 四家 DoH 服务器再对返回结果做交叉比对。因此这个接口的“错误”并不都是传统意义上的 HTTP 错误更多时候你需要学会解读响应里各家服务器的 status 字段以及 summary 中不同风险等级的判读逻辑。只有先理解这个并发验证模型才能知道为什么会出现 timeout、为什么两家结果不一致、为什么 IP 有差异却不代表劫持。接入前明确能力边界在开始排错之前先确认 API 的适用范围支持输入domain、https://domain、domain:port、domain/path 四种形式接口会自动剥离协议头、端口与路径只保留主机名部分。查询类型同时查询 AIPv4与 AAAAIPv6记录并提取 CNAME 链。返回内容每台服务器的 IP 列表、CNAME 链如有、TTL 最小值、单台服务器响应延迟。QPS 限制5 次每秒。超过限制会出现限流错误具体错误码与 HTTP 状态码以文档为准。区域差异Cloudflare 属于境外节点在中国大陆服务器侧可能超时接口会将这种超时标记为 timeout而不会让整个请求失败。需要特别注意的是同一域名在不同区域、不同运营商的 DNS 解析结果本身就可能不同。不要把“结果不一致”直接等同于“被劫持”。请求参数与鉴权核心查询参数只有一个参数位置类型必填说明domainquerystring是待检测域名最长 253 字符自动剥离协议头与路径X-API-Keyheaderstring否不传时走匿名额度生产环境建议传入domain 参数的最大长度是 253 个字符对应 DNS 域名的理论最大长度。如果传入带协议的地址接口也会自动剥离不必在客户端做二次处理。可运行示例使用 curl 直接请求curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/dns-check?domainbaidu.com匿名调用方式不传 X-API-Keycurl -sS \ https://v1.apizero.cn/api/dns-check?domainwww.taobao.com如果需要快速观察风险结论可以配合 jq 只看 summary 块curl -sS https://v1.apizero.cn/api/dns-check?domaintaobao.com | jq .data.summary返回结构速读data 对象包含以下核心字段字段说明domain实际查询的域名input你传入的原始字符串exec_ms整个查询总耗时毫秒servers4 家 DoH 服务器的独立结果summary综合判读结果unique_ipv4 / unique_ipv6所有服务器返回 IP 的去重列表在 servers 数组里每台服务器有四个关键字段statusok / timeout。ok 表示拿到解析结果timeout 表示该服务器未在超时时间内返回。error失败时的具体错误信息成功时为空。latency_ms单台服务器响应耗时。ttl_min该服务器返回的 TTL 最小值。在 summary 里risk_level 是判读结果取值包括 safe、safe_with_geodns、suspicious、hijack_likely、unknown 五档同时会给出对应的 status_text、explain 与风险评分 risk_score。success_count 与 total_count 表示获取到结果的服务数量total_count 恒为 4。常见异常现场与排错方向下面按实际排错中可能遇到的场景分类说明。现场一Cloudflare 固定 timeout其余 3 台 ok这是接口设计内的行为。Cloudflare 节点在境外从中国大陆服务器发起 DoH 查询时经常超时接口会在 status 字段标记 timeout同时把 error 写为具体的超时消息。此时只要其余 3 台结果互相验证通过summary 仍会给出 safe 或 safe_with_geodns不必把它当作故障。排错动作不要因为有一台 timeout 就触发告警。配置告警时应以 risk_level 为判断依据而不是以 success_count 是否等于 total_count 为依据。现场二success_count 小于 total_count 但 risk_level 是 safe这说明至少有一家服务器没有成功返回但其余服务器返回的 IP 或 CNAME 链相互吻合算法认为证据足以排除劫持。此时应当顺带记录是哪一台失败并关注 error 文本判断是否只是网络超时。现场三返回 safe_with_geodns这个等级的 explain 会提示检测到 GeoDNS 分流。典型表现是不同服务器返回了不同的 IP 段但这些 IP 段属于同一家 CDN 或同一运营商的不同地域池。如果 CNAME 链一致只是 IP 不同通常只是智能 DNS 的正常行为不是劫持。排错方向确认该域名是否配置了基于来源地域的解析策略比如分省或分运营商解析。确认后再决定是否需要进一步抓取本机 DNS 解析结果对比。现场四suspicious 或 hijack_likely当服务器间出现互不相关的 IP、CNAME 链断裂或指向来源不明的 IP接口会降低 risk_score 并给出对应的风险等级。此时需要通过以下手段做二次确认在本地执行 nslookup 或 dig 查看系统实际解析结果。对比 HTTP 层的证书指纹确认证书是否真的属于目标网站。检查 hosts 文件是否被写入异常条目。使用公共 DNS如 223.5.5.5重新解析同一域名与接口返回结果比对。需要说明hijack_likely 是接口基于 4 家 DoH 交叉比对给出的判断不是最终结论。拿到该结果后应继续用其他手段验证。现场五unique_ipv4_count 很小但 status 全部 ok正常情况下一个大型站点会通过 CDN 返回多个 IP。如果 4 家服务器都正常但 IP 去重后数量极少可能说明该域名未接入 CDN解析结果直接指向源站。这不属于异常可结合 CNAME 链是否为空来判断。现场六unique_ipv6_count 为 0表示所有服务器均没有返回 IPv6 地址。这通常说明该域名未配置 AAAA 记录不说明查询异常。IPv6-only 环境下的客户端访问此类域名会回退到 IPv4如果在 IPv6 网络中出现连接失败应去确认操作系统是否有 NAT64 或过渡机制而不是怀疑 API 返回了空数据。现场七HTTP 层出现 4xx 或 4294xx 通常是请求参数问题或鉴权失败domain 缺失、domain 超过 253 字符、API Key 失效等。429 表示请求频率超过了接口 QPS 限制。具体错误码与响应体中的 error 字段文本在不同场景下可能有差异以文档中的错误说明为准。排错时先打印完整响应体不要只看 HTTP 状态码。工程化排错建议设置合理的客户端超时接口在服务器侧最多等待 6000 毫秒客户端超时建议设置在 7 到 10 秒避免网络抖动被放大。重试策略遇到限流或瞬时错误时使用指数退避不要同步并发重试否则会加剧限流。告警只看风险等级把 risk_level 为 hijack_likely 或 suspicious 的响应接入告警通道单台 timeout 只做统计不做告警。记录完整上下文日志中保留 input、exec_ms、success_count、risk_score 与每台服务器的 status、latency_ms方便事后复盘。注意匿名额度不传 X-API-Key 时接口走匿名额度生产环境应传入申请到的 Key并妥善管理密钥。参考文档文档页https://apizero.cn/aidocs/dns-check原始文档https://apizero.cn/aidocs/dns-check/raw.md
先建立排错的前提理解并发验证模型DNS劫持检测API并不是单点查询而是把同一域名同时发给 AliDNS、DNSPod、360 和 Cloudflare 四家 DoH 服务器再对返回结果做交叉比对。因此这个接口的“错误”并不都是传统意义上的 HTTP 错误更多时候你需要学会解读响应里各家服务器的 status 字段以及 summary 中不同风险等级的判读逻辑。只有先理解这个并发验证模型才能知道为什么会出现 timeout、为什么两家结果不一致、为什么 IP 有差异却不代表劫持。接入前明确能力边界在开始排错之前先确认 API 的适用范围支持输入domain、https://domain、domain:port、domain/path 四种形式接口会自动剥离协议头、端口与路径只保留主机名部分。查询类型同时查询 AIPv4与 AAAAIPv6记录并提取 CNAME 链。返回内容每台服务器的 IP 列表、CNAME 链如有、TTL 最小值、单台服务器响应延迟。QPS 限制5 次每秒。超过限制会出现限流错误具体错误码与 HTTP 状态码以文档为准。区域差异Cloudflare 属于境外节点在中国大陆服务器侧可能超时接口会将这种超时标记为 timeout而不会让整个请求失败。需要特别注意的是同一域名在不同区域、不同运营商的 DNS 解析结果本身就可能不同。不要把“结果不一致”直接等同于“被劫持”。请求参数与鉴权核心查询参数只有一个参数位置类型必填说明domainquerystring是待检测域名最长 253 字符自动剥离协议头与路径X-API-Keyheaderstring否不传时走匿名额度生产环境建议传入domain 参数的最大长度是 253 个字符对应 DNS 域名的理论最大长度。如果传入带协议的地址接口也会自动剥离不必在客户端做二次处理。可运行示例使用 curl 直接请求curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/dns-check?domainbaidu.com匿名调用方式不传 X-API-Keycurl -sS \ https://v1.apizero.cn/api/dns-check?domainwww.taobao.com如果需要快速观察风险结论可以配合 jq 只看 summary 块curl -sS https://v1.apizero.cn/api/dns-check?domaintaobao.com | jq .data.summary返回结构速读data 对象包含以下核心字段字段说明domain实际查询的域名input你传入的原始字符串exec_ms整个查询总耗时毫秒servers4 家 DoH 服务器的独立结果summary综合判读结果unique_ipv4 / unique_ipv6所有服务器返回 IP 的去重列表在 servers 数组里每台服务器有四个关键字段statusok / timeout。ok 表示拿到解析结果timeout 表示该服务器未在超时时间内返回。error失败时的具体错误信息成功时为空。latency_ms单台服务器响应耗时。ttl_min该服务器返回的 TTL 最小值。在 summary 里risk_level 是判读结果取值包括 safe、safe_with_geodns、suspicious、hijack_likely、unknown 五档同时会给出对应的 status_text、explain 与风险评分 risk_score。success_count 与 total_count 表示获取到结果的服务数量total_count 恒为 4。常见异常现场与排错方向下面按实际排错中可能遇到的场景分类说明。现场一Cloudflare 固定 timeout其余 3 台 ok这是接口设计内的行为。Cloudflare 节点在境外从中国大陆服务器发起 DoH 查询时经常超时接口会在 status 字段标记 timeout同时把 error 写为具体的超时消息。此时只要其余 3 台结果互相验证通过summary 仍会给出 safe 或 safe_with_geodns不必把它当作故障。排错动作不要因为有一台 timeout 就触发告警。配置告警时应以 risk_level 为判断依据而不是以 success_count 是否等于 total_count 为依据。现场二success_count 小于 total_count 但 risk_level 是 safe这说明至少有一家服务器没有成功返回但其余服务器返回的 IP 或 CNAME 链相互吻合算法认为证据足以排除劫持。此时应当顺带记录是哪一台失败并关注 error 文本判断是否只是网络超时。现场三返回 safe_with_geodns这个等级的 explain 会提示检测到 GeoDNS 分流。典型表现是不同服务器返回了不同的 IP 段但这些 IP 段属于同一家 CDN 或同一运营商的不同地域池。如果 CNAME 链一致只是 IP 不同通常只是智能 DNS 的正常行为不是劫持。排错方向确认该域名是否配置了基于来源地域的解析策略比如分省或分运营商解析。确认后再决定是否需要进一步抓取本机 DNS 解析结果对比。现场四suspicious 或 hijack_likely当服务器间出现互不相关的 IP、CNAME 链断裂或指向来源不明的 IP接口会降低 risk_score 并给出对应的风险等级。此时需要通过以下手段做二次确认在本地执行 nslookup 或 dig 查看系统实际解析结果。对比 HTTP 层的证书指纹确认证书是否真的属于目标网站。检查 hosts 文件是否被写入异常条目。使用公共 DNS如 223.5.5.5重新解析同一域名与接口返回结果比对。需要说明hijack_likely 是接口基于 4 家 DoH 交叉比对给出的判断不是最终结论。拿到该结果后应继续用其他手段验证。现场五unique_ipv4_count 很小但 status 全部 ok正常情况下一个大型站点会通过 CDN 返回多个 IP。如果 4 家服务器都正常但 IP 去重后数量极少可能说明该域名未接入 CDN解析结果直接指向源站。这不属于异常可结合 CNAME 链是否为空来判断。现场六unique_ipv6_count 为 0表示所有服务器均没有返回 IPv6 地址。这通常说明该域名未配置 AAAA 记录不说明查询异常。IPv6-only 环境下的客户端访问此类域名会回退到 IPv4如果在 IPv6 网络中出现连接失败应去确认操作系统是否有 NAT64 或过渡机制而不是怀疑 API 返回了空数据。现场七HTTP 层出现 4xx 或 4294xx 通常是请求参数问题或鉴权失败domain 缺失、domain 超过 253 字符、API Key 失效等。429 表示请求频率超过了接口 QPS 限制。具体错误码与响应体中的 error 字段文本在不同场景下可能有差异以文档中的错误说明为准。排错时先打印完整响应体不要只看 HTTP 状态码。工程化排错建议设置合理的客户端超时接口在服务器侧最多等待 6000 毫秒客户端超时建议设置在 7 到 10 秒避免网络抖动被放大。重试策略遇到限流或瞬时错误时使用指数退避不要同步并发重试否则会加剧限流。告警只看风险等级把 risk_level 为 hijack_likely 或 suspicious 的响应接入告警通道单台 timeout 只做统计不做告警。记录完整上下文日志中保留 input、exec_ms、success_count、risk_score 与每台服务器的 status、latency_ms方便事后复盘。注意匿名额度不传 X-API-Key 时接口走匿名额度生产环境应传入申请到的 Key并妥善管理密钥。参考文档文档页https://apizero.cn/aidocs/dns-check原始文档https://apizero.cn/aidocs/dns-check/raw.md
)
