外观
文档中心
dn42-control-backend 的全部文档都在这里，按读者要做什么分四层，遵循 Diátaxis 框架。
| 层 | 目录 | 回答的问题 | 形态 |
|---|---|---|---|
| 教程 | tutorials/ | 第一次接触，怎么从零跑起来？ | 手把手、可照做 |
| 操作手册 | guides/ | 要完成某个具体任务，步骤是什么？ | 任务导向、面向目标 |
| 参考 | reference/ | 这个接口、配置、字段、表到底是什么？ | 查得到、求精确 |
| 内部原理 | internals/ | 系统为什么这样设计、怎么运转？ | 解释、配图 |
按场景选读
| 场景 | 从这里开始 |
|---|---|
| 完全没接触过本项目 | 系统概览 → 快速上手 |
| 要把系统部署到生产 | 部署 |
| 要接入一个新节点 | 节点接入 |
| 要建立 eBGP / iBGP 互联 | 建立互联 |
| 要开放或调整自助对等 | 自动对等运维 |
| 要配 DNS 与任播 | DNS 与任播 |
| 要 renumber 地址、看寻址分配 | 寻址与 renumber |
| 要升级 agent、控制面或跑数据库迁移 | 升级与迁移 |
| 节点不健康、iBGP 缺路由、要拨测 | 健康与状态 |
| 对端或前缀在抖，要看榜、定位、处置 | 抖动处置 |
| 想理解 flap 检测怎么算 | flap 检测 |
| 要配管理员账号与登录 | 账号与登录 |
| registry 名称富化缺数据、要手动同步 | registry 副本 |
| 要调用或对接 API | API 参考 |
| 要查某个配置项或环境变量 | 配置参考 |
要查 DesiredState 字段 | DesiredState 参考 |
| 要查数据库表 | 数据层参考 |
| 要查 Redis / Valkey 里存了什么 | KV 与缓存键空间 |
| 要知道哪里慢、怎么压测 | 性能画像 |
| 要知道库有多大、写热点在哪 | 数据层性能与容量 |
| 想理解系统怎么运转 | 架构 |
| 要改代码、写测试 | 贡献指南 |
全部文档
概览
| 文档 | 内容 |
|---|---|
| 系统概览 | 系统是什么、解决什么问题、组成部分、核心概念词汇表 |
| 隐私政策 | 身份服务隐私政策（面向终端用户） |
| 贡献指南 | 开发环境、测试分层、golden 回归、文档维护约定、PR 流程 |
教程
| 文档 | 内容 |
|---|---|
| 快速上手 | 本地从零跑通：装依赖 → 起控制面 → 起 Node Agent → 接上 Web 界面 |
操作手册
部署
| 文档 | 内容 |
|---|---|
| 部署 | 部署形态总览与拓扑 |
| 控制面部署 | 控制面整栈：compose、配置载体、nginx 前置、生产必做项 |
| 节点 Agent 部署 | 节点 agent：systemd 单元、安装、自更新器、加固 |
升级与迁移
| 文档 | 内容 |
|---|---|
| 升级与迁移 | 一次典型全量升级的顺序 |
| Agent 滚动升级 | wheel 构建、控制面驱动的自更新、手工滚动、回退与验收 |
| 控制面升级 | 控制面整栈重建与验收 |
| 数据库迁移 | Alembic 操作、create_all 库接入、已知的坑 |
| 锁步契约 | 协议 schema 与连通性契约的锁步规则、发布前检查清单 |
日常运维
| 文档 | 内容 |
|---|---|
| 健康与状态 | 健康五态、路由观测、指标、抖动观测入口 |
| 主动拨测 | 主动拨测与 agent 日志查看 |
| 故障排查 | 现象对照表、几类需展开的故障、路由调优三件套 |
网络与业务
| 文档 | 内容 |
|---|---|
| 节点接入 | 节点接入全流程：enrollment token → register → 审批闸门 → provision → token 生命周期 |
| 建立互联 | 建立 eBGP / iBGP 互联、internal_topology 不变量、route collector |
| 自动对等运维 | 自助对等的运维侧：供给策略、容量、配额、处置、排查 |
| DNS 与任播 | DNS 组、zone、记录、bind_addresses 任播、rDNS、CoreDNS |
| 寻址与 renumber | fleet 寻址分配与 renumber 操作的同步点 |
| 抖动处置 | 抖动一线操作：榜单与时序、根因区解读、处置与撤销、常见判例 |
身份与外部数据
| 文档 | 内容 |
|---|---|
| 账号与登录 | 管理端鉴权：静态 token 与账号会话双凭据、Cap 人机验证、限速 |
| ASN 归属验证 | ASN 归属验证：PGP / SSH 签名与邮箱验证的操作步骤 |
| 密钥托管与恢复 | WireGuard 私钥托管模型与离线恢复流程 |
| registry 副本 | DN42 registry 副本：同步机制、token 配置、手动触发、排错 |
参考
API
| 文档 | 内容 |
|---|---|
| API 参考 | 服务与基址、鉴权模型、通用约定 |
| 管理面 API | 管理面：节点、Peering、接口、BGP、DNS、token、审批、provision、健康、路由、审计、发布、处置、fleet 收权 |
| 控制台 BFF API | 控制台 BFF：聚合视图、趋势、榜单、registry 代理、拨测与日志 |
| 自动对等 API | 用户面：门户登录闭环、对等请求、只读网络态势 |
| 节点面 API | 节点面：注册、拉取、上报、自更新分发、三条 WebSocket 通道 |
| 公开 API | 公开只读端点与健康探针 |
| 认证服务 API | 认证服务：归属验证、Passkey、OAuth 2.0 / OIDC Provider |
| Registry 服务 API | Registry 副本服务全部端点 |
配置
| 文档 | 内容 |
|---|---|
| 配置参考 | 分层构造纪律与解析助手 |
| Control Server 配置 | Control Server 全部配置项 |
| Auth Server 配置 | Auth Server 全部配置项 |
| Registry Server 配置 | Registry Server 全部配置项 |
| Node Agent 配置 | Node Agent 三来源优先级、全部配置项、状态目录布局 |
数据库
| 文档 | 内容 |
|---|---|
| 数据层文档分三段：model/（为什么这样建模）· tables/（有哪些表，按子系统分册）· mechanics/（怎么运转）。 |
| 文档 | 内容 |
|---|---|
| 数据层参考 | 入口：三段导航 + 41 张表的全表速查（表 → 层 → 保留 → 实测 → 册） |
| 分层与存储角色 | 五层数据模型、三个存储实例的判据、db 分配、准入决策、备份边界 |
| 聚合根与关系 | 三个聚合根、全部外键关系树、ER 图 |
| 时序建模通则 | 桶口径、sum+count 形态、差分基准、保留与分区门控 |
| 全局约定 | 命名、引擎与连接池、类型纪律、spec JSON + 索引列双层 |
| 节点与网络 | 节点、密钥、端口池、接入凭据、世代、Peering 聚合 |
| 共享 DNS | DNS 三级模型与组装规则 |
| 账号、门户与自动对等 | 两个信任域、审计、自动对等策略与请求 |
| 健康与自观测 | 对账健康、上报历史、agent 自观测存档 |
| 路由观测 | 路由全表、逐路由明细、差分基准、churn 时间线 |
| 流量 | 热窗口 + 5min 存档 + 差分 prev，跨 L2/L3/L5 |
| Flap 检测 | 两级打分热态、转移历史、告警事件、速率与活跃度存档 |
| 写入路径 | materialize 与上报摄入两条路径、差分写、预提取、写入方一览 |
| KV 与缓存键索引 | Valkey 与 Redis 的每一个键：TTL、写入方、丢失后果、降级行为 |
| 性能与容量 | 实测规模、写热点、索引行为、vacuum、扩展阈值 |
| 迁移与演进 | create_all 与 Alembic、生产实况、已知偏差、分区化、迁移链 |
DesiredState
| 文档 | 内容 |
|---|---|
| DesiredState 参考 | StrictModel 不变量、顶层字段、跨字段校验 |
| 节点与接口 spec | NodeSpec、InterfaceSpec、WireGuardPeerSpec |
| Runtime spec | runtime 与其全部嵌套 spec |
| BIRD 与路由 spec | BIRD 配置、BGP 会话、内部拓扑、large community |
| DNS spec | DNS 相关 spec |
| Normalize 钩子 | 四个 normalize 钩子、模板集、枚举、完整示例 |
其它参考
| 文档 | 内容 |
|---|---|
| 渲染产物 | agent 渲染出的每个文件：产出什么、被谁消费、由哪部分 schema 驱动 |
| 地址模型 | 地址概念模型：所有地址按源 / 派生 / 副本分类，副本清单速查 |
| CLI 与脚本 | Node Agent CLI 全参数、运维工具、开发脚本、离线恢复工具 |
内部原理
| 文档 | 内容 |
|---|---|
| 架构 | 组件、边界、四条数据流、最小扰动设计、并发一致性、变更闭环 |
| Control Server 内部 | 控制面装配：materialize、健康推导、token 与注册、门铃、拨测过境 |
| Node Agent 内部 | 运行模式、守护双任务与门铃、planner 与收敛、采集上报、自愈与旁路任务 |
| 认证服务内部 | 认证服务：归属验证挑战、会话 JWT 与 JWKS、OAuth / OIDC Provider、服务边界 |
| registry-server 内部 | Registry 副本：唯一同步与落库点、查询 API、消费方与失败语义 |
| 自动对等内部 | 自动对等：OIDC 依赖方、门户会话与前后端交接、与管理面分离的信任域 |
| fleet 供给收权 | 节点密钥单一事实源、端口池入库与统一分配 |
| 内部互联 | 内部互联合成机制、internal_topology 一致性不变量、加节点 checklist |
| 路由策略 | BIRD 过滤器语义：导入 / 导出的判定顺序、cold potato、社区清洗、iBGP 与 OSPF 闸门 |
| flap 检测 | 抖动检测总览：定义、三条设计原则、端点一览、参数速查 |
| 观测与数据源 | 观测与数据源、存储分层 |
| flap 打分算法 | 衰减打分、计分规则、归因、告警边沿、速率时序 |
| 根因定位 | 根因定位算法与准确度验证 |
| flap 处置 | 处置动作与事务纪律 |
| 共享包 | 共享包分层、依赖方向、各包职责、锁步约束 |
| 安全模型 | 鉴权边界、token 哈希模型、审批闸门、禁止的控制模型、信任域隔离 |
文档维护约定
- 单一事实源——每个主题只在一处详细展开，其它地方用链接：
- 配置与 CLI → 配置参考 与 CLI 与脚本
- API → API 参考
- schema 字段 → DesiredState 参考
- 表结构 → 数据库参考
- 分层放置——手把手入门放
tutorials/；任务步骤放guides/；查得到的事实放reference/；为什么与怎么运转放internals/。 - 与代码同步——改了接口、配置、表结构、运行模式或 schema，必须同步对应参考文档；schema 与模板变化要刷新 golden。
- 写当前状态，不写演进过程——文档描述系统现在是什么样，不叙述它曾经是什么样。历史只在解释「为什么是现在这样」时出现，且要说清约束而非编年。
- 示例可执行——命令应当能在仓库根目录直接复制运行，且已脱敏。
- 中立表述——不用第一与第二人称，不按开发批次组织内容。
- 链接用相对路径，新增文档记得加进本页导航表。
详细约定见 贡献指南。