域名加进云解析却不生效:NS 接管、TTL 与记录命名的三个坑

举报
yd_42677603 发表于 2026/11/15 10:54:27 2026/11/15
【摘要】 公网域名加进云解析只是第一步,状态从 PENDING_CREATE 变成 ACTIVE 需要在注册商那边改 NS;记录集 name 不带尾点会被拼成 xxx.example.com.example.com.;TTL 决定回滚成本,批量导入 DONE 之后还要核对 error_count。

把域名搬到云解析,流程看着很简单:控制台点「添加域名」,再添两条 A 记录,等一会儿就好了。可真正动手时,绝大多数人卡在同一批地方——域名加进去了,状态一直不是「正常」;记录填了,ping 还是旧 IP;批量导入几十条主机记录,接口返回成功,回头一看只进去一半。

这些现象背后是三件不同的事:域名的接管状态、解析记录的缓存时间、以及记录集名称的命名规则。用 SDK 批量做的时候,这三件事全都变成了硬约束,踩一次就要多花半小时排查。这篇按操作顺序把云解析服务(DNS)的 API 走一遍,把字段里的坑讲清楚。

环境准备

python3 -m pip install huaweicloudsdkdns
import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkdns.v2.region.dns_region import DnsRegion
from huaweicloudsdkdns.v2 import DnsClient

client = DnsClient.new_builder() \
    .with_credentials(BasicCredentials(
        os.environ["HUAWEI_AK"],
        os.environ["HUAWEI_SK"],
    )) \
    .with_region(DnsRegion.CN_NORTH_4) \
    .build()

AK/SK 用只授权 DNS 的 RAM 子账号。云解析的写操作影响面很直接——一条 A 记录改错,整站就指向别处了,别拿主账号跑脚本。

一、添加域名只是第一步,状态机才是真相

公网域名的创建接口本身没有难度:

from huaweicloudsdkdns.v2 import CreatePublicZoneRequest
from huaweicloudsdkdns.v2.model import CreatePublicZoneReq

resp = client.create_public_zone(CreatePublicZoneRequest(
    body=CreatePublicZoneReq(
        name="example.com",
        zone_type="public",          # 公网域名固定 public
        email="ops@example.com",     # 用来生成 SOA 记录里的管理员邮箱
        ttl=300,                     # SOA 记录的有效缓存时间,1~2147483647
    )
))
print(resp.id, resp.name, resp.status)

返回的 status 十有八九是 PENDING_CREATE。这不是"失败",而是"我刚把域名登记到云解析,但外网还不知道该来问我"。公网域名的状态枚举是这一组:

  • ACTIVE:正常,解析已经对外生效
  • PENDING_CREATE:创建中(还没接管)
  • PENDING_UPDATE / PENDING_DELETE:正在变更 / 删除
  • FREEZE / PENDING_FREEZE:冻结中
  • ILLEGAL / POLICE:违规冻结 / 公安冻结
  • DISABLE / PENDING_DISABLE:暂停
  • ERROR:失败

真正让域名变成 ACTIVE 的动作发生在云解析之外:去域名注册商那里,把这个域名的 NS 改成云解析分配给它的权威 DNS。分配到的地址在域名详情的记录列表里能查到,把它们抄到注册商的控制台,再回来看状态由 PENDING_CREATE 变成 ACTIVE。

所以在脚本里做巡检,第一件事不是查记录,而是查状态:

from huaweicloudsdkdns.v2 import ListPublicZonesRequest

resp = client.list_public_zones(ListPublicZonesRequest(
    type="public",
    status="PENDING_CREATE",   # 只捞没接管的
    limit=500,
))
print("待接管域名数:", resp.metadata.total_count)
for z in resp.zones:
    print(z.id, z.name, z.status, "记录数:", z.record_num)

顺带记两个分页细节:limit 的合法区间是 0~500,不是随便填;metadata.total_count 才是满足条件的总数,不受 limit/offset 影响——拿 len(resp.zones) 当总数,超过一页就会算少。

二、记录集的 name 是 FQDN,尾点决定它拼到哪里

这是云解析 API 里最反直觉的一条。创建记录集时,name 表示"主机记录或域名",而末尾有没有那个点,语义完全不同:

  • 填 www → 创建出来是 www.example.com.
  • 填 www.example.com.(带尾点)→ 创建出来是 www.example.com.
  • 填 www.example.com(不带尾点)→ 创建出来是 www.example.com.example.com.

第三条不是笔误。不带点就会被当成"域名前缀",在你当前的 zone 名后面再接一遍。接口不会报错,记录也确实创建成功了,只是它永远不会被查询到——因为它压根不是你以为的那个主机名。用 SDK 批量建记录时,这一条能让人把整个 zone 的解析全部建废,而且肉眼扫一遍记录列表还看不出问题,毕竟是合法域名。

