From ca0be28aba2f86c7d7d26d89e194bc65b4ce55e4 Mon Sep 17 00:00:00 2001
From: zenfun <zenfun510@gmail.com>
Date: Mon, 22 Dec 2025 13:27:02 +0800
Subject: [PATCH] doc : update readme

---
 README.md | 102 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 71 insertions(+), 31 deletions(-)

diff --git a/README.md b/README.md
index 7f01fcc..7957472 100644
--- a/README.md
+++ b/README.md
@@ -4,55 +4,74 @@ EZ-API 网关系统的管理中心和控制平面。
 
 ## 目标
 
-EZ-API 是"大脑"。它管理着事实的来源 (Source of Truth)。
-它负责：
-1. **管理 API**: 提供商 (Providers)、API 密钥 (Keys) 和模型 (Models) 的 CRUD 操作。
-2. **状态同步**: 将配置快照推送到 Redis，供 Balancer 使用。
-3. **日志摄取**: 异步将访问日志写入 PostgreSQL。
+EZ-API 是“控制平面”，负责管理事实来源 (Source of Truth)。
+它主要承担：
+1. **资源管理**：Master/Key/Provider/Model/Binding/Namespace 的 CRUD 与批量操作。
+2. **状态同步**：将配置快照与 Feature Flags 推送到 Redis，供 Balancer 使用。
+3. **日志与统计**：日志摄取/统计、操作日志、实时计数回写。
+4. **运行配置**：CORS、模型注册表、配额重置等运维能力。
 
 ## 架构设计
 
-控制平面采用了传统的三层架构，但有一个关键的转折：它主动将状态推送到边缘 (Redis)。
+控制平面采用三层结构，并主动将状态推送到 Redis。
 
-- **数据库**: PostgreSQL (持久化存储)。
-- **缓存/总线**: Redis (向 Balancer 分发配置)。
+- **数据库**: PostgreSQL（主库），可选独立日志库（`EZ_LOG_PG_DSN`）。
+- **缓存/总线**: Redis（配置快照、实时计数、Feature Flags）。
 - **框架**: Gin + GORM。
 
 ## API 端点
 
-### 管理接口
-- `POST /providers`: 注册新的上游 AI 提供商。
-- `POST /keys`: 创建新的客户端 API 密钥。
-- `POST /models`: 注册支持的模型。
-- `GET /models`: 列出所有模型。
-- `POST /admin/masters/{id}/keys`: 代某个 master 签发子 key（子 key 仍归属该 master；仅审计 `issued_by=admin`）。
+### 基础
+- `GET /health`
+- `GET /api/status/test`
+- `GET /swagger/*any`
 
-### Feature Flags（给未来前端用）
+### Internal
+- `POST /internal/stats/flush`：Balancer 统计回写。
+- `GET /internal/metrics`：内部指标。
 
-控制平面会把轻量“开关配置”存到 Redis 的 hash：`meta:features`，并提供管理接口：
+### Admin
+- `/admin/masters`（CRUD + batch + manage）
+- `/admin/masters/:id/realtime`
+- `/admin/masters/:id/keys`
+- `/admin/providers`（CRUD + test + fetch-models + batch）
+- `/admin/models`（CRUD + batch）
+- `/admin/bindings`（CRUD + batch）
+- `/admin/namespaces`（CRUD）
+- `/admin/logs`、`/admin/logs/stats`、`/admin/logs/webhook`
+- `/admin/features`、`/admin/operation-logs`、`/admin/stats`
 
-- `GET /admin/features`
-- `PUT /admin/features`（body 为 JSON map）
+### Master
+- `/v1/self`
+- `/v1/tokens`（CRUD）
+- `/v1/logs`、`/v1/logs/stats`
+- `/v1/stats`、`/v1/realtime`
 
