DNS

源码 packages/dn42_schemas/dn42_schemas/dns.py。

DesiredState.dns 为 None 等价于不部署 DNS；enabled=False 则保留配置但不输出 Corefile。控制面侧的三级共享模型（组 → zone → 记录）如何组装成本对象，见共享 DNS。

DnsSpec

字段	类型	必填	说明
`enabled`	`bool`	否（默认 `True`）	是否部署 DNS
`bind_addresses`	`list[str]`	是	DNS 任播与服务地址的唯一真源；逐项走 `validate_ip_address`
`cache_ttl_seconds`	`int`（`ge=0`）	否（默认 `300`）	缓存 TTL
`zones`	`list[DnsZoneSpec]`	否（默认 `[]`）	本地接管的 zone
`forwards`	`list[DnsForwardSpec]`	否（默认 `[]`）	转发规则

bind_addresses 驱动 _normalize_dns_anycast 合成 dns-anycast 接口与任播前缀，见 normalize 钩子。这是全项目最干净的单一真相源实现：改一处地址，接口、内核路由、BGP 宣告全部自动跟随。

字段	类型	必填	说明
`zone`	`str`	是	zone 名。允许单 label，允许含 `/`（RFC 2317 反向委派）；走 `validate_domain_name(require_multi_label=False, allow_slash=True)`
`records_ref`	`str`	是	外部 record 集的逻辑引用（如 `zone://example.dn42`）
`primary_ns`	`str \| None`	否	SOA 主 NS FQDN；有内联 `records` 时必填
`admin_email`	`str \| None`	否	SOA 管理邮箱的 zone 写法；有内联 `records` 时必填
`soa_refresh`	`int`（`ge=0`）	否（默认 `86400`）	SOA refresh（秒）
`soa_retry`	`int`（`ge=0`）	否（默认 `7200`）	SOA retry（秒）
`soa_expire`	`int`（`ge=0`）	否（默认 `3600000`）	SOA expire（秒）
`soa_minimum`	`int`（`ge=0`）	否（默认 `3600`）	SOA minimum（秒）
`default_ttl`	`int`（`ge=0`）	否（默认 `3600`）	zone 的 `$TTL`，单条记录未给 TTL 时使用
`records`	`list[DnsRecordSpec]`	否（默认 `[]`）	内联记录；非空即触发 zone 文件渲染

模型级校验：有内联 records 时 primary_ns 与 admin_email 必须同时提供（用于构造 SOA）。

字段	类型	必填	说明
`name`	`str`	是	记录名：相对 owner、`@`（apex）或 FQDN
`type`	`str`	是	限 `A` / `AAAA` / `CNAME` / `NS` / `PTR` / `TXT` / `MX` / `SRV` / `CAA`，归一化为大写
`value`	`str`	是	rdata；语义由调用方保证
`ttl`	`int \| None`（`ge=0`）	否	单条 TTL；省略则回落 zone 的 `default_ttl`

字段	类型	必填	说明
`zone`	`str`	是	转发 zone；允许单 label
`upstreams`	`list[str]`	是	上游 resolver；逐项走 `validate_ip_address`