Admin API 参考

本文档按当前后端代码（api/main.go + api/handler/*.go）同步整理，重点覆盖 Admin Console 相关接口。

基础信息

启动模式域名：
- SaaS 单租户：https://api.xairouter.com
- BYOK 多租户：https://api.xaicontrol.com
文中示例统一使用 $BASE_URL，先按模式设置：

export BASE_URL="https://api.xairouter.com"      # SaaS
# export BASE_URL="https://api.xaicontrol.com"   # BYOK

认证：Authorization: Bearer sk-Xvs...
权限模型：
- Owner：可管理 /x-keys、/x-conf、/x-config、/x-info
- Root：可发布系统级新闻 POST /x-news

端点总览

模块	方法	端点	说明
密钥管理	GET	`/x-keys`	查询密钥（支持筛选/分页）
密钥管理	GET	`/x-keys/{id	L{n}
密钥管理	POST	`/x-keys`	新增密钥
密钥管理	PUT/POST	`/x-keys/{id}`	更新密钥
密钥管理	DELETE	`/x-keys/{id}`	删除密钥
配置观测	GET	`/x-conf`	获取 Owner 配置 + 休眠/禁用密钥
配置批量	POST	`/x-conf`	批量配置（含级联更新）
配置 CRUD	GET/PUT/POST/DELETE	`/x-config`	Owner 配置读写删
用户详情	GET	`/x-info?user={id或name}`	查看指定用户详细信息
通知管理	POST/DELETE	`/x-news`、`/x-news/{target}`	创建/删除通知
工具接口	GET	`/x-gkey`	生成 `sk-Xvs` key
工具接口	GET	`/x-ekey/{text}`	加密文本
工具接口	GET	`/x-dkey/{text}`	解密文本

1) 密钥管理（`/x-keys`）

1.1 查询密钥

GET /x-keys

查询参数：

id：按 Key ID
level：按 Level
provider：按 Provider
page、size：分页；仅传 size 时 page 自动按 1 处理

路径筛选：

/x-keys/123：按 ID
/x-keys/L2：按 Level
/x-keys/api.openai.com：按 Provider

响应为数组，分页信息在 Header：X-Total-Count、X-Page、X-Per-Page、X-Total-Pages。

curl -H "Authorization: Bearer $API_KEY" \
  "${BASE_URL}/x-keys?page=1&size=20&level=2"

1.2 新增密钥

POST /x-keys

请求字段（与代码一致）：

{
  "Name": "OpenAI 主池",
  "Level": 1,
  "Provider": "https://api.openai.com",
  "SecretKey": "sk-xxxxxxxxxxxxxxxxxxxx",
  "Status": true,
  "config": {
    "provider_type": "standard"
  }
}

说明：

Provider 必填且必须是合法 URL。
SecretKey 必填，长度至少 20。
config 字段名为小写（json:"config"）。
Status 建议显式传入（未传时按 Go bool 零值处理）。
新增后会刷新缓存与轮询结构，并尝试自动补全 LEVEL_MAPPER。

1.3 更新密钥

PUT /x-keys/{id} 或 POST /x-keys/{id}

可更新字段：Name、Level、Provider、SecretKey、Status、config。

curl -X PUT ${BASE_URL}/x-keys/123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Level":2,"Status":true}'

1.4 删除密钥

DELETE /x-keys/{id}

curl -X DELETE ${BASE_URL}/x-keys/123 \
  -H "Authorization: Bearer $API_KEY"

2) Owner 配置批量接口（`/x-conf`）

2.1 获取配置

GET /x-conf

返回字段（当前代码）：

Resources
LevelMapper
ModelMapper
ModelFailover
ModelLimits
SwitchOver
SleepingKeys
DisabledKeys
UserMinBalance
UserApiBalance

2.2 批量更新

POST /x-conf

支持字段：

LoadKeys（bool）
LogEnable（bool）
SaveCache（bool）
Resources（string）
LevelMapper（string）
ModelMapper（string）
ModelFailover（string）
DelKeys（bool）
ModelLimits（object 或 string）

ModelLimits 字符串操作：

* 或 =：清空
-model：删除指定模型

curl -X POST ${BASE_URL}/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ModelMapper":"gpt-3.5*=gpt-4o-mini",
    "LevelMapper":"gpt-4*=2",
    "ModelLimits":{"gpt-4o":{"rpm":30,"tpm":90000}}
  }'

说明：

ModelMapper、ModelLimits 会同步到后代用户（按代码中的级联逻辑）。
LevelMapper 由 Owner 配置驱动，后代用户按条件同步。

3) Owner 配置 CRUD（`/x-config`）

3.1 获取配置

GET /x-config

返回格式：

{
  "success": true,
  "oid": 1,
  "configs": {
    "MODEL_MAPPER": {},
    "MODEL_FAILOVER": {},
    "LEVEL_MAPPER": {},
    "SWITCH_OVER": {},
    "RESOURCES": {},
    "MODEL_LIMITS": {},
    "PRICING": "",
    "XAI_MAIL": "",
    "EMAIL_PORT": "",
    "EMAIL_SMTP": "",
    "EMAIL_AUTH": ""
  }
}

3.2 更新配置

PUT /x-config 或 POST /x-config

该接口按 map[string]string 解析，请求值应为字符串。

允许键：

MODEL_MAPPER
MODEL_FAILOVER
LEVEL_MAPPER
SWITCH_OVER
RESOURCES
MODEL_LIMITS（JSON 字符串）
PRICING（JSON 字符串）
XAI_MAIL
EMAIL_PORT
EMAIL_SMTP
EMAIL_AUTH
EMAIL_PASS

curl -X PUT ${BASE_URL}/x-config \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "MODEL_MAPPER":"gpt-4=gpt-4o",
    "MODEL_LIMITS":"{\"gpt-4o\":{\"rpm\":30}}"
  }'

3.3 删除配置键

DELETE /x-config

{
  "keys": ["MODEL_MAPPER", "PRICING"]
}

4) 用户详情（`/x-info`）

GET /x-info?user={id或name}

user 参数必填。
仅允许查询当前 Owner 体系下用户。
响应为 user_info 结构，包含余额、限额、ACL、ModelMapper、ModelLimits、日/月用量等。

5) 新闻通知（`/x-news`）

5.1 创建通知

POST /x-news：系统通知（仅 Root）
POST /x-news/{target}：定向通知

target 可为：

用户 ID
用户名
DNA（以 . 开头）

请求体：

{
  "title": "维护通知",
  "content": "今晚 02:00~03:00 升级",
  "days": 3
}

5.2 删除通知

DELETE /x-news
DELETE /x-news/{target}

删除行为是“删除该目标下全部新闻项”。

6) 常见错误码

401 Unauthorized：缺失或无效 API Key
403 Forbidden：非 Owner 调用 Owner 接口，或越权操作
404 Not Found：目标用户/密钥不存在
400 Bad Request：参数或请求体格式不合法