数据库参考

状态：Current

最后核对：2026-05-16

本页按 nexus-backend/migrations/001_initial_schema.sql 到 033_node_config_updated_at.sql 整理。

核心表

nodes

节点库存和 Agent 连接信息。

metadata JSON 可包含 node_port_runtime_listeners 和 node_port_runtime_reported_at，由 Agent heartbeat 写入。这两个字段支撑 GET /api/nodes/ports/runtime，表示 Agent 实际应用后的 listener 表。

重要字段：

• id
• name
• public_ip
• public_ipv6
• status
• last_heartbeat
• metadata
• iso_3166_code
• manual_addresses
• detected_addresses
• multiplex
• multiplex_port
• control_psk_verifier
• control_psk_fingerprint
• control_psk_rotated_at
• config_updated_at

WireGuard 字段已由迁移 008 删除。region/datacenter/latitude/longitude 已由迁移 009 删除或替换。

config_updated_at 是节点级运行时配置版本输入。会改变 Agent 目标运行态的节点配置更新会推进该字段；heartbeat、runtime listener 回报和其他运行态 metadata 仍只影响 updated_at，不会无意义触发配置下发。

routes / route_hops

legacy route 表仍存在用于兼容，但当前 gateway 工作流以 L4 chains 为主。route_rules 已由迁移 010 删除。

tunnel_chains

当前 L4 chain 存储。

重要字段：

• id
• name
• client_protocol
• enabled
• stages
• version

stages 是 JSONB，保存每 hop chain 模型。控制台选择 target 时会把 upstream_id 存进 stages，endpoint 字符串仅作为旧数据 fallback。

upstream_clusters

L4 上游端点注册表。

重要字段：

• id
• name
• endpoint
• server_names
• health_check_interval_ms
• enabled

server_names 写入时会 trim、lowercase、去重。health_check_interval_ms 默认是 0，表示关闭。health_check_path 已由迁移 030 删除。

enc_keys

可复用 X25519 key material。

重要字段：

• id
• name
• public_key
• private_key
• key_type
• metadata
• created_at

当前规范类型是 x25519。udp_noise 是 legacy alias，统一 credentials API 会规范化为 x25519。

reality_profiles

REALITY profile 配置，引用一个 X25519 key。

重要字段：

• id
• name
• x25519_key_id
• target_host
• target_port
• server_names
• short_ids
• metadata

node_port_policies

端口管理使用的每节点 listener 优先级策略表。该表现在主要作为 API 管理策略的兼容存储；当前端口管理页不再暴露策略保存 icon，并使用 Agent runtime heartbeat 状态做预览。

重要字段：

• id
• node_id
• transport
• listen_addr
• listen_port
• priority_order
• enabled
• created_at
• updated_at

node_id 引用 nodes(id)，节点删除时级联删除。transport 是 tcp 或 udp；QUIC 共享 UDP listener namespace。priority_order 是 JSONB 数组，例如 ["reality", "tls", "noise", "raw"]。该表按 node_id + transport + listen_addr + listen_port 定位一条策略。

唯一约束：

UNIQUE (node_id, transport, listen_addr, listen_port)

旧 L3 产品表

旧 l3_networks、l3_endpoints、l3_routes、l3_key_material、l3_key_epochs 产品表已由迁移 064 删除。现在承载链路由 SD-WAN underlay profiles 管理。 Agent 中通用 TUN I/O、userspace WireGuard、QUIC DATAGRAM、offload、GSO、GRO 代码仍保留为共享数据面底座。

auth_users

RBAC 用户账户，包含 username、password_hash、role、disabled、last_login_at。

audit_logs

不可变审计记录，包含 action、resource、old/new state、diff、IP、user agent 和创建时间。

certificates

TLS 证书存储。当前通过 /api/credentials 的 tls_cert 类型访问。

app_settings

后端设置键值表。当前默认键包括 node_offline_timeout_seconds。