ez-api/docs/api.md

EZ-API 控制平面 API 文档（中文补充版）

本文补充 Swagger 中未详细说明的业务字段与配置含义，便于前端/运维快速理解。 Swagger 入口：GET /swagger/index.html

---

1. 基础信息

1.1 Base URL

默认：http://{host}:8080

1.2 鉴权方式

• Admin：Authorization: Bearer <admin_token>
  • 由环境变量 EZ_ADMIN_TOKEN 配置
• Master：Authorization: Bearer <master_key>
  • 由 /admin/masters 创建时返回，仅显示一次
• Internal：X-Internal-Token: <token>
  • 由环境变量 EZ_INTERNAL_STATS_TOKEN 配置

1.3 通用参数

• 列表分页（多数 GET /admin/*）：
  • page：从 1 开始
  • limit：默认 50，最大 200
  • search：模糊匹配（具体字段见各端点）
• 日志列表分页：
  • limit / offset
• 时间范围：
  • since / until：Unix 秒（日志查询、统计）
  • 删除日志使用 before：RFC3339 字符串

1.4 状态字段约定

• master.status：active / suspended
• key.status：active / suspended
• provider.status：active / auto_disabled / manual_disabled
• namespace.status：active / suspended

---

2. 核心数据模型速览

2.1 Master

• name：租户名称
• group：路由分组（影响 DP 选路）
• max_child_keys：可签发子 Key 数上限
• global_qps：Master 级 QPS，默认 0 表示关闭限流
• default_namespace / namespaces：命名空间访问控制
• epoch：用于撤销/轮换的版本号

2.2 Key（子 Key）

• scopes：权限/用途描述（字符串）
• model_limits：允许使用的模型（逗号分隔）
• model_limits_enabled：是否启用模型限制
• expires_at：过期时间（可选）
• allow_ips / deny_ips：CIDR 列表
• quota_limit / quota_used / quota_reset_at / quota_reset_type：额度控制

2.3 Provider

• type：上游类型（openai / anthropic / gemini 等）
• base_url：上游地址
• api_key：上游 Key
• group：路由分组
• models：支持模型列表（逗号分隔）
• weight：负载权重
• auto_ban / ban_until：自动禁用控制

2.4 Model

• name：模型名
• kind：chat / embedding / other
• context_window：最大上下文
• max_output_tokens：默认最大输出
• supports_vision / supports_functions / supports_tool_choice / supports_fim

2.5 Binding & Namespace

• Namespace：逻辑命名空间（面向用户）
• Binding：namespace.public_model → route_group 规则
  • selector_type：exact 等
  • selector_value：匹配值

---

3. Feature Flags（重点补充）

Feature 存储在 Redis meta:features。

3.1 常用开关

Key	类型	说明	默认
dp_state_store_backend	string	DP 状态存储后端：memory / redis	memory
dp_claude_cross_upstream	bool	允许 Claude 请求路由到 OpenAI 兼容上游	true
dp_context_preflight_enabled	bool	DP 上下文预校验开关	true
log_request_body_enabled	bool	记录请求体	true

3.2 日志清理覆盖项（特殊存储）

这两项不是写入 meta:features，而是写入独立 Redis key：

Key	说明	Redis Key	规则
log_retention_days	日志保留天数	meta:log:retention_days	0/空表示清除覆盖，恢复默认配置
log_max_records	最大日志条数	meta:log:max_records	0/空表示清除覆盖

3.3 更新 Feature 示例

PUT /admin/features

{
  "dp_context_preflight_enabled": false,
  "log_request_body_enabled": true,
  "log_retention_days": 30,
  "log_max_records": 1000000
}

---

4. Admin API（管理端）

4.1 Master 管理

• POST /admin/masters：创建 master
  • global_qps 默认 0（关闭限流）
• GET /admin/masters：分页/搜索列表
• GET /admin/masters/:id：详情（含 realtime 字段）
• PUT /admin/masters/:id：更新字段
• POST /admin/masters/:id/manage：freeze / unfreeze
• POST /admin/masters/batch：批量 delete / status
• POST /admin/masters/:id/keys：为 master 签发子 Key（仅此处返回 key_secret）
• GET /admin/masters/:id/realtime：实时统计（QPS/限流状态等）
• GET /admin/masters/:id/access / PUT /admin/masters/:id/access
  • 更新 default_namespace / namespaces，可 propagate_to_keys

4.2 Key 访问控制

• GET /admin/keys/:id/access
• PUT /admin/keys/:id/access

4.3 Provider 管理

• POST /admin/providers：创建 provider
• POST /admin/providers/preset：从预设模板创建
• POST /admin/providers/custom：自定义创建
• POST /admin/providers/google：Google Provider
• GET /admin/providers / GET /admin/providers/:id
• PUT /admin/providers/:id / DELETE /admin/providers/:id
• POST /admin/providers/:id/test：测试连通性
• POST /admin/providers/:id/fetch-models：拉取模型
• POST /admin/providers/batch：批量 delete / status

4.4 Model 管理

• POST /admin/models
• GET /admin/models
• PUT /admin/models/:id
• DELETE /admin/models/:id
• POST /admin/models/batch：批量删除

4.5 Binding 管理

• POST /admin/bindings
• GET /admin/bindings
• GET /admin/bindings/:id
• PUT /admin/bindings/:id
• DELETE /admin/bindings/:id
• POST /admin/bindings/batch：批量 delete / status

4.6 Namespace 管理

• POST /admin/namespaces
• GET /admin/namespaces
• GET /admin/namespaces/:id
• PUT /admin/namespaces/:id
• DELETE /admin/namespaces/:id

4.7 日志与统计

• GET /admin/logs：筛选条件
  • limit / offset / since / until / key_id / group / model / status_code
• DELETE /admin/logs：删除日志
  • body: { "before": "2025-01-01T00:00:00Z", "key_id": 1, "model": "gpt-4" }
• GET /admin/logs/stats：日志统计
• GET /admin/logs/webhook / PUT /admin/logs/webhook
  • enabled, url, secret, threshold, window_seconds, cooldown_seconds, status_code_threshold
• GET /admin/stats：全站用量统计
• GET /admin/operation-logs：操作日志（支持 page/limit/search）

4.8 模型注册表

• GET /admin/model-registry/status
• POST /admin/model-registry/check
• POST /admin/model-registry/refresh
• POST /admin/model-registry/rollback

4.9 其他

• GET /admin/features / PUT /admin/features
• POST /admin/sync/snapshot

---

5. Master API（租户端）

• GET /v1/self
• POST /v1/tokens：签发子 Key
• GET /v1/tokens
• GET /v1/tokens/:id
• PUT /v1/tokens/:id
• DELETE /v1/tokens/:id
• GET /v1/logs
• GET /v1/logs/stats
• GET /v1/stats：按时间范围统计
• GET /v1/realtime：实时统计（含 QPS/限流状态）

---

6. Internal API（仅内部使用）

• POST /internal/stats/flush
  • body:

{
  "keys": [
    {"token_hash":"...","requests":10,"tokens":120,"last_accessed_at":1700000000}
  ]
}

• GET /internal/metrics（内部指标）

---

7. 常见用法示例

7.1 创建 Master 并签发子 Key

# 创建 Master
curl -H 'Authorization: Bearer <admin_token>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"team-a","group":"default","max_child_keys":5}' \
  http://localhost:8080/admin/masters

# 为 Master 签发子 Key
curl -H 'Authorization: Bearer <admin_token>' \
  -H 'Content-Type: application/json' \
  -d '{"scopes":"chat:write"}' \
  http://localhost:8080/admin/masters/{id}/keys

7.2 更新 Feature 开关

curl -H 'Authorization: Bearer <admin_token>' \
  -H 'Content-Type: application/json' \
  -d '{"log_request_body_enabled":false}' \
  http://localhost:8080/admin/features

---

8. 备注

• Swagger 是接口字段“准确定义”，本文是业务含义“补充说明”。
• 任何功能开关更新后，DP 会在下一次 Redis 刷新周期生效。