稳妥的写法是:name 一律写完整域名并带尾点。

from huaweicloudsdkdns.v2 import CreateRecordSetWithLineRequest
from huaweicloudsdkdns.v2.model import CreateRecordSetWithLineRequestBody

client.create_record_set_with_line(CreateRecordSetWithLineRequest(
    zone_id="<zone_id>",
    body=CreateRecordSetWithLineRequestBody(
        name="www.example.com.",       # 完整域名,结尾必须有点
        type="A",
        ttl=60,
        records=["192.0.2.10"],        # 记录值按需替换,这里用文档保留地址
        line="default_view",           # 默认线路
        weight=1,
    )
))

记录类型和用途的对应关系:

类型 用途 记录值长什么样
A 域名指向 IPv4 地址 192.0.2.10
AAAA 域名指向 IPv6 地址 2001:db8::10
CNAME 域名指向另一个域名 edge.example.net.
MX 邮件服务器 邮件服务器域名
TXT 域名所有权验证、SPF 等 任意文本
CAA 指定可为域名签发证书的 CA 0 issue "example-ca.com"

关于 CNAME 有两点要提醒:

  • name 的尾点规则只管记录集名称,记录值不在这个规则里,按添加记录时的提示填目标域名就好,别把两者混成一件事;
  • 同一条主机记录上,CNAME 不能和 A/AAAA/TXT 共存。这是 DNS 协议本身的规定,不是云解析的限制——把 www 的 CNAME 换成 A,得先删 CNAME,或者干脆改成先建新的主机名再切流量。

另外,name 的长度也不是没边界的:整个 zone 的域名长度上限 254 字符,每一级标签不超过 63 字符。

三、TTL 与权重:改记录之前先把缓存放下来

ttl 是记录在各地 Local DNS 里的缓存时间,单位秒,取值范围 1~2147483647,默认 300。它决定了两件事:解析生效有多快,以及你改错了有多难收场。

切换 IP 的推荐顺序是"先降后改再升":提前一天把要动的记录 TTL 降到 60 秒,等旧 TTL 到期、缓存都刷新成短缓存,再改记录值,观察平稳后再把 TTL 调回 300 或更大。反过来——TTL 还是 3600 的时候直接改记录,然后发现改错了再改回去——中间那一小时里,各地用户会按各自的缓存时间随机落到新旧两个 IP 上,这种"一半人正常一半人 502"的现象最难解释。

修改用 update_record_set,UpdateRecordSetReq 里只有 name、type 是必填,description、ttl、records 留空表示维持原值:

from huaweicloudsdkdns.v2 import UpdateRecordSetRequest
from huaweicloudsdkdns.v2.model import UpdateRecordSetReq

client.update_record_set(UpdateRecordSetRequest(
    zone_id="<zone_id>",
    recordset_id="<recordset_id>",
    body=UpdateRecordSetReq(
        name="www.example.com.",
        type="A",
        ttl=60,
        records=["192.0.2.20"],
    ),
))

weight 是权重,范围 0~1000,公网记录集默认 1,内网记录集默认不设。只有同主机记录、同线路的多条记录之间才谈得上权重分配,单条记录设权重没有意义。还有两个限制值得记住:别名记录不支持权重;MX 记录会忽略权重字段——如果 MX 有多个值,直接写在一个记录集里即可,同主机同线路的多条 MX 记录会被自动合并成一条。

要临时停掉某条解析(比如灰度回滚),不用删记录,把状态置成 DISABLE 就行,启用时改回 ENABLE:

from huaweicloudsdkdns.v2 import BatchSetRecordSetsStatusRequest
from huaweicloudsdkdns.v2.model import BatchSetRecordSetsStatusRequestBody

client.batch_set_record_sets_status(BatchSetRecordSetsStatusRequest(
    body=BatchSetRecordSetsStatusRequestBody(
        status="DISABLE",
        recordset_ids=["<recordset_id_1>", "<recordset_id_2>"],   # 一次最多 50 个
    ),
))

四、批量导入是异步任务,别把 task_id 当成功

迁移域名的时候,几十上百条记录手敲不现实。云解析提供了批量创建接口,但它返回的 task_id 只是"任务已受理",不是"记录已创建":

from huaweicloudsdkdns.v2 import BatchCreateRecordSetsTaskRequest
from huaweicloudsdkdns.v2 import ShowBatchCreateRecordSetsTaskRequest
from huaweicloudsdkdns.v2.model import (
    BatchCreateRecordSetsTaskRequestBody,
    BatchCreateRecordSetsTaskItem,
)

