API 参考

状态：Current

最后核对：2026-05-16

本页按 nexus-backend/src/main.rs 注册路由整理。

Base URLs

REST:  http://localhost:8081/api
Agent control: NEXUS_REALITY_LISTEN_ADDR 对应的 REALITY listener

Agent 控制面使用 REALITY listener 上的 SecureAgentService，后端不再暴露单独的明文 gRPC listener。通过 Docker 测 REST 时需要额外发布 8081，或本地运行后端。

认证

公开路由：

方法	路径
POST	/api/auth/login

其他路由需要 auth middleware。

响应使用 ApiResponse<T> envelope：

{
  "success": true,
  "data": {},
  "error": null
}

REST 路由

Auth

方法	路径
GET	/api/auth/me
PUT	/api/auth/me
PUT	/api/auth/password
GET	/api/auth/users
POST	/api/auth/users

/api/auth/users 需要 admin。当前没有用户删除、禁用或角色更新路由。

Nodes

方法	路径
GET	/api/nodes
POST	/api/nodes
GET	/api/nodes/links
GET	/api/nodes/{id}
PUT	/api/nodes/{id}
DELETE	/api/nodes/{id}
POST	/api/nodes/{id}/psk
POST	/api/nodes/{id}/config

POST /api/nodes/{id}/config 用于刷新该节点的数据库权威运行时快照，不再接受内联 L4 规则 payload。版本、重放、回滚、应用回报和端口冲突语义见 运行时配置热重载。

Legacy Routes

方法	路径
GET	/api/routes
POST	/api/routes
GET	/api/routes/{id}
PUT	/api/routes/{id}
DELETE	/api/routes/{id}
GET	/api/routes/{id}/hops

L4 Chains

方法	路径
GET	/api/l4-chains
POST	/api/l4-chains
GET	/api/l4-chains/{id}
PUT	/api/l4-chains/{id}
DELETE	/api/l4-chains/{id}
POST	/api/l4-chains/{id}/deploy

端口管理

端口管理 API 暴露由启用的 L4 链、L3 服务和已保存 listener policy 推导出的控制平面 listener 意图，也暴露 Agent 最近一次 heartbeat 上报的运行时 listener 表。

方法	路径
GET	/api/nodes/ports
GET	/api/nodes/ports?node_id={id}
GET	/api/nodes/ports/runtime
GET	`/api/nodes/ports/runtime?node_id={id}&transport={tcp
PUT	/api/nodes/ports/policies

GET /api/nodes/ports 返回：

• nodes：供前端下拉框使用的所有节点。
• items：按 nodeId、transport、listenAddr、listenPort 标识的 listener 行。
• defaultPriorityOrder：当前为 ["reality", "tls", "noise", "raw"]。

items[].routes 包含计算后的 listener route，字段有：

• source：l4_chain、l4_upstream 或 l3_network。
• sourceLabel：来源显示名。
• matchKind：reality、sni、local_key、l3_context 或 default。
• matchValue：route 的匹配字符串。
• nextHop：下一跳 endpoint 或接口名。

GET /api/nodes/ports/runtime 返回 Agent heartbeat metadata 中的当前运行态：

• nodes：节点运行态记录。
• nodes[].reportedAt：携带 runtime 数据的 heartbeat 时间。
• nodes[].listeners：按可选 query 参数过滤后的 runtime listener。
• listeners[].state：Agent listener 状态，例如 running。
• listeners[].routes：Agent runtime table 中实际存在的 route。
• listeners[].bytesIn、bytesOut、activeSessions、totalSessions、errorSessions：Agent 上报的 runtime counter。

PUT /api/nodes/ports/policies 需要 admin 或 operator，请求体示例：

{
  "nodeId": "node-uuid",
  "transport": "tcp",
  "listenAddr": "::",
  "listenPort": 443,
  "priorityOrder": ["reality", "tls", "noise", "raw"]
}

支持的优先级标签是 reality、tls、noise、raw。transport 是 tcp 或 udp；QUIC 共享 UDP listener namespace。

后端会先去重，再按默认顺序补齐缺失标签后保存。

policy endpoint 保留用于 API 兼容和自动化。当前端口管理页不再暴露保存策略 icon；它展示可拖拽的逐 listener 服务列表，并从 /api/nodes/ports/runtime 加载 runtime preview。

L4 Upstreams

方法	路径
GET	/api/l4-upstreams
POST	/api/l4-upstreams
GET	/api/l4-upstreams/{id}
PUT	/api/l4-upstreams/{id}
DELETE	/api/l4-upstreams/{id}

GET /api/l4-upstreams 会返回分页的 items，其中每条 upstream 都带有 server_names、health_check_interval_ms 和 enabled。 create_upstream 需要 name 和 endpoint。update_upstream 不接受 name。

create_upstream 接收 name、endpoint、可选 server_names 和可选 health_check_interval_ms。update_upstream 接收 endpoint、 server_names、health_check_interval_ms 和 enabled。API 不再接受旧 health_check_path 字段。

Credentials

方法	路径
GET	/api/credentials
POST	/api/credentials
PUT	/api/credentials/{id}
DELETE	/api/credentials/{id}

类型：

• x25519
• tls_cert
• reality

当前没有 /api/certs 路由；TLS 证书通过统一 credentials API 管理。

Audit / Dashboard / Settings

方法	路径
GET	/api/audit
POST	/api/audit/{id}/revert
GET	/api/dashboard/stats
GET	/api/settings/connectivity
PUT	/api/settings/connectivity

gRPC

生产 Agent 控制服务是 SecureAgentService：

RPC	方向	用途
OpenSession	unary	使用每节点 control PSK 建立 secure session。
Control	双向流	传输加密的 hello、heartbeat、config 和 metrics frame。

protobuf 中仍保留旧 AgentService RPC 以兼容，但后端入口注册的是 SecureAgentServiceServer。