lanyuanxiaoyao
1580b5b838
- 更新项目结构，反映分层架构（handler → service → repository） - 完善技术栈说明，包含所有依赖和版本信息 - 添加首次启动的自动初始化说明 - 展开管理接口的详细 CRUD 端点 - 添加完整配置文件示例和数据文件说明 - 分离前后端测试和开发命令 - 指向子项目 README 获取详细开发规范
204 lines
5.3 KiB
Markdown
204 lines
5.3 KiB
Markdown
# Nex - AI Gateway
|
||
|
||
一个统一的大模型 API 网关，支持 OpenAI 和 Anthropic 双协议，让应用只需配置一个地址即可透明使用多个供应商的大模型服务。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
nex/
|
||
├── backend/ # Go 后端服务（分层架构）
|
||
│ ├── cmd/server/ # 主程序入口
|
||
│ ├── internal/
|
||
│ │ ├── handler/ # HTTP 处理器 + 中间件
|
||
│ │ ├── service/ # 业务逻辑层
|
||
│ │ ├── repository/ # 数据访问层
|
||
│ │ ├── domain/ # 领域模型
|
||
│ │ ├── protocol/ # 协议适配器（OpenAI/Anthropic）
|
||
│ │ ├── provider/ # 供应商客户端
|
||
│ │ └── config/ # 配置管理
|
||
│ ├── pkg/ # 公共包（logger/errors/validator）
|
||
│ ├── migrations/ # 数据库迁移
|
||
│ └── tests/ # 测试（unit/integration）
|
||
│
|
||
├── frontend/ # React 前端界面
|
||
│ ├── src/
|
||
│ │ ├── api/ # API 层（统一请求封装 + 字段转换）
|
||
│ │ ├── hooks/ # TanStack Query hooks
|
||
│ │ ├── components/ # 通用组件（AppLayout）
|
||
│ │ ├── pages/ # 页面（Providers, Stats）
|
||
│ │ ├── routes/ # React Router 路由配置
|
||
│ │ ├── types/ # TypeScript 类型定义
|
||
│ │ └── __tests__/ # 单元测试 + 组件测试
|
||
│ ├── e2e/ # Playwright E2E 测试
|
||
│ └── package.json
|
||
│
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
## 功能特性
|
||
|
||
- **双协议支持**：同时支持 OpenAI 和 Anthropic 协议
|
||
- **透明代理**：对 OpenAI 兼容供应商透传请求
|
||
- **流式响应**：完整支持 SSE 流式传输
|
||
- **Function Calling**：支持工具调用（Tools）
|
||
- **多供应商管理**：配置和管理多个供应商
|
||
- **用量统计**：按供应商、模型、日期统计请求数量
|
||
- **Web 配置界面**：提供供应商和模型配置管理
|
||
|
||
## 技术栈
|
||
|
||
### 后端
|
||
- **语言**: Go 1.26+
|
||
- **HTTP 框架**: Gin
|
||
- **ORM**: GORM
|
||
- **数据库**: SQLite
|
||
- **日志**: zap + lumberjack（结构化日志 + 日志轮转）
|
||
- **配置**: gopkg.in/yaml.v3
|
||
- **验证**: go-playground/validator/v10
|
||
- **迁移**: goose
|
||
|
||
### 前端
|
||
- **运行时**: Bun
|
||
- **构建工具**: Vite
|
||
- **语言**: TypeScript (strict mode)
|
||
- **框架**: React
|
||
- **UI 组件库**: Ant Design 5
|
||
- **路由**: React Router v7
|
||
- **数据获取**: TanStack Query v5
|
||
- **样式**: SCSS Modules
|
||
- **测试**: Vitest + React Testing Library + Playwright
|
||
|
||
## 快速开始
|
||
|
||
### 后端
|
||
|
||
```bash
|
||
cd backend
|
||
go mod download
|
||
go run cmd/server/main.go
|
||
```
|
||
|
||
后端服务将在 `http://localhost:9826` 启动。首次启动会自动：
|
||
- 创建配置文件 `~/.nex/config.yaml`
|
||
- 初始化数据库 `~/.nex/config.db`
|
||
- 运行数据库迁移
|
||
- 创建日志目录 `~/.nex/log/`
|
||
|
||
### 前端
|
||
|
||
```bash
|
||
cd frontend
|
||
bun install
|
||
bun dev
|
||
```
|
||
|
||
前端开发服务器将在 `http://localhost:5173` 启动，API 请求通过 Vite proxy 转发到后端。
|
||
|
||
## API 接口
|
||
|
||
### 代理接口（对外部应用）
|
||
|
||
- `POST /v1/chat/completions` - OpenAI Chat Completions API
|
||
- `POST /v1/messages` - Anthropic Messages API
|
||
|
||
### 管理接口（对前端）
|
||
|
||
#### 供应商管理
|
||
- `GET /api/providers` - 列出所有供应商
|
||
- `POST /api/providers` - 创建供应商
|
||
- `GET /api/providers/:id` - 获取供应商
|
||
- `PUT /api/providers/:id` - 更新供应商
|
||
- `DELETE /api/providers/:id` - 删除供应商
|
||
|
||
#### 模型管理
|
||
- `GET /api/models` - 列出模型（支持 `?provider_id=xxx` 过滤）
|
||
- `POST /api/models` - 创建模型
|
||
- `GET /api/models/:id` - 获取模型
|
||
- `PUT /api/models/:id` - 更新模型
|
||
- `DELETE /api/models/:id` - 删除模型
|
||
|
||
#### 统计查询
|
||
- `GET /api/stats` - 查询统计
|
||
- `GET /api/stats/aggregate` - 聚合统计
|
||
|
||
查询参数支持：`provider_id`、`model_name`、`start_date`、`end_date`、`group_by`
|
||
|
||
## 配置
|
||
|
||
配置文件位于 `~/.nex/config.yaml`，首次启动自动生成：
|
||
|
||
```yaml
|
||
server:
|
||
port: 9826
|
||
read_timeout: 30s
|
||
write_timeout: 30s
|
||
|
||
database:
|
||
path: ~/.nex/config.db
|
||
max_idle_conns: 10
|
||
max_open_conns: 100
|
||
conn_max_lifetime: 1h
|
||
|
||
log:
|
||
level: info
|
||
path: ~/.nex/log
|
||
max_size: 100 # MB
|
||
max_backups: 10
|
||
max_age: 30 # 天
|
||
compress: true
|
||
```
|
||
|
||
数据文件：
|
||
- `~/.nex/config.yaml` - 配置文件
|
||
- `~/.nex/config.db` - SQLite 数据库
|
||
- `~/.nex/log/` - 日志目录
|
||
|
||
## 测试
|
||
|
||
### 后端测试
|
||
|
||
```bash
|
||
cd backend
|
||
make test # 运行所有测试
|
||
make test-coverage # 生成覆盖率报告
|
||
```
|
||
|
||
### 前端测试
|
||
|
||
```bash
|
||
cd frontend
|
||
bun run test # 单元测试 + 组件测试
|
||
bun run test:watch # 监听模式
|
||
bun run test:coverage # 生成覆盖率报告
|
||
bun run test:e2e # E2E 测试
|
||
```
|
||
|
||
## 开发
|
||
|
||
### 后端开发
|
||
|
||
```bash
|
||
cd backend
|
||
make build # 构建
|
||
make lint # 代码检查
|
||
make migrate-up # 数据库迁移
|
||
```
|
||
|
||
### 前端开发
|
||
|
||
```bash
|
||
cd frontend
|
||
bun run build # 构建生产版本
|
||
bun run lint # 代码检查
|
||
```
|
||
|
||
## 开发规范
|
||
|
||
详见各子项目的 README.md：
|
||
- [后端 README](backend/README.md) - 分层架构、依赖注入、数据库迁移
|
||
- [前端 README](frontend/README.md) - TypeScript strict、SCSS Modules、测试策略
|
||
|
||
## 许可证
|
||
|
||
MIT
|