From 38d2329991ce5ca57237b8620f83553c59e84aaa Mon Sep 17 00:00:00 2001 From: zenfun Date: Wed, 24 Dec 2025 14:51:57 +0800 Subject: [PATCH] =?UTF-8?q?doc:=20=E5=A2=9E=E5=8A=A0=20.env=20=E7=9A=84?= =?UTF-8?q?=E6=B3=A8=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 5 ++++- README.md | 5 +++-- docs/api.md | 57 ++++++++++++++++++++++++++++++++++------------------ 3 files changed, 44 insertions(+), 23 deletions(-) diff --git a/.env.example b/.env.example index 7553302..253d566 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,7 @@ # Control Plane EZ_API_PORT=8080 EZ_PG_DSN=host=postgres user=postgres password=postgres dbname=ezapi port=5432 sslmode=disable +# 日志库 DSN（可选）；默认不创建独立 log DB，留空将使用主库写日志 EZ_LOG_PG_DSN= EZ_REDIS_ADDR=redis:6379 EZ_REDIS_PASSWORD= @@ -8,11 +9,13 @@ EZ_REDIS_DB=0 EZ_ADMIN_TOKEN=admin123 EZ_INTERNAL_STATS_TOKEN=internal123 EZ_CORS_ALLOW_ORIGINS=* +# 日志保留策略（单位：天 / 条数） EZ_LOG_RETENTION_DAYS=30 EZ_LOG_MAX_RECORDS=1000000 +# 日志分区（off/month/day） EZ_LOG_PARTITIONING=off -# Log DB (docker-compose log-postgres) +# Log DB (docker-compose log-postgres，可选；默认不启用独立日志库) LOG_POSTGRES_USER=postgres LOG_POSTGRES_PASSWORD=postgres LOG_POSTGRES_DB=ezapi_logs diff --git a/README.md b/README.md index 06c57a6..4718e55 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ EZ-API 网关系统的管理中心和控制平面。 EZ-API 是“控制平面”，负责管理事实来源 (Source of Truth)。 它主要承担： -1. **资源管理**：Master/Key/Provider/Model/Binding/Namespace 的 CRUD 与批量操作。 +1. **资源管理**：Master/Key/ProviderGroup/APIKey/Model/Binding/Namespace 的 CRUD 与批量操作。 2. **状态同步**：将配置快照与 Feature Flags 推送到 Redis，供 Balancer 使用。 3. **日志与统计**：日志摄取/统计、操作日志、实时计数回写。 4. **运行配置**：CORS、模型注册表、配额重置等运维能力。 @@ -36,7 +36,8 @@ EZ-API 是“控制平面”，负责管理事实来源 (Source of Truth)。 - `/admin/masters`（CRUD + batch + manage） - `/admin/masters/:id/realtime` - `/admin/masters/:id/keys` -- `/admin/providers`（CRUD + test + fetch-models + batch） +- `/admin/provider-groups`（CRUD） +- `/admin/api-keys`（CRUD + batch） - `/admin/models`（CRUD + batch） - `/admin/bindings`（CRUD + batch） - `/admin/namespaces`（CRUD） diff --git a/docs/api.md b/docs/api.md index cf8b72b..0c1c5d1 100644 --- a/docs/api.md +++ b/docs/api.md @@ -41,8 +41,9 @@ graph TD Master -- 签发 --> Key[Key 子令牌] Master -- 关联 --> Namespace[Namespace 命名空间] Namespace -- 定义 --> Binding[Binding 路由规则] - Binding -- 映射 --> Provider[Provider 上游供应商] - Provider -- 包含 --> Model[Model 模型能力] + Binding -- 映射 --> ProviderGroup[ProviderGroup 上游组] + ProviderGroup -- 包含 --> APIKey[APIKey 上游凭证] + Binding -. 关联 .-> Model[Model 能力表] ``` ### 2.2 身份与权限模型 @@ -57,22 +58,28 @@ graph TD - `allow_ips`/`deny_ips`：支持 CIDR 格式的 IP 白名单/黑名单。 ### 2.3 路由与供应商模型 -- **Provider (供应商)**：上游 AI 服务商（如 OpenAI, Anthropic）。 - - `weight`：在同一分组内的负载均衡权重。 - - `auto_ban`：若开启，当上游持续报错时，系统会自动暂时禁用该供应商。 -- **Model (模型能力)**：定义模型的基础属性（上下文长度、功能支持等）。 +- **ProviderGroup (上游组)**：一组同类型上游定义（如 OpenAI / Anthropic / Compatible）。 + - `base_url`、`models` 在 Group 层统一声明。 + - `name` 即路由的 `route_group`（内部使用）。 +- **APIKey (上游凭证)**：具体可用的 key 池。 + - `weight`：同组内负载均衡权重。 + - `auto_ban` / `ban_until`：支持自动熔断与手动禁用。 +- **Model (模型能力表)**：全局能力注册表（上下文长度、功能支持等）。 - **Namespace (命名空间)**：逻辑隔离单位，用于组织 Binding 规则。 - **Binding (路由规则)**：核心路由逻辑。 - - 将 `namespace.public_model`（用户请求的模型名）映射到特定的 `route_group`。 - - `selector_type`：匹配模式（目前主要为 `exact` 精确匹配）。 + - 将 `bindingKey = namespace.public_model` 映射到 `group_id`（ProviderGroup）。 + - 同一 `bindingKey` 可存在多条 Binding（候选），通过 `weight` 进行加权选择。 + - `selector_type` + `selector_value` 用于从 Group 的 `models` 中解析上游 true_model。 + - 能力校验以 `bindingKey` 为 key（CP 会将 true_model 能力汇总到 `bindingKey`）。 + - 客户端请求若未携带 namespace，DP 会使用 key 的 `default_namespace` 生成 `bindingKey`。 ### 2.4 状态机约定 | 状态值 | 适用对象 | 含义 | | :--- | :--- | :--- | | `active` | 所有 | 正常可用。 | | `suspended` | Master, Key, Namespace | 已停用，请求将被拦截。 | -| `auto_disabled` | Provider | 因故障被系统自动熔断。 | -| `manual_disabled` | Provider | 被管理员手动禁用。 | +| `auto_disabled` | APIKey | 因故障被系统自动熔断。 | +| `manual_disabled` | APIKey | 被管理员手动禁用。 | --- @@ -101,7 +108,7 @@ graph TD ### 4.1 管理端 (Admin API) - 需 Admin Token - **租户管理**：创建 Master、签发子 Key、实时 QPS 监控、冻结/解冻。 -- **供应商管理**：支持从预设模板创建、测试连通性、自动拉取上游模型列表。 +- **上游管理**：ProviderGroup + APIKey 的 CRUD 与批量操作。 - **模型注册表**：管理全局模型能力，支持从远程 `models.dev` 刷新和回滚。 - **日志审计**：全站请求日志查询、按条件批量删除日志、配置 Webhook 告警。 @@ -144,31 +151,41 @@ graph TD ``` ### 5.2 供应商与路由配置 -1. **添加 OpenAI 供应商**： +1. **创建 ProviderGroup**： ```bash - curl -X POST http://localhost:8080/admin/providers/custom \ + curl -X POST http://localhost:8080/admin/provider-groups \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ - "name": "openai-primary", + "name": "openai-default", + "type": "openai", "base_url": "https://api.openai.com/v1", + "models": ["gpt-4o", "gpt-4o-mini"] + }' + ``` +2. **创建 APIKey**： + ```bash + curl -X POST http://localhost:8080/admin/api-keys \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "group_id": 1, "api_key": "sk-...", - "group": "default", - "models": ["gpt-4", "gpt-3.5-turbo"], "weight": 10 }' ``` -2. **创建模型路由 (Binding)**： +3. **创建模型路由 (Binding)**： ```bash curl -X POST http://localhost:8080/admin/bindings \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "namespace": "default", - "public_model": "gpt-4-latest", - "route_group": "default", + "public_model": "gpt-4o", + "group_id": 1, "selector_type": "exact", - "selector_value": "gpt-4" + "selector_value": "gpt-4o", + "weight": 1 }' ```