From a0f13d55c113c141758a4144daf3703ea841932d Mon Sep 17 00:00:00 2001
From: zenfun <zenfun510@gmail.com>
Date: Tue, 2 Dec 2025 15:00:13 +0800
Subject: [PATCH] docs: update readme with system architecture and usage guide

Replace placeholder with comprehensive documentation including:
- System goals and control plane responsibilities
- Architecture design and technology stack
- API endpoint reference for management and system interfaces
- Configuration variables and default values
- Deployment instructions for local and Docker environments
---
 README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 267cabb..69dc81b 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,61 @@
-# ez-api
+# EZ-API (控制平面)
+
+EZ-API 网关系统的管理中心和控制平面。
+
+## 目标
+
+EZ-API 是"大脑"。它管理着事实的来源 (Source of Truth)。
+它负责：
+1. **管理 API**: 提供商 (Providers)、API 密钥 (Keys) 和模型 (Models) 的 CRUD 操作。
+2. **状态同步**: 将配置快照推送到 Redis，供 Balancer 使用。
+3. **日志摄取**: 异步将访问日志写入 PostgreSQL。
+
+## 架构设计
+
+控制平面采用了传统的三层架构，但有一个关键的转折：它主动将状态推送到边缘 (Redis)。
+
+- **数据库**: PostgreSQL (持久化存储)。
+- **缓存/总线**: Redis (向 Balancer 分发配置)。
+- **框架**: Gin + GORM。
+
+## API 端点
+
+### 管理接口
+- `POST /providers`: 注册新的上游 AI 提供商。
+- `POST /keys`: 创建新的客户端 API 密钥。
+- `POST /models`: 注册支持的模型。
+- `GET /models`: 列出所有模型。
+
+### 系统接口
+- `POST /sync/snapshot`: 强制将 DB 状态全量重新同步到 Redis。
+- `POST /logs`: 供 Balancer 推送日志的内部端点 (异步)。
+
+## 配置说明
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `EZ_API_PORT` | `8080` | 监听端口。 |
+| `EZ_PG_DSN` | `host=localhost...` | PostgreSQL 连接字符串。 |
+| `EZ_REDIS_ADDR` | `localhost:6379` | Redis 地址。 |
+| `EZ_LOG_QUEUE` | `10000` | 日志缓冲通道的容量。 |
+| `EZ_LOG_BATCH_SIZE` | `10` | 单次 DB 事务写入的日志数量。 |
+
+## 运行方式
+
+### 本地运行
+
+```bash
+go run cmd/server/main.go
+```
+
+### Docker 运行
+
+```bash
+docker build -t ez-api .
+docker run -p 8080:8080 --env-file .env ez-api
+```
+
+## 设计决策
+
+- **异步日志**: 日志不会立即写入 DB。它们被缓冲在内存中，并分批刷新，以减少 DB IOPS。
+- **快照同步**: Balancer 不查询 DB，而是由 EZ-API 将 JSON 快照推送到 Redis。这将高流量的数据平面与关系型数据库解耦。