给 API 配置新域名后浏览器能打开首页并不代表程序已经可以向这个地址发送密钥。排查“新域名不能调用”时先把 DNS、TCP、TLS、HTTP 路由和凭证权限分开才容易判断问题发生在哪一层。本文给出一个只使用 Python 标准库的探测程序解析主机名连接 443 端口按正常信任配置验证 TLS然后关闭连接。程序不发送 HTTP 请求也没有 API Key 输入参数。本文由 Ace Data Cloud 团队整理。域名配置示例参考当前公开指南探测方法适用于你有权检查的 HTTPS 主机名。1. 先确认程序实际应该访问哪个主机名验收记录里至少写清两个地址的用途portal.example.com客户查看文档、管理账号的网站地址。api.example.com程序按接口文档发送请求的 API 主机名。这里使用的是保留示例域名请替换成实际配置。两个地址可以承担不同职责网页可访问只能证明网页这条路径的部分环节正常。在 Ace Data Cloud 的域名配置中页面域名和 API 域名有各自的 CNAME 目标应从当前控制台的对应配置项复制。变更已有 DNS 记录前还要确认原记录是否被其他业务使用。DNS 解析和 HTTPS 就绪需要分别验收。具体配置步骤见当前域名指南。下面只检查客户端观察到的 DNS 和 TLS不替代控制台状态检查。2. 用 Python 做不带密钥的 DNS/TLS 探测保存为api_hostname_preflight.py。输入必须是裸主机名不能包含协议、端口、路径、查询参数或凭证。import argparse import json import socket import ssl from datetime import datetime, timezone def main(): parser argparse.ArgumentParser(descriptionResolve a hostname and verify TLS; send no HTTP request) parser.add_argument(hostname, helpBare hostname, without scheme, port, path or credentials) args parser.parse_args() host args.hostname.rstrip(.) if not host or any(c in host for c in /:?#) or any(c.isspace() for c in host): parser.error(Pass a hostname only, not a URL, port or credential) try: host host.encode(idna).decode(ascii) except UnicodeError: parser.error(Hostname could not be converted to an ASCII DNS name) report {hostname: host, port: 443, started_at: datetime.now(timezone.utc).isoformat()} stage dns try: answers socket.getaddrinfo(host, 443, typesocket.SOCK_STREAM) report[resolved_addresses] sorted({answer[4][0] for answer in answers}) stage connect context ssl.create_default_context() with socket.create_connection((host, 443), timeout5) as connection: stage tls with context.wrap_socket(connection, server_hostnamehost) as tls: certificate tls.getpeercert() report.update(statustls_verified, connected_peertls.getpeername()[0], tls_versiontls.version(), certificate_not_aftercertificate.get(notAfter)) except ssl.SSLCertVerificationError as error: report.update(statuscertificate_rejected, stagestage, verification_codeerror.verify_code) except (OSError, ValueError) as error: report.update(statusprobe_failed, stagestage, error_typetype(error).__name__) report[checked_at] datetime.now(timezone.utc).isoformat() print(json.dumps(report, indent2)) return 0 if report[status] tls_verified else 1 if __name__ __main__: raise SystemExit(main())使用 Python 3 运行python3 api_hostname_preflight.py api.example.com脚本没有发送请求路径、Authorization、Cookie 或模型生成请求。ssl.create_default_context()使用当前 Python 运行环境的正常证书信任配置server_hostnamehost用于 TLS 的 SNI 和主机名校验。不要为了让测试通过而关闭证书验证。这里的 5 秒超时针对连接和 TLS 套接字操作。操作系统的 DNS 解析有自己的行为连接帮助函数可能依次尝试多个地址因此整个脚本不保证在 5 秒内结束。它适合一次有边界的诊断不是完整的监控系统。3. 按实际失败阶段读结果输出是 JSON包含 UTC 时间。先看status失败时再看stagetls_verified这台客户端解析了主机名并按其运行环境的信任配置接受了 TLS 连接。下一步才是检查应用路由和授权操作。certificate_rejected证书验证失败。检查访问主机名、证书有效期与证书链、客户端时钟和信任配置verification_code保留验证错误编号。probe_failed且stage为dns系统解析器未返回可用的地址信息。检查输入名称、DNS 记录和客户端使用的解析器。probe_failed且stage为connect地址解析已完成但连接准备或建立失败。检查 443 端口可达性、网络策略及客户端配置。此阶段也包含创建 TLS 上下文等连接前置操作不应一律解释成服务器拒绝连接。probe_failed且stage为tls已建立连接但 TLS 操作失败或超时。检查 TLS 配置与网络路径。这不是 API Key 验证的响应。参数报错、退出码为2输入不属于脚本支持的主机名格式。去掉协议、端口、路径或凭证后再检查不要把完整调用命令粘进参数。成功时resolved_addresses是系统解析器返回的地址connected_peer是实际选中的连接对端。socket.create_connection()可能再次解析同一个名称所以两项观察不一定完全一致。一次成功只验证了本次选中的连接不能据此宣布所有 A、AAAA 记录都正常。这也不是权威 DNS 查询更没有遍历整条 CNAME 链。解析器、代理和证书信任库都会影响本机看到的结果。有些网络会为不存在的名称合成地址最终表现为连接或 TLS 超时。保留实际观察到的阶段不要把“预计应该解析失败”写成“已经解析失败”。CNAME 是否符合当前配置要求仍需单独核对。4. TLS 通过以后再验收 HTTP 和权限有效证书不保证该主机名后面就是预期的 API 应用。因为脚本没有发送 HTTP 请求它既不能识别应用也不能判断路径、请求方法或密钥权限是否正确。确认 API 域名就绪后核对文档中的 Base URL 和请求路径。使用 Ace Data Cloud 时可以在“使用与测试”里的“查看代码”检查所选接口示例再决定是否运行。包含真实 Key 的示例应留在私有环境手工维护的文档也要单独检查不能假定旧文档里的硬编码地址会自动更新。后续如果收到 HTTP 404检查路由和路径如果收到 401保留实际错误并检查该服务的鉴权要求。已经收到 HTTP 响应是另一层的新证据不应再简单改写成“DNS 不通”。自定义 API 域名本身也不能证明凭证已经隔离。服务展示列表、凭证可用服务与操作级权限需要独立测试具体可参考API 权限验收用 Python 检查白名单配置再验证允许与拒绝。5. 给接手排障的人留下一份小记录建议把探测输出与配置来源、客户端环境一起保存。对外提供之前确认主机名和网络地址是否属于只能在私有支持渠道分享的信息。预期 API 主机名 预期地址的配置或文档来源 执行检查的客户端与网络 开始时间和结束时间UTC DNS 返回地址与实际连接对端适合分享时 TLS 结果与证书到期时间或实际失败阶段 HTTP 路由检查未执行 / 已观察到的结果 带凭证的业务操作未执行 / 已观察到的结果 仍未验证的部分不用附上整个环境变量列表也不要发送带凭证的完整命令、Cookie 或签名链接。后续若确实需要一次业务调用应使用已获授权的测试客户凭证先确认当前费用和最小操作范围再检查真实响应与用量记录。如果操作异步执行保留原任务 ID 后再判断是否重试。做到这里DNS/TLS 探测只交付它实际完成的传输层证据路由、权限和业务结果各有自己的验收记录。
