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`

```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 刷新周期生效。