add doc

2026-01-13 17:47:51 +00:00 · 2025-12-22 14:34:22 +08:00
parent 9518ae3fec
commit d8682acfe5
1 changed files with 276 additions and 0 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -0,0 +1,276 @@
+# 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`
+
+```json
+{
+  "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:
+
+```json
+{
+  "keys": [
+    {"token_hash":"...","requests":10,"tokens":120,"last_accessed_at":1700000000}
+  ]
+}
+```
+
+- `GET /internal/metrics`（内部指标）
+
+---
+
+## 7. 常见用法示例
+
+### 7.1 创建 Master 并签发子 Key
+
+```bash
+# 创建 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 开关
+
+```bash
+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 刷新周期生效。