mirror of
https://github.com/EZ-Api/ez-api.git
synced 2026-01-13 17:47:51 +00:00
doc: 增加 .env 的注释
This commit is contained in:
zenfun
@@ -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
|
||||
|
||||
@@ -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）
|
||||
|
||||
57
docs/api.md
57
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 <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",
|
||||
"route_group": "default",
|
||||
"public_model": "gpt-4o",
|
||||
"group_id": 1,
|
||||
"selector_type": "exact",
|
||||
"selector_value": "gpt-4"
|
||||
"selector_value": "gpt-4o",
|
||||
"weight": 1
|
||||
}'
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user