task = client.batch_create_record_sets_task(BatchCreateRecordSetsTaskRequest(
    zone_id="<zone_id>",
    body=BatchCreateRecordSetsTaskRequestBody(
        recordsets=[
            BatchCreateRecordSetsTaskItem(
                name="www.example.com.",
                type="A",
                ttl=300,
                records=["192.0.2.10"],
                line="default_view",
            ),
            BatchCreateRecordSetsTaskItem(
                name="api.example.com.",
                type="A",
                ttl=60,
                records=["192.0.2.11"],
                line="default_view",
            ),
        ]
    ),
))
print("task_id:", task.task_id)

拿 task_id 轮询查询,注意这个查询接口是按 zone 维度走的(路径里只有 zone_id,不用传 task_id)。status 只有两个值:PENDING(处理中)和 DONE(已完成)——而 DONE 不代表全部成功,得看统计和错误明细:

import time

while True:
    t = client.show_batch_create_record_sets_task(
        ShowBatchCreateRecordSetsTaskRequest(zone_id="<zone_id>")
    )
    if t.status == "DONE":
        print("总数:", t.total_count, "成功:", t.success_count, "失败:", t.error_count)
        for item in t.error_items or []:
            print("失败项:", item)
        break
    time.sleep(3)

error_item_limit / error_item_offset 控制错误明细的分页,导入量大又错得多的时候,只看默认返回的前几条是不够的。

BatchCreateRecordSetsTaskItem 里的 name 规则和前面完全一致:不带尾点会被当前缀拼接到 zone 名后面。批量导入是最容易踩这条的场合,因为一条模板变量拼错的记录会在几十条里静默生效。

五、内网域名要绑 VPC,递归代理决定要不要往外问

内网域名(private zone)和公网域名的创建参数几乎一样,但 router 是必填的——域名不绑定 VPC 就没有任何意义,因为内网解析只在这个 VPC 内生效:

from huaweicloudsdkdns.v2 import CreatePrivateZoneRequest
from huaweicloudsdkdns.v2.model import CreatePrivateZoneReq, Router

client.create_private_zone(CreatePrivateZoneRequest(
    body=CreatePrivateZoneReq(
        name="internal.example.com",
        zone_type="private",
        router=Router(
            router_id="<vpc_id>",
            router_region="cn-north-4",
        ),
        proxy_pattern="AUTHORITY",
        ttl=300,
    )
))

proxy_pattern 有两个取值,选错了会出现"内网域名加上了,但某些子域名解析不出来":

  • AUTHORITY:未开启递归解析代理,只有你在本 zone 里建过的记录能被解析,其余子域名直接 NXDOMAIN;
  • RECURSIVE:开启递归解析代理,本 zone 里没有的记录会继续向外递归查询,最后落到公网解析上。

分环境用同一个域名(比如 db.internal.example.com 在测试和生产 VPC 里指向不同地址)时,就用内网域名 + 每个 VPC 绑定一份 zone;需要和公网共用其余子域时再开 RECURSIVE。另外别忘了公有云之外的机器不会走这套解析,跨 VPC 访问得先把 VPC 打通。

六、出问题时按这个顺序查

解析"不生效"是个很笼统的描述,实际排查按这个顺序走,能省掉大部分来回:

  1. 域名状态:list_public_zones 过滤 status,不是 ACTIVE 就先解决接管问题,后面全是白忙。
  2. NS 是否生效:dig NS <域名> +short,看返回的权威 DNS 是不是你在注册商那里填的那两台。这里返回的如果还是旧 DNS 厂商的服务器,说明 NS 还没改或还没同步。
  3. 直接问权威服务器:dig @<权威DNS地址> www.example.com A +short,绕过缓存。这一步能立刻区分是"记录没配对"还是"缓存没到期"。
  4. 看记录集本身:name 是不是多拼了一层 zone 名,status 是不是 DISABLE,ttl 多大。
  5. 本地缓存:nslookup / dig 结果和权威服务器不一致时,就是 TTL 还没到期,等或者换 TTL 更短的记录再来一遍。

我在控制台记录列表里见过最典型的一次误判:记录名显示成 www.example.com.example.com.,因为导入脚本把完整域名写进了 name 却没带尾点。列表里一切正常、状态 ACTIVE、没有任何报错,只是没人会去访问那个域名。

小结

云解析的 API 不长,真正需要记的是三条约束:

  • 公网域名创建完是 PENDING_CREATE,ACTIVE 的前提是注册商那边 NS 已指向云解析;
  • 记录集的 name 一律写带尾点的完整域名,否则会被当前缀再拼一次 zone 名,静默建出错误记录;
  • TTL 决定生效速度和回滚成本,切流量前先降 TTL;批量导入是异步任务,DONE 之后还要核对 error_count。

把这三条固化成脚本里的断言(创建前查状态、创建后回读 name、任务完成后比对成功数),域名迁移这种一次性的事就能做得比较踏实。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。