doc: 增加 .env 的注释

.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

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）

docs/api.md

@@ -41,8 +41,9 @@ graph TD
     Master -- 签发 --> Key[Key 子令牌]
     Master -- 关联 --> Namespace[Namespace 命名空间]
     Namespace -- 定义 --> Binding[Binding 路由规则]
-    Binding -- 映射 --> Provider[Provider 上游供应商]
+    Binding -- 映射 --> ProviderGroup[ProviderGroup 上游组]
-    Provider -- 包含 --> Model[Model 模型能力]
+    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）。
+- **ProviderGroup (上游组)**：一组同类型上游定义（如 OpenAI / Anthropic / Compatible）。
-  - `weight`：在同一分组内的负载均衡权重。
+  - `base_url`、`models` 在 Group 层统一声明。
-  - `auto_ban`：若开启，当上游持续报错时，系统会自动暂时禁用该供应商。
+  - `name` 即路由的 `route_group`（内部使用）。
-- **Model (模型能力)**：定义模型的基础属性（上下文长度、功能支持等）。
+- **APIKey (上游凭证)**：具体可用的 key 池。
+  - `weight`：同组内负载均衡权重。
+  - `auto_ban` / `ban_until`：支持自动熔断与手动禁用。
+- **Model (模型能力表)**：全局能力注册表（上下文长度、功能支持等）。
 - **Namespace (命名空间)**：逻辑隔离单位，用于组织 Binding 规则。
 - **Binding (路由规则)**：核心路由逻辑。
-  - 将 `namespace.public_model`（用户请求的模型名）映射到特定的 `route_group`。
+  - 将 `bindingKey = namespace.public_model` 映射到 `group_id`（ProviderGroup）。
-  - `selector_type`：匹配模式（目前主要为 `exact` 精确匹配）。
+  - 同一 `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 | 因故障被系统自动熔断。 |
+| `auto_disabled` | APIKey | 因故障被系统自动熔断。 |
-| `manual_disabled` | Provider | 被管理员手动禁用。 |
+| `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 <admin_token>" \
      -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 <admin_token>" \
+     -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 <admin_token>" \
      -H "Content-Type: application/json" \
      -d '{
        "namespace": "default",
-       "public_model": "gpt-4-latest",
+       "public_model": "gpt-4o",
-       "route_group": "default",
+       "group_id": 1,
        "selector_type": "exact",
-       "selector_value": "gpt-4"
+       "selector_value": "gpt-4o",
+       "weight": 1
      }'
    ```