yangzhaohan
467 lines
20 KiB
Markdown
467 lines
20 KiB
Markdown
# Janus - AI 中转站 完整开发计划
|
||
|
||
## Context
|
||
|
||
构建一个 AI API 中转/网关服务（Janus），使用 Go + Gin + PostgreSQL（GORM），前端采用前后端分离架构（Vue 3）。
|
||
|
||
用户背景：Java 转 Go，项目兼顾学习目的。计划按阶段递增复杂度，每个阶段引入新的 Go 语言特性：
|
||
- 早期：struct、interface、error handling、package 组织
|
||
- 中期：goroutine、channel、sync 包（并发安全）
|
||
- 后期：middleware 模式、context、observability
|
||
|
||
## 架构总览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Clients │
|
||
│ (OpenAI SDK / Anthropic SDK / curl) │
|
||
└─────────────────┬───────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Janus Gateway │
|
||
│ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
|
||
│ │ Gin │ │ Proxy │ │ Management │ │
|
||
│ │ Router │ │ Engine │ │ API (CRUD) │ │
|
||
│ └────┬─────┘ └────┬─────┘ └───────┬───────┘ │
|
||
│ │ │ │ │
|
||
│ ┌────┴─────────────┴───────────────┴───────┐ │
|
||
│ │ Service Layer │ │
|
||
│ │ ┌──────────┐ ┌────────┐ ┌────────────┐ │ │
|
||
│ │ │ Balancer │ │ Health │ │ Rate Limiter│ │ │
|
||
│ │ │ Service │ │Checker │ │ Service │ │ │
|
||
│ │ └──────────┘ └────────┘ └────────────┘ │ │
|
||
│ └────────────────┬──────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────┴──────────────────────────┐ │
|
||
│ │ Repository Layer (GORM) │ │
|
||
│ └────────────────┬──────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────┴──────────────────────────┐ │
|
||
│ │ PostgreSQL │ │
|
||
│ └────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌────────────────────────────────────────────┐ │
|
||
│ │ Vue 3 Dashboard (SPA) │ │
|
||
│ └────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Upstream AI Providers │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
|
||
│ │ OpenAI │ │Anthropic │ │ Compatible │ │
|
||
│ │ API │ │ API │ │ (DS, QWen) │ │
|
||
│ └──────────┘ └──────────┘ └──────────────┘ │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 项目目录结构
|
||
|
||
```
|
||
janus/
|
||
├── cmd/
|
||
│ └── server/
|
||
│ └── main.go # 应用入口，依赖组装
|
||
├── internal/
|
||
│ ├── config/
|
||
│ │ └── config.go # YAML 配置加载（viper）
|
||
│ ├── model/
|
||
│ │ ├── provider.go # Provider 模型
|
||
│ │ ├── api_key.go # ApiKey 模型
|
||
│ │ ├── model.go # AIModel 模型
|
||
│ │ └── request_log.go # RequestLog 模型
|
||
│ ├── repository/
|
||
│ │ ├── provider_repo.go # Provider CRUD
|
||
│ │ ├── api_key_repo.go # ApiKey CRUD
|
||
│ │ ├── model_repo.go # AIModel CRUD
|
||
│ │ └── request_log_repo.go # Log 查询
|
||
│ ├── service/
|
||
│ │ ├── provider_svc.go # Provider 业务逻辑
|
||
│ │ ├── api_key_svc.go # ApiKey 管理
|
||
│ │ ├── balancer_svc.go # 负载均衡核心
|
||
│ │ ├── proxy_svc.go # 请求代理引擎
|
||
│ │ ├── health_svc.go # 健康检查 & 故障转移
|
||
│ │ └── rate_limit_svc.go # 速率限制
|
||
│ ├── handler/
|
||
│ │ ├── proxy_handler.go # /v1/* 代理端点
|
||
│ │ ├── provider_handler.go # Provider 管理 API
|
||
│ │ ├── api_key_handler.go # ApiKey 管理 API
|
||
│ │ ├── model_handler.go # Model 管理 API
|
||
│ │ ├── stats_handler.go # 统计 API
|
||
│ │ └── health_handler.go # 健康检查
|
||
│ ├── middleware/
|
||
│ │ ├── auth.go # API Key 认证
|
||
│ │ ├── ratelimit.go # 速率限制中间件
|
||
│ │ ├── logging.go # 请求日志中间件
|
||
│ │ ├── cors.go # CORS
|
||
│ │ └── recovery.go # Panic 恢复
|
||
│ ├── proxy/
|
||
│ │ ├── openai.go # OpenAI 协议适配器
|
||
│ │ ├── anthropic.go # Anthropic 协议适配器
|
||
│ │ └── adapter.go # 适配器接口定义
|
||
│ ├── balancer/
|
||
│ │ ├── strategy.go # 策略接口
|
||
│ │ ├── round_robin.go # 轮询实现
|
||
│ │ └── weighted.go # 加权实现
|
||
│ ├── health/
|
||
│ │ ├── checker.go # 健康检查 Worker
|
||
│ │ └── circuit_breaker.go # 熔断器
|
||
│ └── router/
|
||
│ └── router.go # 路由注册
|
||
├── pkg/
|
||
│ ├── response/
|
||
│ │ └── response.go # 统一响应格式
|
||
│ ├── errors/
|
||
│ │ └── errors.go # 自定义错误类型
|
||
│ └── utils/
|
||
│ └── utils.go # 工具函数
|
||
├── web/ # Vue 3 前端项目
|
||
│ ├── src/
|
||
│ │ ├── views/
|
||
│ │ ├── components/
|
||
│ │ ├── api/
|
||
│ │ └── router/
|
||
│ ├── package.json
|
||
│ └── vite.config.ts
|
||
├── migrations/ # 数据库迁移 SQL
|
||
│ ├── 001_init.up.sql
|
||
│ └── 001_init.down.sql
|
||
├── config.yaml # 默认配置
|
||
└── go.mod
|
||
```
|
||
|
||
## 数据库设计
|
||
|
||
```sql
|
||
-- providers: AI 服务提供商
|
||
CREATE TABLE providers (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
name VARCHAR(50) NOT NULL UNIQUE, -- openai / anthropic / deepseek
|
||
base_url VARCHAR(255) NOT NULL, -- https://api.openai.com
|
||
protocol VARCHAR(20) NOT NULL DEFAULT 'openai', -- openai / anthropic
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active / disabled
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- api_keys: API 密钥池
|
||
CREATE TABLE api_keys (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
provider_id BIGINT NOT NULL REFERENCES providers(id),
|
||
key_value TEXT NOT NULL, -- 加密存储
|
||
name VARCHAR(100), -- 别名/备注
|
||
weight INT NOT NULL DEFAULT 1, -- 负载权重
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active', -- active/disabled/depleted
|
||
fail_count INT NOT NULL DEFAULT 0, -- 连续失败计数
|
||
last_used_at TIMESTAMPTZ,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- models: 可用模型列表
|
||
CREATE TABLE models (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
provider_id BIGINT NOT NULL REFERENCES providers(id),
|
||
name VARCHAR(100) NOT NULL, -- gpt-4o / claude-sonnet-4-5
|
||
input_price DECIMAL(10,8) DEFAULT 0, -- 每 1K token 价格
|
||
output_price DECIMAL(10,8) DEFAULT 0,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'active',
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
UNIQUE(provider_id, name)
|
||
);
|
||
|
||
-- request_logs: 请求日志
|
||
CREATE TABLE request_logs (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
api_key_id BIGINT,
|
||
model_id BIGINT,
|
||
provider_id BIGINT,
|
||
request_method VARCHAR(10),
|
||
request_path VARCHAR(500),
|
||
request_body TEXT,
|
||
response_body TEXT,
|
||
status_code INT,
|
||
latency_ms INT,
|
||
tokens_in INT DEFAULT 0,
|
||
tokens_out INT DEFAULT 0,
|
||
cost DECIMAL(10,6) DEFAULT 0,
|
||
error_message TEXT,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||
);
|
||
|
||
-- 索引
|
||
CREATE INDEX idx_api_keys_provider_id ON api_keys(provider_id);
|
||
CREATE INDEX idx_api_keys_status ON api_keys(status);
|
||
CREATE INDEX idx_models_provider_id ON models(provider_id);
|
||
CREATE INDEX idx_request_logs_created_at ON request_logs(created_at DESC);
|
||
CREATE INDEX idx_request_logs_provider_id ON request_logs(provider_id);
|
||
```
|
||
|
||
## API 设计
|
||
|
||
### 代理端点（OpenAI 兼容 & Anthropic 兼容）
|
||
```
|
||
POST /v1/chat/completions # OpenAI 聊天补全
|
||
POST /v1/embeddings # OpenAI 嵌入
|
||
POST /v1/messages # Anthropic Messages API
|
||
GET /v1/models # 列出可用模型（聚合所有 provider）
|
||
```
|
||
|
||
### 管理 API（Dashboard 用）
|
||
```
|
||
# Providers
|
||
GET /api/admin/providers
|
||
POST /api/admin/providers
|
||
GET /api/admin/providers/:id
|
||
PUT /api/admin/providers/:id
|
||
DELETE /api/admin/providers/:id
|
||
|
||
# API Keys
|
||
GET /api/admin/api-keys?provider_id=
|
||
POST /api/admin/api-keys
|
||
PUT /api/admin/api-keys/:id
|
||
DELETE /api/admin/api-keys/:id
|
||
POST /api/admin/api-keys/:id/toggle # 启用/禁用
|
||
|
||
# Models
|
||
GET /api/admin/models?provider_id=
|
||
POST /api/admin/models
|
||
PUT /api/admin/models/:id
|
||
DELETE /api/admin/models/:id
|
||
|
||
# Stats
|
||
GET /api/admin/stats/overview # 总览统计
|
||
GET /api/admin/stats/requests # 请求明细
|
||
```
|
||
|
||
## 负载均衡 & 故障转移设计
|
||
|
||
### 负载策略接口
|
||
```go
|
||
type Strategy interface {
|
||
Next(keys []*model.ApiKey) *model.ApiKey
|
||
Name() string
|
||
}
|
||
```
|
||
|
||
### 策略实现
|
||
1. **RoundRobin** - 无状态轮询，适合均匀分布
|
||
2. **WeightedRoundRobin** - 按 weight 字段加权分配
|
||
|
||
### 健康检查
|
||
- 每个 ApiKey 维护 `fail_count` 连续失败计数
|
||
- 失败超过阈值（默认 3 次）自动标记为 `disabled`
|
||
- 后台 goroutine 定期重试 disabled 的 key（30s 间隔）
|
||
- 正常请求也作为隐式健康检查
|
||
|
||
### 故障转移流程
|
||
1. Balancer 选取一个 ApiKey
|
||
2. 代理请求到上游
|
||
3. 如果失败（5xx / 超时 / 网络错误）：
|
||
- 递增 `fail_count`
|
||
- 达到阈值标记 `disabled`
|
||
- 立即从剩余 key 中选择重试（最多 3 次）
|
||
4. 如果成功：重置 `fail_count` 为 0
|
||
|
||
### 熔断器（单例 per ApiKey）
|
||
```
|
||
状态机: CLOSED → (连续失败) → OPEN → (冷却时间) → HALF_OPEN → (成功) → CLOSED
|
||
→ (失败) → OPEN
|
||
```
|
||
|
||
## 分阶段实施计划
|
||
|
||
### Phase 1: 项目骨架 & 基础设施（第 1-2 天）
|
||
**学习目标**: Go 项目组织、package 管理、Gin 基础
|
||
|
||
具体任务：
|
||
- [-] 初始化 `go.mod`（go mod init github.com/synoth/janus）
|
||
- [ ] 安装核心依赖：gin, gorm, viper, pgx 驱动
|
||
- [ ] 实现 `internal/config/config.go`：Viper 加载 YAML 配置
|
||
- [ ] 编写 `config.yaml`：数据库连接、服务器端口等
|
||
- [ ] 实现 `cmd/server/main.go`：组装依赖，启动 Gin
|
||
- [ ] 实现 `internal/router/router.go`：基础路由
|
||
- [ ] 实现 `internal/handler/health_handler.go`：GET /health
|
||
- [ ] 实现 GORM 数据库连接 & AutoMigrate
|
||
- [ ] 添加 `.env` 支持敏感配置
|
||
|
||
**交付物**: 可运行的服务，响应 `/health`，连接数据库
|
||
|
||
### Phase 2: 数据模型 & Repository 层（第 2-3 天）
|
||
**学习目标**: Go struct、GORM 关系映射、interface 定义
|
||
|
||
具体任务：
|
||
- [ ] 定义 `internal/model/provider.go`（struct + GORM 标签）
|
||
- [ ] 定义 `internal/model/api_key.go`
|
||
- [ ] 定义 `internal/model/model.go`（AIModel）
|
||
- [ ] 定义 `internal/model/request_log.go`
|
||
- [ ] 编写 SQL 迁移脚本 `migrations/001_init.up.sql`
|
||
- [ ] 实现 `internal/repository/provider_repo.go`（CRUD）
|
||
- [ ] 实现 `internal/repository/api_key_repo.go`
|
||
- [ ] 实现 `internal/repository/model_repo.go`
|
||
- [ ] 编写 Repository 层的单元测试
|
||
|
||
**交付物**: 完整的数据访问层，可通过测试验证
|
||
|
||
### Phase 3: Provider & API Key 管理 API（第 3-4 天）
|
||
**学习目标**: Gin handler、请求验证、JSON 序列化、统一错误处理
|
||
|
||
具体任务：
|
||
- [ ] 实现 `pkg/response/response.go`：统一 JSON 响应格式
|
||
- [ ] 实现 `pkg/errors/errors.go`：业务错误码定义
|
||
- [ ] 实现 `internal/service/provider_svc.go`
|
||
- [ ] 实现 `internal/service/api_key_svc.go`
|
||
- [ ] 实现 `internal/handler/provider_handler.go`：CRUD API
|
||
- [ ] 实现 `internal/handler/api_key_handler.go`：CRUD API
|
||
- [ ] 实现 `internal/handler/model_handler.go`：模型管理 API
|
||
- [ ] 添加请求验证（binding tags + validator）
|
||
- [ ] Postman/curl 可测试的完整管理 API
|
||
|
||
**交付物**: 可通过 REST API 管理 Provider、ApiKey、Model
|
||
|
||
### Phase 4: 代理引擎（第 4-6 天）
|
||
**学习目标**: HTTP 反向代理、streaming、context、Go http.Client
|
||
|
||
具体任务：
|
||
- [ ] 实现 `internal/proxy/adapter.go`：协议适配器接口
|
||
```go
|
||
type Adapter interface {
|
||
Forward(ctx context.Context, key *model.ApiKey, body []byte) (*ProxyResult, error)
|
||
Protocol() string
|
||
}
|
||
```
|
||
- [ ] 实现 `internal/proxy/openai.go`：OpenAI 请求转发
|
||
- 支持 `/v1/chat/completions`（含 streaming）
|
||
- 支持 `/v1/embeddings`
|
||
- [ ] 实现 `internal/proxy/anthropic.go`：Anthropic 请求转发
|
||
- 支持 `/v1/messages`（含 streaming）
|
||
- [ ] 实现 `internal/service/proxy_svc.go`：编排代理流程
|
||
- [ ] 实现 `internal/handler/proxy_handler.go`：
|
||
- 解析请求路径确定目标 protocol
|
||
- 从 header 获取 Janus API Key → 查找 upstream key 池
|
||
- 调用代理服务
|
||
- [ ] 实现 `internal/middleware/auth.go`：Janus 自身的 API Key 认证
|
||
- [ ] 添加请求日志记录（写入 request_logs）
|
||
- [ ] 处理 streaming 响应（SSE）
|
||
|
||
**交付物**: 可以用 curl 通过 Janus 调用 OpenAI/Anthropic
|
||
|
||
### Phase 5: 负载均衡（第 6-7 天）
|
||
**学习目标**: Go interface 多态、sync.Mutex、原子操作
|
||
|
||
具体任务：
|
||
- [ ] 实现 `internal/balancer/strategy.go`：Strategy 接口
|
||
- [ ] 实现 `internal/balancer/round_robin.go`：
|
||
- 线程安全的轮询计数器（sync.Mutex 或 atomic）
|
||
- 跳过 disabled key
|
||
- [ ] 实现 `internal/balancer/weighted.go`：
|
||
- 加权轮询算法
|
||
- 平滑加权轮询（Nginx 算法）
|
||
- [ ] 实现 `internal/service/balancer_svc.go`：
|
||
- 集成策略选择（可通过 API 或配置切换）
|
||
- 从 DB 加载可用 key 列表（带缓存）
|
||
- [ ] 修改 ProxyService 集成 BalancerService
|
||
- [ ] 编写负载均衡的单元测试（验证分布均匀性）
|
||
|
||
**交付物**: 请求自动在多个 ApiKey 间负载均衡
|
||
|
||
### Phase 6: 健康检查 & 故障转移（第 7-9 天）
|
||
**学习目标**: Goroutine、Channel、context 取消、并发模式
|
||
|
||
具体任务：
|
||
- [ ] 实现 `internal/health/circuit_breaker.go`：
|
||
- 三态状态机（Closed/Open/HalfOpen）
|
||
- 可配置阈值和冷却时间
|
||
- [ ] 实现 `internal/health/checker.go`：
|
||
- 后台 goroutine 定期检查 disabled key
|
||
- 向每个 provider 发送轻量健康检查请求
|
||
- 通过 channel 接收检查结果
|
||
- [ ] 实现 `internal/service/health_svc.go`：
|
||
- 管理所有 key 的健康状态
|
||
- 优雅关闭（context 取消 → 停止所有 goroutine）
|
||
- [ ] 修改 ProxyService 添加故障转移逻辑：
|
||
- 请求失败 → 标记 key → 从剩余池中重试
|
||
- 最大重试次数 3
|
||
- 熔断器介入
|
||
- [ ] 添加健康状态 API：GET /api/admin/keys/:id/health
|
||
|
||
**交付物**: 单个 key 故障时自动切换，故障 key 自动恢复
|
||
|
||
### Phase 7: 速率限制 & 可观测性（第 9-10 天）
|
||
**学习目标**: Middleware 模式、token bucket 算法、结构化日志
|
||
|
||
具体任务：
|
||
- [ ] 实现 `internal/service/rate_limit_svc.go`：
|
||
- Token bucket 算法（golang.org/x/time/rate）
|
||
- 支持按 Janus API Key 限流
|
||
- 支持按上游模型限流
|
||
- [ ] 实现 `internal/middleware/ratelimit.go`：
|
||
- 从 Gin context 提取 key
|
||
- 返回 429 Too Many Requests
|
||
- 添加 Retry-After header
|
||
- [ ] 实现 `internal/middleware/logging.go`：
|
||
- 结构化日志（使用 slog 或 zerolog）
|
||
- 记录 latency、status、path、tokens
|
||
- [ ] 实现 `internal/middleware/recovery.go`：Panic 恢复
|
||
- [ ] 实现 `internal/handler/stats_handler.go`：
|
||
- 总请求数、成功率、平均延迟
|
||
- 按 Provider/Model 分组统计
|
||
- 费用汇总
|
||
- [ ] 添加 `internal/middleware/cors.go`
|
||
|
||
**交付物**: 完整的中间件链，可观测的统计数据
|
||
|
||
### Phase 8: Dashboard 前端 & 容器化（第 10-14 天）
|
||
**学习目标**: 前后端集成、Docker、项目收尾
|
||
|
||
具体任务：
|
||
- [ ] 初始化 Vue 3 + Vite 项目（`web/`）
|
||
- [ ] 安装 UI 组件库（Element Plus 或 Naive UI）
|
||
- [ ] 实现 Providers 管理页面
|
||
- [ ] 实现 API Keys 管理页面
|
||
- [ ] 实现 Models 管理页面
|
||
- [ ] 实现统计仪表盘页面（图表）
|
||
- [ ] 前端构建产物由 Gin 静态文件服务托管
|
||
- [ ] 编写 Dockerfile（多阶段构建）
|
||
- [ ] 编写 docker-compose.yml（Janus + PostgreSQL）
|
||
- [ ] 编写 README.md（中英文）
|
||
|
||
**交付物**: 完整的可部署项目
|
||
|
||
## Go 学习路径映射
|
||
|
||
| Phase | Go 特性 | Java 对比 |
|
||
|-------|---------|-----------|
|
||
| 1 | package, import, func, defer | package ≈ package, defer ≈ finally |
|
||
| 2 | struct, interface, 指针 | struct ≈ class(无继承), interface 隐式满足 |
|
||
| 3 | error handling, type assertion | error 返回值 ≠ exception |
|
||
| 4 | context, http.Client, io.Reader | context ≈ 请求上下文传递 |
|
||
| 5 | sync.Mutex, atomic, slice | 无内置锁语法，需显式使用 |
|
||
| 6 | goroutine, channel, select | ≈ ThreadPool + BlockingQueue |
|
||
| 7 | middleware 闭包, functional options | ≈ Filter chain / Builder pattern |
|
||
| 8 | 前后端集成, Docker | 通用技能 |
|
||
|
||
## 关键技术决策
|
||
|
||
1. **配置管理**: Viper（支持 YAML + 环境变量覆盖）
|
||
2. **ORM**: GORM v2（AutoMigrate 用于开发，生产用迁移脚本）
|
||
3. **API Key 加密**: 使用 AES-256-GCM 加密存储 key_value
|
||
4. **Streaming**: 使用 `http.Flusher` + SSE 协议
|
||
5. **日志**: slog（Go 1.21+ 内置结构化日志）
|
||
6. **前端**: Vue 3 + Vite + Element Plus（轻量、国内文档丰富）
|
||
7. **容器化**: 多阶段 Docker 构建，docker-compose 一键部署
|
||
|
||
## 验证方式
|
||
|
||
每个 Phase 完成后的验证方法：
|
||
1. `go build ./...` 编译通过
|
||
2. `go vet ./...` 静态分析通过
|
||
3. `go test ./...` 单元测试通过
|
||
4. curl / Postman 手动测试关键 API
|
||
5. Phase 4+ 可用 OpenAI SDK 指向 Janus 实际调用
|
||
6. Phase 6 手动停用一个 key 验证故障转移
|
||
7. Phase 8 `docker-compose up` 一键启动
|