外观
Runtime
源码 packages/dn42_schemas/dn42_schemas/runtime.py。描述节点上要跑哪些容器、在什么网络里、怎么构建。
RouterRuntimeSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
project_name | str | None | 否 | runtime 项目名；None 时由节点名推导。须匹配 [a-z0-9][a-z0-9_-]* |
underlay | UnderlayNetworkSpec | 是 | underlay 网络定义 |
rpki | RpkiSpec | 否（默认值） | RPKI cache 参数 |
router_dockerfile | RouterDockerfileSpec | 否（默认值） | 路由器镜像构建模板参数 |
wireguard_port_range | WireGuardPortRangeSpec | None | 否 | 对外对等的 WG UDP 端口段；设置后驱动端口发布注入 |
wireguard_internal_port_range | WireGuardPortRangeSpec | None | 否 | 节点间内部链路的 WG UDP 端口段。可空表示未启用分段，全部端口按外部段口径处理（向后兼容）。两段都会被 normalize 钩子注入发布 |
services | list[RuntimeServiceSpec] | 是 | runtime 服务列表 |
RuntimeServiceSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | str | 是 | 服务名；同一 deployment 内唯一 |
role | ServiceRole | 是 | 服务语义角色；决定必需挂载与默认 IP 推导 |
image | str | None | 否 | 直接使用的镜像名；与 build 互斥 |
build | BuildSpec | None | 否 | 构建参数；与 image 互斥 |
ipv4_address | str | None | 否 | underlay 中的显式 IPv4。用 network_mode 时不得设置 |
command | list[str] | 否（默认 []） | 启动命令；wg-gateway 与 bird-router 角色必填 |
environment | dict[str, str] | 否（默认 {}） | 环境变量 |
ports | list[PortPublishSpec] | 否（默认 []） | 发布端口。用 network_mode 时不得发布端口 |
network_mode | str | None | 否 | 网络模式，如 service:<name>；service: 的目标须存在 |
cap_add | list[str] | 否（默认 []） | 额外 Linux capability；未设时按角色默认回落 |
devices | list[str] | 否（默认 []） | 透传设备 |
sysctls | dict[str, str] | 否（默认 {}） | 创建时应用的 sysctl；未设时按角色默认回落 |
volumes | list[VolumeMount] | 否（默认 []） | 挂载卷；部分角色有必需的挂载目标 |
depends_on | list[str] | 否（默认 []） | 启动依赖；目标须存在 |
healthcheck | HealthCheckSpec | None | 否 | 健康检查；未设时部分角色有默认 |
enabled | bool | 否（默认 True） | 是否参与最终渲染 |
ServiceRole 取值：router-netns / wg-gateway / bird-router / rpki-cache / dns / debug-shell。
服务级校验
RouterRuntimeSpec.validate_services：
- 服务名唯一。
- enabled 服务必须覆盖三个必需角色：
router-netns、wg-gateway、bird-router。 depends_on与network_mode service:<name>引用的服务都须存在。- 用
network_mode的服务不得同时设ipv4_address，也不得发布端口。 - 角色必需挂载：
wg-gateway须挂/opt/dn42/scripts与/etc/wireguard；bird-router须挂/opt/dn42/scripts与/etc/bird；不共享 netns 的dns角色须发布 53/udp 与 53/tcp。 - 服务 IPv4 须落在 underlay 子网内，不得等于 underlay 网关，且不得与其它服务重复。
- 发布端口（含范围）在同一
(host_ip, host_port, protocol)上不得冲突。
单个服务的校验：image 与 build 不可同设；wg-gateway 与 bird-router 必须有 command。
VolumeMount
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
source | str | 是 | 宿主路径、命名卷或相对来源 |
target | str | 是 | 容器内挂载目标 |
readonly | bool | 否（默认 True） | 是否只读 |
HealthCheckSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
test | list[str] | 是 | 健康检查命令数组 |
interval_seconds | int（ge=1） | 否（默认 15） | 检查间隔 |
timeout_seconds | int（ge=1） | 否（默认 5） | 单次超时 |
retries | int（ge=1） | 否（默认 5） | 连续失败次数阈值 |
start_period_seconds | int（ge=0） | 否（默认 10） | 启动宽限期 |
BuildSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
target | str | None | 否 | 多阶段构建的 target 名 |
args | dict[str, str] | 否（默认 {}） | build args |
Dockerfile 内容由 runtime.router_dockerfile 在 agent 内生成，并经 Docker Engine API 内存构建——没有构建上下文目录，也没有落盘的 Dockerfile。
PortPublishSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
container_port | int（ge=1, le=65535） | 是 | 容器端口 |
container_port_end | int | None | 否 | 容器端口范围末端；须 ≥ container_port |
host_port | int | None | 否 | 宿主端口；None 表示仅声明容器端口 |
host_port_end | int | None | 否 | 宿主端口范围末端；须先有 host_port |
protocol | str | 否（默认 "tcp"） | 限 tcp / udp / sctp，归一化为小写 |
host_ip | str | None | 否 | 绑定的宿主地址 |
validate_ranges：只给 host_port 与 container_port_end 时自动补算 host_port_end；宿主与容器端口范围的大小须一致；host_port_end 须 ≤65535 且 ≥ host_port。
WireGuardPortRangeSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
start | int（ge=1, le=65535） | 是 | 容器侧端口范围起点 |
end | int（ge=1, le=65535） | 是 | 容器侧端口范围终点；须 ≥ start |
host_start | int | None | 否 | 宿主侧起始端口；推导出的宿主末端不得 >65535 |
host_ip | str | None | 否 | 绑定的宿主地址 |
派生属性：effective_host_start（= host_start or start）、effective_host_end、contains(port)。
两段的实际值由 materializer 从 port_pools 表派生（external / internal 两个 scope），见 fleet 供给收权。
⚠️
wireguard_internal_port_range是较晚加入的 runtime 字段：StrictModel的extra="forbid"会让不认识它的旧版 agent 整份拒收 DesiredState。启用分段前必须先把 agent 升到认识该字段的版本，见 锁步契约。
UnderlayNetworkSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | str | 否（默认 "router_underlay"） | underlay 网络名 |
subnet | str | 是 | underlay IPv4 子网 CIDR |
gateway | str | 是 | underlay IPv4 网关 |
ipv6_subnet | str | None | 否 | underlay IPv6 ULA 子网；设置后启用 IPv6（NAT66 出网） |
ipv6_gateway | str | None | 否 | underlay IPv6 网关；设 ipv6_subnet 时必填 |
ipv6_subnet 纳入容器 config_hash，改动会触发声明式重建。
RpkiSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
enabled | bool | 否（默认 True） | 是否启用 RPKI cache |
cache_url | str | 否（默认 dn42 ROA JSON 源） | 上游 RPKI JSON 源 |
listen_host | str | 否（默认 "10.254.42.3"） | underlay 内监听地址 |
listen_port | int（ge=1, le=65535） | 否（默认 8282） | 监听端口 |
RouterDockerfileSpec
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
base_image | str | 否（默认 "debian:13-slim"） | 路由器镜像的基础镜像 |
debian_mirror | str | 否（默认 "deb.debian.org"） | Debian 包源镜像 |