-常用 flags：
-
-- `dp_state_store_backend`: `memory`（默认）/ `redis`
-- `dp_claude_cross_upstream`: `true` / `false`
-
-### 系统接口
-- `POST /sync/snapshot`: 强制将 DB 状态全量重新同步到 Redis。
-- `POST /logs`: 供 Balancer 推送日志的内部端点 (异步)。
+### 说明
+- Master 的 `global_qps` 默认 `0` 表示限流关闭；仅当 `global_qps > 0` 才会在数据面生效。
 
 ## 配置说明
 
 | 变量名 | 默认值 | 说明 |
 |--------|--------|------|
 | `EZ_API_PORT` | `8080` | 监听端口。 |
-| `EZ_PG_DSN` | `host=localhost...` | PostgreSQL 连接字符串。 |
+| `EZ_PG_DSN` | `host=localhost...` | PostgreSQL 主库 DSN。 |
+| `EZ_LOG_PG_DSN` | `` | 日志库 DSN（可选）。 |
 | `EZ_REDIS_ADDR` | `localhost:6379` | Redis 地址。 |
-| `EZ_LOG_QUEUE` | `10000` | 日志缓冲通道的容量。 |
-| `EZ_LOG_BATCH_SIZE` | `10` | 单次 DB 事务写入的日志数量。 |
-| `EZ_LOG_LEVEL` | `info` | 日志级别，支持 `debug`、`info`、`warn`、`error`。 |
+| `EZ_REDIS_PASSWORD` | `` | Redis 密码。 |
+| `EZ_REDIS_DB` | `0` | Redis DB。 |
+| `EZ_CORS_ALLOW_ORIGINS` | `*` | 允许的 Origin 列表（逗号分隔）。 |
+| `EZ_LOG_QUEUE` | `10000` | 日志缓冲队列容量。 |
+| `EZ_LOG_BATCH_SIZE` | `10` | 单次 DB 写入日志数。 |
+| `EZ_LOG_FLUSH_MS` | `1000` | 日志批量刷新间隔（毫秒）。 |
+| `EZ_LOG_RETENTION_DAYS` | `30` | 日志保留天数。 |
+| `EZ_LOG_MAX_RECORDS` | `1000000` | 日志最大记录数。 |
+| `EZ_LOG_PARTITIONING` | `off` | 日志分区（off/month/day）。 |
+| `EZ_MODEL_REGISTRY_ENABLED` | `false` | 模型注册表开关。 |
+| `EZ_MODEL_REGISTRY_REFRESH_SECONDS` | `1800` | 模型注册表刷新间隔。 |
+| `EZ_MODEL_REGISTRY_CACHE_DIR` | `./data/model-registry` | 模型注册表缓存目录。 |
+| `EZ_QUOTA_RESET_INTERVAL_SECONDS` | `300` | 配额重置间隔。 |
+| `EZ_INTERNAL_STATS_TOKEN` | `` | 内部统计回写鉴权 token。 |
 
 配置读取优先级：环境变量 > 配置文件 > 默认值。通过 [Viper](https://github.com/spf13/viper) 支持 `./config.yaml`（或 `./config/config.yaml`），也可用 `EZ_CONFIG_FILE` 指定路径。示例：
 
@@ -80,7 +99,28 @@ auth:
 go run cmd/server/main.go
 ```
 
-### Docker 运行
+### Docker Compose（推荐）
+
+在 `ez-api` 目录使用自带的 `docker-compose.yml` 拉起完整栈（Postgres + Redis + ez-api + balancer）：
+
+```bash
+cd ez-api
+docker compose up -d
+```
+
+常用可选变量（写入 `.env`）：
+
+```env
+EZ_ADMIN_TOKEN=admin123
+EZ_INTERNAL_STATS_TOKEN=internal123
+EZ_BALANCER_LOG_SINK_ENABLED=false
+EZ_BALANCER_LOG_SINK_BASE_URL=http://ez-api:8080
+EZ_BALANCER_STATS_FLUSH_ENABLED=false
+EZ_BALANCER_STATS_FLUSH_BASE_URL=http://ez-api:8080
+EZ_BALANCER_STATS_FLUSH_TOKEN=internal123
+```
+
+### Docker 单独运行
 
 ```bash
 docker build -t ez-api .