外观
节点与接口
源码 packages/dn42_schemas/dn42_schemas/network.py。
NodeSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
node_id | str | 是 | 节点唯一标识；通常也是模板层与 runtime 层的稳定节点名 |
site | str | 是 | 站点标识（IATA 城市码） |
region | Dn42OriginRegionCommunity | 否（默认 ASIA_EAST） | DN42 区域枚举（来自 dn42_common） |
asn | int（ge=1） | 是 | 节点 ASN |
router_id | str | 是 | BIRD router id，通常是稳定 IPv4；走 validate_ip_address |
ipv4_prefixes | list[str] | 否（默认 []） | 自有可宣告 IPv4 前缀；逐项走 validate_dn42_ipv4_network |
ipv6_prefixes | list[str] | 否（默认 []） | 自有可宣告 IPv6 前缀；逐项走 validate_dn42_ipv6_network |
loopback_ipv4 | str | None | 否 | 节点 loopback IPv4；设置则必须属于 ipv4_prefixes 之一 |
loopback_ipv6 | str | None | 否 | 节点 loopback IPv6；设置则必须属于 ipv6_prefixes 之一 |
link_local | str | None | 否 | 节点级 IPv6 link-local（fe80::/10，不带 %zone）；走 validate_ipv6_link_local_address |
link_local 是单一真相源
一节点一个本端 link-local 地址，所有外部 eBGP WireGuard 接口复用它（WG 建邻与 eBGP-over-link-local 的源地址）。
materializer 把 <link_local>/64 派生注入这些接口的 addresses，接口侧不再各存一份；渲染器再与各接口的 fe80 peer_route 配成 ip addr add fe80::X/64 peer fe80::Y 形式。
不含内部互联：iBGP 与 OSPF 的内部 WG 接口用各自的 link-local，不取本字段。
地址的源 / 派生 / 副本分类见 地址模型。
InterfaceSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | str | 是 | 接口名；校验 ≤15 字符（Linux 限制） |
kind | InterfaceKind | 是 | dummy / wireguard / underlay |
mtu | int | None（ge=576, le=9000） | 否（默认 1420） | 接口 MTU；None 交由 runtime 或脚本默认 |
addresses | list[str] | 否（默认 []） | 配置到接口的地址；逐项走 validate_ip_interface（须带前缀长度） |
peer_routes | list[str] | 否（默认 []） | 对端直连或宿主路由；逐项走 validate_ip_network |
listen_port | int | None（ge=1, le=65535） | 否 | WireGuard 监听端口 |
private_key_ref | str | None | 否 | WireGuard 私钥字面串（base64，32 字节）；kind=wireguard 时必填 |
wireguard_peer | WireGuardPeerSpec | None | 否 | WireGuard 对端；kind=wireguard 时必填，非 wireguard 时必须为 None |
private_key_ref 只接受字面私钥
字段名保留了历史后缀 _ref，但它就是私钥本身——不存在任何 xxx:// 形式的引用概念。schema 对 wireguard 接口的 private_key_ref 强制 validate_wireguard_key，URI 形态的值会被一条明确的 422 拒绝。
值由 materializer 从节点密钥表无条件注入：spec 里存什么都会被节点自己的密钥覆盖，这是密钥单一事实源的落地方式。写入侧不需要、也不应该手填这个字段。
曾经存在的
secret://占位符会让 agent 另行生成一把托管密钥，造成节点公钥分叉；该概念已彻底废除，schema 层强制拒绝。密钥模型见 fleet 供给收权。
模型级校验
validate_wireguard_fields：wireguard 接口必须同时有合法的 private_key_ref 与 wireguard_peer；非 wireguard 接口不得设 wireguard_peer。
WireGuardPeerSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
public_key | str | 是 | 对端公钥；走 validate_wireguard_key |
preshared_key_ref | str | None | 否 | 预共享密钥引用；解析方式由运行环境决定 |
endpoint | str | None | 否 | 对端端点 host:port；走 validate_wireguard_endpoint。可为域名，agent 会周期重解析 |
allowed_ips | list[str] | 否（默认 []） | peer allowed IP；逐项走 validate_ip_network |
persistent_keepalive_seconds | int | None（ge=1） | 否 | 持久保活间隔（秒） |
对端是另一个受管节点时，public_key 由 materializer 从对端 Node.wireguard_public_key 现取现填，不存 spec 副本。