mirror of
https://github.com/EZ-Api/ez-api.git
synced 2026-01-13 17:47:51 +00:00
a0f13d55c1
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
EZ-API (控制平面)
EZ-API 网关系统的管理中心和控制平面。
目标
EZ-API 是"大脑"。它管理着事实的来源 (Source of Truth)。 它负责：
- 管理 API: 提供商 (Providers)、API 密钥 (Keys) 和模型 (Models) 的 CRUD 操作。
- 状态同步: 将配置快照推送到 Redis，供 Balancer 使用。
- 日志摄取: 异步将访问日志写入 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 事务写入的日志数量。 |
运行方式
本地运行
go run cmd/server/main.go
Docker 运行
docker build -t ez-api .
docker run -p 8080:8080 --env-file .env ez-api
设计决策
- 异步日志: 日志不会立即写入 DB。它们被缓冲在内存中，并分批刷新，以减少 DB IOPS。
- 快照同步: Balancer 不查询 DB，而是由 EZ-API 将 JSON 快照推送到 Redis。这将高流量的数据平面与关系型数据库解耦。