外观
数据层参考
控制面全部持久数据的单一事实源。
权威定义在代码中：PostgreSQL schema 为 apps/control-server/app/db/models/ 下的 SQLAlchemy ORM（迁移见 migrations/versions/），KV 与缓存的键由各 service 模块声明。本册逐字对照源码，代码中不存在的内容不予收录。
auth-server 与 registry-server 各持有独立的 PostgreSQL 库（dn42_auth / dn42_registry），schema 见各自的内部文档：认证服务 · registry 副本服务。
三段结构
本册分三段，对应三种阅读目的：
| 段 | 目的 | 适用场景 |
|---|---|---|
| model/ | 理解建模决策 | 首次接触，或需要新增一类数据 |
| tables/ | 查表与键的定义 | 日常检索 |
| mechanics/ | 理解运转与演进 | 修改写入路径、排查性能、上线 schema 变更 |
一、model — 建模决策
| 文档 | 内容 |
|---|---|
| 分层与存储角色 | 五层数据模型、三个存储实例的角色与判据、db 编号分配、新数据的准入决策、备份边界 |
| 聚合根与关系 | 三个聚合根、全部外键关系树、ER 图 |
| 时序建模通则 | 桶口径、sum + count 形态、差分基准、保留期与裁剪、分区门控 |
| 全局约定 | 命名约定、引擎与连接池、类型纪律、spec JSON + 索引列双层结构 |
二、tables — 表定义
按子系统分册，每册自足。一个子系统的数据通常跨层，单册即可看到它的全部落点（哪些表在 PostgreSQL、哪些键在 KV、保留期多长），无需跨文件拼接。层作为每张表的属性标注，不作为目录轴。
| 文档 | 子系统 | 表数 |
|---|---|---|
| 节点与网络 | 节点身份、密钥、端口池、接入凭据、世代、Peering 聚合 | 10 |
| 共享 DNS | DNS 三级模型与组装规则 | 3 |
| 账号、门户与自动对等 | 两个信任域、审计、自动对等策略与请求 | 8 |
| 健康与自观测 | 对账健康、上报历史、agent 自观测存档 | 4 |
| 路由观测 | 路由全表、逐路由明细、差分基准、churn 时间线 | 4 |
| 流量 | 节点级与接口级流量：热窗口、5 min 存档、差分基准 | 4 |
| Flap 检测 | 两级打分热态、转移历史、告警事件、速率与活跃度存档 | 8 |
三、mechanics — 运转与演进
| 文档 | 内容 |
|---|---|
| 写入路径 | materialize 与上报摄入两条路径、差分写、预提取、写入方一览 |
| KV 与缓存键索引 | Valkey 与 Redis 中的每一个键：TTL、写入方、丢失后果、降级行为 |
| 性能与容量 | 实测规模与增长维度、写热点、索引行为、死元组、扩展阈值 |
| 迁移与演进 | create_all 与 Alembic、生产实况、已知偏差、分区化、迁移链 |
全表速查
控制库共 41 张 ORM 表。规模一列取自参考基线，口径为活行数 / pg_total_relation_size。层的含义见分层与存储角色。
| 表 | 层 | 保留 | 规模 | 册 |
|---|---|---|---|---|
nodes | L1 | 常驻 | 10 行 / 184 kB | fleet |
node_wireguard_keys | L1 | 常驻 | 10 行 / 24 kB | fleet |
port_pools | L1 | 常驻 | 2 行 / 24 kB | fleet |
agent_tokens | L1 | 常驻 | 13 行 / 56 kB | fleet |
enrollment_tokens | L1 | 常驻 | 0 行 / 24 kB | fleet |
pending_registrations | L1 | 常驻 | 0 行 / 40 kB | fleet |
generations | L1 | 每节点 100 代 | 752 行 / 4096 kB | fleet |
peerings | L1 | 常驻 | 45 行 / 120 kB | fleet |
wg_interfaces | L1 | 常驻 | 90 行 / 208 kB | fleet |
bgp_sessions | L1 | 常驻 | 46 行 / 152 kB | fleet |
dns_groups | L1 | 常驻 | 1 行 / 48 kB | dns |
dns_group_zones | L1 | 常驻 | 4 行 / 64 kB | dns |
dns_records | L1 | 常驻 | 54 行 / 48 kB | dns |
admin_users | L1 | 常驻 | 1 行 / 40 kB | access |
admin_sessions | L1 | 到期失效 | 50 行 / 56 kB | access |
admin_audit_log | L1 | 无上限 | 883 行 / 272 kB | access |
portal_login_transactions | L1（降级路径） | 30 min | 94 行 / 80 kB | access |
portal_sessions | L1 | 会话 TTL | 54 行 / 320 kB | access |
autopeering_node_policies | L1 | 常驻 | 10 行 / 32 kB | access |
peering_requests | L1 | 常驻 | 30 行 / 128 kB | access |
autopeer_route_rollup | L3 | 60 天 | 54 418 行 / 9768 kB | access |
node_status | L2 | 覆盖 | 10 行 / 336 kB | health |
node_status_events | L2 | 每 (节点,种类) 100 条 | 3 740 行 / 6768 kB | health |
node_metrics_rollup | L3 | 60 天 | 110 196 行 / 15 MB | health |
node_metrics_last | L2 | 覆盖 | 10 行 / 56 kB | health |
node_routing | L2 | 覆盖 | 10 行 / 344 kB | routing |
node_route_entries | L2 | 跟随最新快照 | 178 303 行 / 144 MB | routing |
node_route_prefix_hashes | L2 | 覆盖 | 10 行 / 1288 kB | routing |
node_routing_events | L2 | 每节点 17 280 条 | 37 265 行 / 7488 kB | routing |
node_traffic_rollup | L3 | 60 天 | 119 306 行 / 15 MB | traffic |
node_traffic_last_sample | L2 | 覆盖 | 10 行 / 56 kB | traffic |
node_iface_traffic_rollup | L3 | 60 天 | 777 120 行 / 127 MB | traffic |
node_iface_traffic_last | L2 | 覆盖 | 87 行 / 64 kB | traffic |
flap_alerts | 事实 | 已消警留 500 条 | 539 行 / 408 kB | flap |
bgp_flap_transitions | 事实 | 每节点 200 条 | 1 649 行 / 472 kB | flap |
node_prefix_flap_meta | L2 | 覆盖 | 10 行 / 56 kB | flap |
prefix_flap_rate_rollup | L3 | 60 天 | 462 604 行 / 61 MB | flap |
flap_activity_rollup | L3 | 60 天 | 49 590 行 / 4112 kB | flap |
bgp_flap_state | 降级路径 | 覆盖 | 136 行 / 104 kB | flap |
node_prefix_flaps | 降级路径 | 整表替换 | 1 802 行 / 528 kB | flap |
node_prefix_flap_paths | 降级路径 | 整表替换 | 1 547 行 / 984 kB | flap |
KV 与 Redis 中的键不在此表，逐键定义见 KV 与缓存键索引。
生产库中的三张残留表
peering_challenges、peering_sessions（挑战验证流迁至 auth-server 后废弃）与 registry_* 系列（副本拆为独立服务后废弃）已从 ORM 与迁移链移除，但现役生产库中仍保留着空表：该库由 create_all 建立，迁移中的 DROP TABLE 从未在生产执行。空表不占用资源、不参与读写，清理属于可选动作。原委见迁移与演进。