外观
系统概览
本文用最短的篇幅讲清楚 dn42-control-backend 是什么、解决什么问题、由哪些部分组成，并给出一份核心概念词汇表——后续文档默认读者已掌握这些词。
一句话
dn42-control-backend 是一套面向 DN42 路由节点的控制平面加节点执行器：把「一个节点应该运行什么配置」表达成 DesiredState，由 Control Server 保存与发布，由每个节点上的 Node Agent 在本机渲染、规划、部署并回报结果。
它解决什么问题
手工运维一组 DN42 节点意味着到处 ssh、改 bird.conf、拉 WireGuard 隧道、对齐 iBGP 与 OSPF、改 DNS——容易漂移、容易漏改、出事难回溯。本系统把这件事变成一个持续运转的闭环：
- 管理端通过 Admin API（或 Web 界面、provision、导入脚本）写入节点、peering、接口、BGP 会话、DNS、token 等事实数据。
- Control Server 把数据库里的事实合成（materialize）为一份完整的
DesiredState，存为递增的 generation，并通过节点私有 WebSocket 通道摇一下门铃通知对应 Agent。 - Node Agent 拉取
DesiredState，渲染本地配置文件，对比当前文件与容器状态，按需写盘、重建容器、热重载服务，并把快照、对账、应用结果回报。 - Control Server 持久化上报，推导每个节点的健康（
ok/stale/degraded/down/unknown）供管理端查询。
核心安全姿态
系统的控制模型是发布期望状态、节点本地收敛、回报观察结果——Control Server 不提供远程 shell 或任意命令执行接口。控制面能做的只有「声明期望状态」，怎么达成完全由节点本地的 Agent 基于本机观测决定。详见 安全模型。
节点 runtime 形态
每个节点的 runtime 使用共享 network namespace：router-netns 提供网络命名空间，wg-gateway 在其中建 WireGuard 隧道，bird-router 在同一网络视图里跑 BIRD 2，dns 可选跑 CoreDNS，rpki-cache 为 BIRD 提供 RPKI 与 ROA 数据。容器不用 docker-compose，由 Agent 直接通过 Docker Engine API 按 DesiredState 创建与重建。
组成部分
三个后端服务、一个节点执行器、五个共享包。前端不在本仓库。
| 组件 | 路径 | 职责 | 详见 |
|---|---|---|---|
| Control Server | apps/control-server | FastAPI 控制服务（api.natlan.io/control/v1/*）：管理面、控制台 BFF、用户面、节点面与公开 API，DesiredState 合成与发布、WebSocket 事件、注册审批、健康与路由视图 | Control Server 内部 |
| Auth Server | apps/auth-server | 认证服务（auth.natlan.io）：ASN 归属验证、Ed25519 会话 JWT 与 JWKS、OAuth 2.0 / OIDC Provider | 认证服务内部 |
| Registry Server | apps/registry-server | DN42 官方 registry 的唯一同步与落库点，仅容器网内可达 | registry-server 内部 |
| Node Agent | apps/node-agent | 节点常驻执行器：注册、拉取、渲染、规划、部署、本机收敛、采集与上报 | Node Agent 内部 |
| 前端 | 独立仓库 natlan-web | 控制台、对等门户、首页、OAuth 授权界面。经 CORS 加 Bearer 调用本仓库的 API | 授权页产物随本仓库发布，见授权页静态资产 |
dn42_schemas | packages/dn42_schemas | 跨组件传输的 Pydantic 模型（DesiredState、Agent 协议等） | 共享包 |
dn42_templates | packages/dn42_templates | 把 DesiredState 渲染为 BIRD / WireGuard / CoreDNS 与脚本 | 同上 |
dn42_runtime | packages/dn42_runtime | 渲染文件类型、写盘计划、router Dockerfile 渲染 | 同上 |
dn42_common | packages/dn42_common | 公共校验、命名、label、community、Jinja、crypto 工具 | 同上 |
dn42_registry | packages/dn42_registry | registry 副本服务的 HTTP 客户端与同步逻辑 | 同上 |
生产入口
本系统的生产实例运营 DN42 网络 NATLAN（AS4242420028），对外入口：
| 域名 | 是什么 |
|---|---|
natlan.io | 静态首页，消费公开接口展示实时网络概貌 |
console.natlan.io | 控制台（管理界面） |
peering.natlan.io | 自助对等门户 |
api.natlan.io | 控制面 API（/control/v1/*） |
auth.natlan.io | 认证服务：授权界面、OIDC 协议端点与 /api/v1/* |
challenges.natlan.io | 自托管人机验证实例 |
docs.natlan.io | 文档中心（本 docs/ 目录的静态站点发布） |
核心概念词汇表
| 术语 | 含义 |
|---|---|
| DesiredState | 「一个节点应运行什么」的完整声明式输入（schema v1）。控制面发布它、Agent 消费它。字段见 DesiredState 参考 |
| generation | DesiredState 的递增版本号。每次 materialize 产出一个新 generation 快照存进 generations 表 |
| materialize | 把数据库里的规范化事实（节点、接口、BGP、DNS…）合成为一份完整、经校验的 DesiredState 并写入新 generation 的过程 |
| provision | 用一份完整 DesiredState 整节点幂等落库并 materialize。被导入脚本与 POST /admin/provision 复用 |
| reconcile（收敛） | Agent 的一轮「拉取 → 渲染 → 观测 → 规划 → 执行 → 上报」。每轮都从最新全量状态推导出最小动作集 |
| ReconcilePlan | planner 一次性产出的唯一权威计划（文件计划 + 容器计划 + 收敛计划）；执行层照单执行 |
| 门铃（doorbell） | 守护进程里的「该 reconcile 了」信号。WebSocket 收到事件即摇门铃，多次事件合并为一次 reconcile |
| config_hash | 容器身份 = 服务 spec + underlay + 构建参数的 SHA-256（取前 16 位），写进容器 label。哈希不变就不重建容器 |
| Peering（聚合根） | 一条逻辑互联，聚合其下的 WireGuard 接口与 BGP 会话；可关联远端节点。见 节点与网络配置表 |
| internal_topology | 同一 AS 内多节点的 iBGP 与 OSPF 由 DesiredState.bird.internal_topology 合成，不是 bgp_sessions。各节点的 routers 加 hosts 必须是同一份完整集合，否则隐蔽缺路由。见 内部互联 |
| DNS 组（dns_group） | 共享的 DNS 配置单元。节点经 Node.dns_group_id 订阅一个组；多节点订阅同组即构成 anycast。见 DNS 与任播 |
| 源 / 派生 / 副本 | 地址（及其它值）的三种存在方式。设计方向是把「副本」变「派生」。见 地址模型 |
| enrollment token / agent token | 前者是一次性注册凭证，后者是节点长期持有的 Bearer token。见 安全模型 |
| 托管（escrow） | 可选的离线备份层：把库里的 WireGuard 私钥用离线恢复公钥 RSA-OAEP 封装后另存一份密文。生产当前未启用。 见 密钥托管与恢复 |
| 健康五态 | ok / stale / degraded / down / unknown，由上报状态、漂移计数、generation 差与时间阈值推导。见 Control Server 内部 |
| flap 检测 | BGP 抖动的三层检测：会话级（从快照推导）、前缀级（agent 进程内 BGP 采集会话喂送）、告警（边沿触发的历史层），衰减计分加根因区定位。见 flap 检测 |
| 处置（mitigation） | 针对 flap 的人工处置动作：拒收前缀与断开对端，声明式、可撤销、全程审计。见 抖动处置 |
| 自动对等（autopeering） | 面向其他 DN42 运营者的自助对等：门户登录后提交即落成标准 Peering 聚合。见 自动对等运维 |