Admin API

所有管理操作通过 control_plane_app 提供的 HTTP API 完成，路由统一在 /admin/v1/* 前缀下。

概述

基础信息

项目	说明
基础路径	`/admin/v1`
协议	HTTP（默认仅 loopback 监听 `127.0.0.1`）
数据格式	JSON（`Content-Type: application/json`）
认证	Admin Session Token（Bearer）
字符编码	UTF-8

生产部署

Admin API 默认仅监听 loopback 地址。生产环境中，应通过 Nginx / Caddy 等反向代理对外暴露，并配置 HTTPS。

认证方式

除初始化 Setup 端点外，所有 API 请求需要在 Header 中携带 Admin Session Token：

http

Authorization: Bearer <admin_session_token>

Token 通过管理员登录接口获取。

通用响应格式

成功响应：

json

{
  "code": 0,
  "data": { ... }
}

分页列表：

json

{
  "code": 0,
  "data": {
    "items": [ ... ],
    "total": 150,
    "page": 1,
    "page_size": 20
  }
}

错误响应：

json

{
  "code": 40001,
  "message": "参数校验失败: app_id 不能为空"
}

系统管理

初始化向导

首次部署时，CP 处于 setup-only 状态，需要完成初始化：

http

# 检查系统状态
GET /admin/v1/setup/status

# 初始化 PKI（四类 CA）
POST /admin/v1/setup/pki/init

# 创建初始平台管理员
POST /admin/v1/setup/admin/init

初始化完成前，/cp/* 南向接口不开放。

仪表盘

http

# 获取仪表盘统计数据
GET /admin/v1/system/dashboard

返回内容包括：

应用数量、用户总数、在线用户数
节点状态汇总
近期活跃趋势

PKI 管理

管理四类独立 CA 及其签发的证书。

http

# 列出所有 CA
GET /admin/v1/pki/cas

# 查看 CA 详情
GET /admin/v1/pki/cas/:ca_id

# 签发证书
POST /admin/v1/pki/cas/:ca_id/certificates

# 吊销证书
POST /admin/v1/pki/certificates/:cert_id/revoke

# 导出证书/密钥
GET /admin/v1/pki/certificates/:cert_id/export

四类 CA 的用途：

CA 类型	用途
`cp_server_ca`	Control Plane HTTPS 服务端证书
`cp_node_client_ca`	节点访问 CP 的 mTLS 客户端证书
`tcp_server_ca`	业务 TCP 服务端证书（面向 SDK）
`app_client_ca`	SDK/App 客户端 mTLS 证书

应用管理

应用（Application）是 AuthNexus 的租户边界。

http

# 列出应用
GET /admin/v1/applications?page=1&page_size=20

# 创建应用
POST /admin/v1/applications
{
  "name": "我的应用",
  "description": "应用描述"
}

# 查看应用详情
GET /admin/v1/applications/:app_id

# 更新应用
PUT /admin/v1/applications/:app_id
{
  "name": "新名称",
  "description": "新描述"
}

# 删除应用
DELETE /admin/v1/applications/:app_id

代理管理

代理（Agent）分为两类：平台管理员和应用代理。

代理类型

字段	platform_admin	app_agent
`kind`	`platform_admin`	`app_agent`
`app_id`	`NULL`	引用真实 application
权限范围	全平台	仅授权应用

API 端点

http

# 列出代理
GET /admin/v1/agents?page=1&page_size=20&kind=app_agent

# 创建代理
POST /admin/v1/agents
{
  "username": "agent001",
  "password": "secure_password",
  "kind": "app_agent",
  "nickname": "代理001"
}

# 查看代理详情
GET /admin/v1/agents/:agent_id

# 更新代理
PUT /admin/v1/agents/:agent_id
{
  "nickname": "新昵称",
  "status": "active"
}

# 删除代理
DELETE /admin/v1/agents/:agent_id

代理应用授权

应用代理通过 agent_app_grants 多对多关系绑定到应用：

http

# 查看代理的应用授权
GET /admin/v1/agents/:agent_id/app-grants

# 授权应用
POST /admin/v1/agents/:agent_id/app-grants
{
  "app_ids": [1001, 1002, 1003]
}

# 撤销授权
DELETE /admin/v1/agents/:agent_id/app-grants/:app_id

代理层级

代理支持树形层级结构，子代理的权限范围不超过父代理：

http

# 查看代理树
GET /admin/v1/agents/tree

# 查看子代理
GET /admin/v1/agents/:agent_id/children

用户管理

管理终端用户（使用 SDK 接入的用户）。

http

# 搜索用户
GET /admin/v1/users?app_id=1001&keyword=test&page=1&page_size=20

# 查看用户详情
GET /admin/v1/users/:user_id

# 更新用户状态
PUT /admin/v1/users/:user_id
{
  "status": "disabled"
}

# 重置用户密码
POST /admin/v1/users/:user_id/reset-password
{
  "new_password": "new_secure_password"
}

用户与应用的关系在首次卡密登录时建立，不可变更。

卡密管理

卡密类型

http

# 列出卡密类型
GET /admin/v1/card-types?app_id=1001

# 创建卡密类型
POST /admin/v1/card-types
{
  "app_id": 1001,
  "name": "月卡",
  "duration_days": 30,
  "attribute": "standard"
}

# 更新卡密类型
PUT /admin/v1/card-types/:type_id

# 删除卡密类型
DELETE /admin/v1/card-types/:type_id

卡密操作

http

# 批量生成卡密
POST /admin/v1/card-keys/generate
{
  "card_type_id": 1,
  "count": 100,
  "prefix": "VIP"
}

# 搜索卡密
GET /admin/v1/card-keys?app_id=1001&card_type_id=1&status=unused&page=1&page_size=20

# 查看卡密详情
GET /admin/v1/card-keys/:key_id

# 禁用卡密
POST /admin/v1/card-keys/:key_id/disable

# 批量导出
GET /admin/v1/card-keys/export?app_id=1001&card_type_id=1&format=csv

云函数管理

http

# 列出云函数
GET /admin/v1/cloud-functions?app_id=1001

# 创建云函数
POST /admin/v1/cloud-functions
{
  "app_id": 1001,
  "name": "validate_input",
  "description": "输入验证函数",
  "script": "local ctx = authnexus.get_context()\nreturn json.encode({ok = true})"
}

# 查看云函数
GET /admin/v1/cloud-functions/:id

# 更新云函数
PUT /admin/v1/cloud-functions/:id
{
  "script": "-- 更新后的脚本",
  "description": "更新描述"
}

# 删除云函数
DELETE /admin/v1/cloud-functions/:id

每个 app_id + name 组合唯一。更新后自动通过配置推送机制下发到节点。

结算管理

佣金规则

http

# 列出佣金规则
GET /admin/v1/settlement/commission-rules?app_id=1001

# 创建佣金规则
POST /admin/v1/settlement/commission-rules
{
  "app_id": 1001,
  "agent_id": 5,
  "card_type_id": 1,
  "rate": 0.15,
  "description": "月卡15%佣金"
}

# 更新佣金规则
PUT /admin/v1/settlement/commission-rules/:rule_id

# 删除佣金规则
DELETE /admin/v1/settlement/commission-rules/:rule_id

INFO

佣金规则由后端强制限定为直接子代理，不允许跨级设置。

结算报表

http

# 生成结算报表
GET /admin/v1/settlement/reports?agent_id=5&start_date=2026-01-01&end_date=2026-01-31

# 查看报表详情
GET /admin/v1/settlement/reports/:report_id

节点管理

管理 server_app 业务节点。

http

# 列出节点
GET /admin/v1/nodes

# 查看节点详情（包含心跳状态、应用版本快照）
GET /admin/v1/nodes/:node_id

# 向节点发送命令
POST /admin/v1/nodes/:node_id/commands
{
  "type": "reload_config",
  "payload": {}
}

# 查看节点命令执行结果
GET /admin/v1/nodes/:node_id/commands/:cmd_id

# 查看节点配置下发状态
GET /admin/v1/nodes/:node_id/configs

节点状态

节点通过 Channel 1 定期 checkin，状态通过管理后台查看：

online — 心跳正常
stale — 心跳超时但未超过离线阈值
offline — 长时间无心跳

系统配置

运行时设置

http

# 查看当前运行时设置
GET /admin/v1/system/settings

# 更新运行时设置
PUT /admin/v1/system/settings
{
  "setting_key": "value"
}

配置类型参考

配置类型	说明	推送对象
`server_runtime_settings`	服务运行时参数	所有节点
`app_policy`	应用策略（登录限制、会话策略等）	相关节点
`app_variables`	应用变量（SDK 可查询）	相关节点
`app_client_ca_bundle`	应用 mTLS 客户端 CA 包	相关节点
`app_mtls_trust_bundle`	应用 mTLS 信任包	相关节点
`cp_agent_runtime`	CP Agent 运行参数	指定节点

所有配置更新后通过 Channel 2 SSE hint + Channel 1 pull 机制自动下发。

分页与筛选

大部分列表接口支持统一的分页和筛选参数：

参数	类型	说明
`page`	int	页码，从 1 开始
`page_size`	int	每页数量，默认 20，最大 100
`keyword`	string	关键词搜索（模糊匹配）
`app_id`	int	按应用筛选
`status`	string	按状态筛选
`sort_by`	string	排序字段
`sort_order`	string	`asc` 或 `desc`

错误码参考

错误码	含义
0	成功
40001	参数校验失败
40101	未认证（Token 缺失或无效）
40301	无权限
40401	资源不存在
40901	资源冲突（如重名）
50001	服务内部错误

Demo 模式

Admin 前端支持 Demo 模式，通过 MSW (Mock Service Worker) 在浏览器内拦截 /admin/v1 请求，无需后端即可演示：

powershell

# 启动 Demo 模式开发服务器
cd src\admin_frontend
npm run dev:demo

# 构建 Demo 静态资源
npm run build:demo

Demo 模式不污染生产构建：MSW、mocks、seed 数据仅在 VITE_DEMO_MODE=true 时动态导入。

Admin API ​

概述 ​

基础信息 ​

认证方式 ​

通用响应格式 ​

系统管理 ​

初始化向导 ​

仪表盘 ​

PKI 管理 ​

应用管理 ​

代理管理 ​

代理类型 ​

API 端点 ​

代理应用授权 ​

代理层级 ​

用户管理 ​

卡密管理 ​

卡密类型 ​

卡密操作 ​

云函数管理 ​

结算管理 ​

佣金规则 ​

结算报表 ​

节点管理 ​

节点状态 ​

系统配置 ​

运行时设置 ​

配置类型参考 ​

分页与筛选 ​

错误码参考 ​

Demo 模式 ​

Admin API

概述

基础信息

认证方式

通用响应格式

系统管理

初始化向导

仪表盘

PKI 管理

应用管理

代理管理

代理类型

API 端点

代理应用授权

代理层级

用户管理

卡密管理

卡密类型

卡密操作

云函数管理

结算管理

佣金规则

结算报表

节点管理

节点状态

系统配置

运行时设置

配置类型参考

分页与筛选

错误码参考

Demo 模式