diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..2484640 --- /dev/null +++ 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 ` + - 由环境变量 `EZ_ADMIN_TOKEN` 配置 +- **Master**：`Authorization: Bearer ` + - 由 `/admin/masters` 创建时返回，仅显示一次 +- **Internal**：`X-Internal-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 ' \ + -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 ' \ + -H 'Content-Type: application/json' \ + -d '{"scopes":"chat:write"}' \ + http://localhost:8080/admin/masters/{id}/keys +``` + +### 7.2 更新 Feature 开关 + +```bash +curl -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{"log_request_body_enabled":false}' \ + http://localhost:8080/admin/features +``` + +--- + +## 8. 备注 + +- Swagger 是接口字段“准确定义”，本文是业务含义“补充说明”。 +- 任何功能开关更新后，DP 会在下一次 Redis 刷新周期生效。