mirror of
https://github.com/EZ-Api/ez-api.git
synced 2026-01-13 17:47:51 +00:00
89cb74ba6e
- Replace direct zerolog usage with standard library `log/slog` in business code - Add `internal/logging` package with zerolog bridge handler for structured output - Create `internal/jsoncodec` package to centralize JSON encoding/decoding using Sonic - Update all services and main entry point to use new logging interface - Maintain backward compatibility with existing zerolog console output - Remove custom logger setup in favor of structured logging bridge
111 lines
3.6 KiB
Markdown
111 lines
3.6 KiB
Markdown
# 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 事务写入的日志数量。 |
|
||
| `EZ_LOG_LEVEL` | `info` | 日志级别，支持 `debug`、`info`、`warn`、`error`。 |
|
||
|
||
配置读取优先级：环境变量 > 配置文件 > 默认值。通过 [Viper](https://github.com/spf13/viper) 支持 `./config.yaml`（或 `./config/config.yaml`），也可用 `EZ_CONFIG_FILE` 指定路径。示例：
|
||
|
||
```yaml
|
||
server:
|
||
port: 8080
|
||
postgres:
|
||
dsn: host=localhost user=postgres password=postgres dbname=ezapi port=5432 sslmode=disable
|
||
redis:
|
||
addr: localhost:6379
|
||
db: 0
|
||
log:
|
||
batch_size: 10
|
||
flush_ms: 1000
|
||
queue_capacity: 10000
|
||
auth:
|
||
jwt_secret: change_me_in_production
|
||
```
|
||
|
||
## 运行方式
|
||
|
||
### 本地运行
|
||
|
||
```bash
|
||
go run cmd/server/main.go
|
||
```
|
||
|
||
### Docker 运行
|
||
|
||
```bash
|
||
docker build -t ez-api .
|
||
docker run -p 8080:8080 --env-file .env ez-api
|
||
```
|
||
|
||
### 本地联合开发（配合 balancer）
|
||
|
||
- 目录结构建议：`/workspace/` 下并列放置 `ez-api` 与 `balancer`。
|
||
- 初始化/更新 Go 工作区（Go 1.20+）：在 `/workspace` 执行
|
||
```bash
|
||
go work use ./ez-api ./ez-api/test ./balancer
|
||
```
|
||
仓库已附带 `go.work`，若路径一致可直接复用；若放在其他位置请按上面命令重建。
|
||
|
||
### 集成测试
|
||
|
||
依赖 Docker 与 docker compose，且默认在工作区里与 `balancer` 仓库并列（用于构建镜像）。在仓库内运行：
|
||
|
||
```bash
|
||
cd ez-api
|
||
./test/integration.sh
|
||
```
|
||
|
||
脚本会拉起 `docker-compose.integration.yml` 中的服务，运行带 `integration` tag 的 Go 测试，并在完成后清理容器和卷。
|
||
|
||
## 日志
|
||
|
||
- 业务代码统一使用标准库 `log/slog`（`logger.Info("msg", "k", v)` 风格）。
|
||
- 输出后端仍为 [zerolog](https://github.com/rs/zerolog)（通过 `internal/logging` 的 slog handler bridge），默认 ConsoleWriter。
|
||
- 通过 `EZ_LOG_LEVEL` 控制控制平面的日志等级，配合异步 DB 写入（LogWriter）一起使用。
|
||
|
||
## JSON
|
||
|
||
- 项目内 JSON 编解码统一走 `ez-api/internal/jsoncodec`（内部使用 Sonic）。
|
||
|
||
## 设计决策
|
||
|
||
- **异步日志**: 日志不会立即写入 DB。它们被缓冲在内存中，并分批刷新，以减少 DB IOPS。
|
||
- **快照同步**: Balancer 不查询 DB，而是由 EZ-API 将 JSON 快照推送到 Redis。这将高流量的数据平面与关系型数据库解耦。
|