mirror of https://github.com/EZ-Api/ez-api.git synced 2026-01-13 17:47:51 +00:00

Files

zenfun a0f13d55c1 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

2025-12-02 15:00:13 +08:00

1.9 KiB

Raw Blame History

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。这将高流量的数据平面与关系型数据库解耦。

1.9 KiB Raw Blame History Unescape Escape