外观
BIRD 与路由
源码 packages/dn42_schemas/dn42_schemas/routing.py。
Bird2ConfigSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
region | Dn42OriginRegionCommunity | None | 否 | 节点 DN42 区域；None 回退到节点级 |
internal_topology | InternalTopologySpec | None | 否 | AS 内部拓扑；存在时驱动 OSPF 与 iBGP 生成 |
large_communities | BgpLargeCommunitySpec | 否（默认值） | large community 的编码与策略参数 |
dn42_ratelimit | int（ge=1） | 否（默认 15） | BIRD 默认限速参数 |
import_limit | int（ge=0） | 否（默认 8500） | 每 eBGP 对端 per-channel 的默认导入前缀上限；0 表示不限制 |
import_limit_action | ImportLimitAction | 否（默认 "block"） | 超限动作 |
disable_ebgp | bool | 否（默认 False） | 是否整体禁用 eBGP 邻居生成 |
export_ownnets | bool | 否（默认 True） | 是否默认对外宣告自有前缀 |
dummy_interfaces | dict[str, DummyInterfaceSpec] | 否（默认 {}） | BIRD 引用的 dummy 接口映射 |
stub_ifnames | list[str] | 否（默认 []） | 按 stub 处理的接口名 |
stub_ifnames_append | list[str] | 否（默认 []） | 追加到默认 stub 集的接口名 |
static_routes4 / static_routes6 | list[str] | 否（默认 []） | 静态路由表达式；首段走 validate_ip_network |
cold_potato_med | int（0..4294967295） | 否（默认 50） | 同大区 cold-potato 偏好的 MED（越低越优）。eBGP 导入时给带本节点同大区 region 社区（或无 region）的路由设此 MED，跨区域保持 100，优先就近 |
route_local_pref | list[RouteLocalPrefSpec] | 否（默认 []） | per-prefix local-pref 覆盖 |
blocked_prefixes | list[str] | 否（默认 []） | 运维拒收前缀：eBGP 导入侧精确匹配 reject，不波及其余路由。由 mitigation 端点下发与撤销，人工触发 |
ImportLimitAction = "block" / "restart" / "disable" / "warn"：
| 值 | 行为 |
|---|---|
block（默认） | 丢弃多余前缀但保住会话。防灌表与防震荡的首选——不会引发 flap |
restart | 拆会话重来 |
disable | 关会话 |
warn | 只告警 |
RouteLocalPrefSpec
对单个前缀的 local-pref 覆盖：eBGP 导入时对精确匹配该前缀的路由设 bgp_local_pref，只影响这一个前缀，不波及会话上的其余路由。仅本节点导入侧生效，经 iBGP 传播。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
prefix | str | 是 | 精确匹配的目标前缀（v4 或 v6 网络） |
local_pref | int（0..4294967295） | 是 | 命中后设置的 BGP local-pref（越大越优；eBGP 默认 100） |
这是三件路由调优工具中爆炸半径最小的一件，见 路由调优。
BgpSessionSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | str | 是 | 会话逻辑名；同节点内唯一 |
remote_asn | int（ge=1） | 是 | 对端 ASN |
neighbor | str | 是 | 对端地址；可纯 IP 或 IPv6%iface（带 zone） |
source_address | str | 是 | 本端源地址 |
address_family | AddressFamily | 是 | ipv4 / ipv6 / mp-bgp |
interface | str | None | 否 | 邻居所属接口名；link-local IPv6 邻居常需 |
policy | str | 否（默认 "dnpeers"） | 会话模板选择：dnpeers（外部 eBGP）/ internal（视为内部会话，不进 dn42_peers.conf）/ route_collector（多跳收集器喂送，无 WG 接口、import none）。见 路由策略 |
import_mode / export_mode | str | 否（默认 "filter"） | 模板的导入 / 导出模式 |
protocol_suffix | str | 否（默认 ""） | 追加到生成的 protocol 名的后缀 |
extended_next_hop | bool | 否（默认 False） | 是否启用 extended next hop（MP-BGP 承载另一地址族的前提） |
bfd | BfdSpec | None | 否（默认新建 BfdSpec） | BFD 参数；None 表示不生成 BFD |
route_reflector_client | bool | 否（默认 False） | 是否视对端为 RR client |
import_limit | int | None（ge=1） | 否 | 本会话导入上限覆盖；None 用节点级 |
import_limit_action | ImportLimitAction | None | 否 | 超限动作覆盖；None 用节点级 |
local_pref | int | None（0..4294967295） | 否 | 本会话导入路由的 local-pref 覆盖；None 用 BIRD 默认（eBGP 为 100） |
link_latency | int | None（ge=1, le=9） | 否 | 本会话 WG 链路的 DN42 延迟档（1–9 对数分档） |
enabled | bool | 否（默认 True） | 是否参与渲染 |
⚠️
local_pref整条会话生效，勿用于 transit peer——爆炸半径是该会话导入的全部前缀。按前缀精调请用Bird2ConfigSpec.route_local_pref。
link_latency 设了就在 import 与 export 时给路由打 (64511, 档) 延迟社区，沿路径取最差档。这是可见性与信令用途，本 fleet 不据此选路。
模型级校验 validate_neighbor：拆出 zone 后地址走 validate_ip_address；若 neighbor 带 zone 且同时设了 interface，两者须一致；IPv6 link-local 邻居必须给 %zone 或显式 interface。
方法 is_internal(own_asn)：remote_asn == own_asn 或 policy == "internal" 即视为内部会话。
BfdSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
enabled | bool | 否（默认 True） | 是否启用 BFD |
interval_ms | int（ge=50） | 否（默认 1000） | 控制报文间隔（毫秒） |
multiplier | int（ge=1） | 否（默认 5） | 连续丢失多少报文判失活 |
InternalTopologySpec
同一 AS 内多节点的 iBGP 与 OSPF 由这个字段合成，不是 bgp_sessions 记录。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
routers | list[str] | 是 | 参与内部路由域的路由器节点名 |
private_nodes | list[str] | 否（默认 []） | 仅内部可见的私有节点 |
hosts | dict[str, BirdHostSpec] | 是 | 节点名 → BirdHostSpec，iBGP 与 OSPF 邻居信息的主来源 |
igp_adjacencies | list[IgpAdjacencySpec] | 否（默认 []） | 显式 IGP 邻接（非全连接场景） |
full_mesh_ibgp | bool | 否（默认 True） | 是否在 routers 之间建 full-mesh iBGP |
ospf_v2 / ospf_v3 | bool | 否（默认 True） | 是否生成对应 OSPF |
模型级校验 validate_topology_hosts：routers、private_nodes、每条 igp_adjacencies.node 都必须在 hosts 里有条目。
一致性不变量：各节点的
routers+hosts必须是同一份完整集合，否则会出现隐蔽的缺路由。加节点 checklist 见 内部互联。
BirdHostSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ownip | str | 是 | 节点 loopback / iBGP 标识 IPv4 |
ownip6 | str | 是 | 节点 loopback / iBGP 标识 IPv6 |
ibgp_rr_upstreams | list[str] | 否（默认 []） | RR 拓扑下的上游 RR 节点名 |
ibgp_transport | Literal["ipv6", "ipv4"] | 否（默认 "ipv6"） | 与该节点的 iBGP 会话走哪个传输层 |
ibgp_transport 默认 ipv6，即 iBGP 走 loopback v6 互连。节点 underlay 没有 IPv6 时置 ipv4——典型场景是链路 PMTU 低于 1280，无法配置 IPv6 地址。置 ipv4 后，与该节点相关的 iBGP 会话两端都回落 v4 传输，且只保留 IPv4 通道。
因为它影响的是「与该节点的会话」，所以和 hosts 的其余字段一样，必须在所有节点的这份 hosts 里写成同一个值——一端认为走 v6、另一端认为走 v4，会话就建不起来。
IgpAdjacencySpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
node | str | 是 | 对端节点名，须在 topology 的 hosts 里 |
cost | int | None（ge=1） | 否 | IGP 开销；None 交模板默认 |
interface | str | None | 否 | 显式承载接口名 |
iface_type | str | 否（默认 "ptp"） | IGP 接口类型 |
DummyInterfaceSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ifname | str | 是 | 出现在模板中的接口名 |
track_service | bool | 否（默认 False） | True 表示承载任播或服务地址（进 direct protocol）；False 仅作 stub |
BgpLargeCommunitySpec
各整数字段范围 0..4294967295。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
origin_node_type | int | 否（默认 100） | 标记来源节点 ID 的社区类型编号 |
origin_region_type | int | 否（默认 101） | 标记来源区域的社区类型编号 |
policy_type | int | 否（默认 102） | 标记策略字段的社区类型编号 |
origin_node_id | int | None | 否 | 显式来源节点 ID；未设时由模板推导 |
policy_local_pref | int | 否（默认 10） | local-pref 语义策略值 |
policy_deprep | int | 否（默认 20） | de-prepend 语义策略值 |
rejected_asns | list[int] | 否（默认 []） | 标记为拒绝来源的 ASN；逐项须为合法 ASN |