lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity

docs: 更新后端文档细节和内容

Browse Source
This commit is contained in:
兰缘小妖
2026-04-20 19:47:41 +08:00
parent 3fa5827de3
commit 1ae9336cbe
1 changed files with 55 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
backend/README.md
View File

@@ -26,7 +26,7 @@ AI 网关后端服务，提供统一的大模型 API 代理接口。
- **ORM**: GORM
- **数据库**: SQLite
- **日志**: zap + lumberjack
- **配置**: gopkg.in/yaml.v3
- **配置**: Viper + pflag（多层配置：CLI > 环境变量 > 配置文件 > 默认值）
- **验证**: go-playground/validator/v10
- **迁移**: goose
@@ -39,7 +39,7 @@ backend/
│ └── main.go # 主程序入口（依赖注入）
├── internal/
│ ├── config/ # 配置管理
│ │ ├── config.go # 配置加载/保存/验证
│ │ ├── config.go # Viper 多层配置加载/验证
│ │ └── models.go # GORM 数据模型
│ ├── domain/ # 领域模型
│ │ ├── provider.go
@@ -47,17 +47,17 @@ backend/
│ │ ├── stats.go
│ │ └── route.go
│ ├── handler/ # HTTP 处理器
│ │ ├── middleware/ # 中间件
│ │ ├── middleware/ # 中间件
│ │ │ ├── request_id.go
│ │ │ ├── logging.go
│ │ │ ├── recovery.go
│ │ │ └── cors.go
│ │ ├── proxy_handler.go # 统一代理处理器
│ │ ├── proxy_handler.go # 统一代理处理器
│ │ ├── provider_handler.go
│ │ ├── model_handler.go
│ │ └── stats_handler.go
│ ├── conversion/ # 协议转换引擎
│ │ ├── canonical/ # Canonical Model
│ ├── conversion/ # 协议转换引擎
│ │ ├── canonical/ # Canonical Model
│ │ │ ├── types.go # 核心请求/响应类型
│ │ │ ├── stream.go # 流式事件类型
│ │ │ └── extended.go # 扩展层 Models
@@ -111,13 +111,12 @@ backend/
│ └── validator/ # 验证器
│ └── validator.go
├── migrations/ # 数据库迁移
│ ├── 001_initial_schema.sql
│ └── 002_add_indexes.sql
├── tests/ # 测试
│ ├── 20260401000001_initial_schema.sql
│ ├── 20260401000002_add_indexes.sql
│ └── 20260419000001_add_provider_protocol.sql
├── tests/ # 集成测试
│ ├── helpers.go
│ ├── integration/
│ ├── unit/
│ └── testdata/
│ └── integration/
├── Makefile
├── go.mod
└── README.md
@@ -133,6 +132,19 @@ handler（HTTP 请求处理）
→ repository（数据访问）
```
代理请求通过 ConversionEngine 进行协议转换：
```
Client Request (clientProtocol)
→ ProxyHandler 路由到上游 provider
→ ConversionEngine 请求转换 (clientProtocol → providerProtocol)
→ ProviderClient 发送请求
→ ConversionEngine 响应转换 (providerProtocol → clientProtocol)
→ Client Response
```
同协议时自动透传，跳过序列化开销。
## 运行方式
### 安装依赖
@@ -186,78 +198,44 @@ log:
export NEX_SERVER_PORT=9000
export NEX_DATABASE_PATH=/data/nex.db
export NEX_LOG_LEVEL=debug
./server
```
环境变量命名规则：将配置路径转换为大写，用下划线连接，加 `NEX_` 前缀：
- `server.port` → `NEX_SERVER_PORT`
- `database.path` → `NEX_DATABASE_PATH`
- `log.level` → `NEX_LOG_LEVEL`
命名规则：配置路径转大写 + 下划线 + `NEX_` 前缀（如 `server.port` → `NEX_SERVER_PORT`）。
### 命令行参数
所有配置项都支持命令行参数：
```bash
./server --server-port 9000 --log-level debug --database-path /tmp/test.db
```
CLI 参数命名规则：将配置路径转换为 kebab-case，用连字符连接：
- `server.port` → `--server-port`
- `database.path` → `--database-path`
- `log.level` → `--log-level`
命名规则：配置路径转 kebab-case + `--` 前缀（如 `server.port` → `--server-port`）。
完整参数列表：
```
服务器配置:
--server-port int 服务器端口（默认 9826）
--server-read-timeout duration 读超时（默认 30s）
--server-write-timeout duration 写超时（默认 30s）
数据库配置:
--database-path string 数据库文件路径（默认 ~/.nex/config.db）
--database-max-idle-conns int 最大空闲连接数（默认 10）
--database-max-open-conns int 最大打开连接数（默认 100）
--database-conn-max-lifetime duration 连接最大生命周期（默认 1h）
日志配置:
--log-level string 日志级别：debug/info/warn/error（默认 info）
--log-path string 日志文件目录（默认 ~/.nex/log）
--log-max-size int 单个日志文件最大大小 MB（默认 100）
--log-max-backups int 保留的旧日志文件最大数量（默认 10）
--log-max-age int 保留旧日志文件的最大天数（默认 30）
--log-compress 是否压缩旧日志文件（默认 true）
通用选项:
--config string 配置文件路径（默认 ~/.nex/config.yaml）
服务器: --server-port, --server-read-timeout, --server-write-timeout
数据库: --database-path, --database-max-idle-conns, --database-max-open-conns, --database-conn-max-lifetime
日志: --log-level, --log-path, --log-max-size, --log-max-backups, --log-max-age, --log-compress
通用: --config (指定配置文件路径)
```
### 使用示例
```bash
# 1. 使用默认配置
# 默认配置
./server
# 2. 临时修改端口（不修改配置文件）
# 临时修改端口
./server --server-port 9000
# 3. 测试场景（临时数据库）
# 测试场景
./server --database-path /tmp/test.db --log-level debug
# 4. Docker 部署（环境变量）
docker run -d \
-e NEX_SERVER_PORT=9000 \
-e NEX_DATABASE_PATH=/data/nex.db \
-e NEX_LOG_LEVEL=info \
nex-server
# Docker 部署
docker run -d -e NEX_SERVER_PORT=9000 -e NEX_LOG_LEVEL=info nex-server
# 5. 使用自定义配置文件
# 自定义配置文件
./server --config /path/to/custom.yaml
# 6. 混合使用（优先级：CLI > ENV > File）
export NEX_LOG_LEVEL=debug
./server --server-port 9000 # port 用 CLI，log.level 用 ENV
```
数据文件：
@@ -283,6 +261,9 @@ make migrate-up DB_PATH=~/.nex/config.db
make migrate-down DB_PATH=~/.nex/config.db
make migrate-status DB_PATH=~/.nex/config.db
# 创建新迁移
make migrate-create
# 或直接使用 goose
goose -dir migrations sqlite3 ~/.nex/config.db up
```
@@ -293,7 +274,7 @@ goose -dir migrations sqlite3 ~/.nex/config.db up
使用 `/{protocol}/v1/{path}` URL 前缀路由：
#### OpenAI 协议代理
#### OpenAI 协议
```
POST /openai/v1/chat/completions
@@ -302,37 +283,13 @@ POST /openai/v1/embeddings
POST /openai/v1/rerank
```
请求示例：
```json
{
"model": "gpt-4",
"messages": [
{"role": "user", "content": "Hello"}
],
"stream": false
}
```
#### Anthropic 协议代理
#### Anthropic 协议
```
POST /anthropic/v1/messages
GET /anthropic/v1/models
```
请求示例：
```json
{
"model": "claude-3-opus",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": [{"type": "text", "text": "Hello"}]}
]
}
```
**协议转换**：网关支持任意协议间的双向转换。客户端使用 OpenAI 协议请求，上游供应商可以是 Anthropic 协议（反之亦然）。同协议时自动透传，零序列化开销。
### 管理接口
@@ -345,8 +302,6 @@ GET /anthropic/v1/models
- `PUT /api/providers/:id` - 更新供应商
- `DELETE /api/providers/:id` - 删除供应商
创建供应商示例：
```json
{
"id": "openai",
@@ -357,15 +312,9 @@ GET /anthropic/v1/models
}
```
**Protocol 字段说明：**
- `protocol` 标识上游供应商使用的协议类型，可选值：`"openai"`（默认）、`"anthropic"`
- 同协议透传时，请求体和响应体原样转发，零序列化开销
**Protocol 字段**：标识上游供应商使用的协议类型，可选值 `"openai"`（默认）、`"anthropic"`。
**重要说明：**
- `base_url` 应配置到 API 版本路径，不包含具体端点
- OpenAI: `https://api.openai.com/v1`
- GLM: `https://open.bigmodel.cn/api/paas/v4`
- 其他 OpenAI 兼容供应商根据其文档配置版本路径
**base_url 说明**：应配置到 API 版本路径，不包含具体端点（如 OpenAI: `https://api.openai.com/v1`，GLM: `https://open.bigmodel.cn/api/paas/v4`）。
#### 模型管理
@@ -375,8 +324,6 @@ GET /anthropic/v1/models
- `PUT /api/models/:id` - 更新模型
- `DELETE /api/models/:id` - 删除模型
创建模型示例：
```json
{
"id": "gpt-4",
@@ -390,61 +337,43 @@ GET /anthropic/v1/models
- `GET /api/stats` - 查询统计
- `GET /api/stats/aggregate` - 聚合统计
查询参数：
查询参数：`provider_id`、`model_name`、`start_date`（YYYY-MM-DD）、`end_date`、`group_by`（provider/model/date）
- `provider_id` - 供应商 ID
- `model_name` - 模型名称
- `start_date` - 开始日期（YYYY-MM-DD）
- `end_date` - 结束日期（YYYY-MM-DD）
- `group_by` - 聚合维度（provider/model/date）
#### 健康检查
- `GET /health` - 返回 `{"status": "ok"}`
## 开发
### 构建
```bash
make build
make build # 构建
make lint # 代码检查
make deps # 整理依赖
```
### 代码检查
```bash
make lint
```
### 环境要求
- Go 1.26 或更高版本
环境要求：Go 1.26 或更高版本
## 公共库使用指南
### pkg/errors — 结构化错误
使用预定义的错误类型，配合 `errors.Is` / `errors.As` 判断错误：
```go
import (
"errors"
pkgErrors "nex/backend/pkg/errors"
)
// 使用预定义错误
return pkgErrors.ErrRequestSend.WithCause(err)
// 判断错误类型
var appErr *pkgErrors.AppError
if errors.As(err, &appErr) {
// appErr.Code, appErr.HTTPStatus, appErr.Message
}
```
可用函数：`NewAppError`、`Wrap`、`WithContext`、`WithMessage`、`AsAppError`
预定义错误：`ErrModelNotFound`、`ErrProviderNotFound`、`ErrInvalidRequest`、`ErrRequestCreate`、`ErrRequestSend`、`ErrResponseRead` 等
### pkg/logger — 日志系统
使用依赖注入模式，构造函数接受 `*zap.Logger` 参数，nil 时回退到 `zap.L()`：
构造函数接受 `*zap.Logger` 参数，nil 时回退到 `zap.L()`：
```go
func NewMyService(repo Repository, logger *zap.Logger) *MyService {
@@ -455,8 +384,6 @@ func NewMyService(repo Repository, logger *zap.Logger) *MyService {
}
```
禁止直接在业务代码中使用 `zap.L()` 全局 logger，应通过构造函数注入。
### pkg/validator — 请求验证
```go
@@ -468,8 +395,8 @@ err := v.Validate(myStruct)
## 编码规范
- **JSON 解析**：使用 `encoding/json` 标准库（`json.Unmarshal` / `json.Marshal`），不手动扫描字节
- **JSON 解析**：使用 `encoding/json` 标准库，不手动扫描字节
- **字符串拼接**：使用 `strings.Join`，不手写循环拼接
- **错误判断**：使用 `errors.Is` / `errors.As`，不使用字符串匹配（`strings.Contains(err.Error(), ...)`）
- **错误判断**：使用 `errors.Is` / `errors.As`，不使用字符串匹配
- **日志使用**：通过依赖注入 `*zap.Logger`，不直接调用 `zap.L()`
- **字符串分割**：使用 `strings.SplitN(key, "/", 2)` 等精确分割，不使用索引切片
- **字符串分割**：使用 `strings.SplitN` 等精确分割，不使用索引切片