lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
ebb70809bf2ebaf985082ba30dff81d75b8e26bf
nex/README.md
lanyuanxiaoyao 0b05e08705 feat: 新增桌面应用支持 
- 新增 desktop 应用入口，将后端与前端打包为单一可执行文件
- 集成系统托盘功能（getlantern/systray）
- 支持单实例锁和端口冲突检测
- 启动时自动打开浏览器显示管理界面
- 新增 embedfs 模块嵌入静态资源
- 新增跨平台构建脚本（macOS/Windows/Linux）
- 新增 macOS .app 打包脚本
- 统一 Makefile，移除 backend/Makefile
- 更新 README 添加桌面应用使用说明
2026-04-22 19:27:27 +08:00

243 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Nex - AI Gateway
一个统一的大模型 API 网关，支持 OpenAI 和 Anthropic 双协议，让应用只需配置一个地址即可透明使用多个供应商的大模型服务。
## 项目结构
```
nex/
├── backend/ # Go 后端服务（分层架构）
│ ├── cmd/
│ │ ├── server/ # CLI 主程序入口
│ │ └── desktop/ # 桌面应用入口
│ ├── 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
│
├── assets/ # 应用资源
│ ├── icon.png # 托盘图标
│ ├── AppIcon.icns # macOS 应用图标
│ └── icon.ico # Windows 应用图标
│
├── scripts/ # 构建脚本
│ └── build/
│ └── package-macos.sh # macOS .app 打包脚本
│
└── README.md # 本文件
```
## 功能特性
- **双协议支持**：同时支持 OpenAI 和 Anthropic 协议
- **统一模型 ID**：`provider_id/model_name` 格式全局唯一标识模型（如 `openai/gpt-4`）
- **透明代理**：对 OpenAI 兼容供应商 Smart Passthrough，最小化改写保持参数保真
- **流式响应**：完整支持 SSE 流式传输
- **Function Calling**：支持工具调用（Tools）
- **多供应商管理**：配置和管理多个供应商（供应商 ID 仅限字母、数字、下划线）
- **用量统计**：按供应商、模型、日期统计请求数量
- **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 组件库**: TDesign React
- **图表库**: Recharts
- **路由**: React Router v7
- **数据获取**: TanStack Query v5
- **样式**: SCSS Modules
- **测试**: Vitest + React Testing Library + Playwright
## 快速开始
### 桌面应用（推荐）
**构建桌面应用**：
```bash
# 当前平台
make desktop
# macOS (arm64 + amd64)
make desktop-darwin
make package-macos # 打包为 .app
# Windows
make desktop-windows
# Linux
make desktop-linux
```
**使用桌面应用**：
- 双击启动应用（macOS: Nex.app，Windows: nex.exe，Linux: nex）
- 系统托盘图标出现，浏览器自动打开管理界面
- 点击托盘图标显示菜单，可打开管理界面或退出
- 关闭浏览器后服务继续运行，可通过托盘重新打开
**注意事项**：
- 桌面应用需要 CGO 支持
- macOS: 自带 Xcode Command Line Tools
- Linux: 自带 gcc，部分桌面环境需要 `libappindicator3-dev`
- Windows: 需要 MinGW-w64 或在 Windows 环境构建
**Linux 桌面环境兼容性**：
- GNOME: 需要 AppIndicator 扩展
- KDE Plasma: 原生支持
- Xfce: 需要 libappindicator
- 其他支持 StatusNotifierItem 规范的环境
### CLI 模式
#### 后端
```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 接口
### 代理接口（对外部应用）
代理接口统一使用 `provider_id/model_name` 格式的模型 ID（如 `openai/gpt-4`）。同协议请求走 Smart Passthrough，最小化 JSON 改写保持参数保真；跨协议请求走完整 decode/encode 转换。
- `POST /v1/chat/completions` - OpenAI Chat Completions API
- `POST /v1/messages` - Anthropic Messages API
- `GET /v1/models` - 模型列表（本地数据库聚合，不请求上游）
- `GET /v1/models/{provider_id}/{model_name}` - 模型详情（本地数据库查询）
### 管理接口（对前端）
#### 供应商管理
- `GET /api/providers` - 列出所有供应商
- `POST /api/providers` - 创建供应商（`id` 仅限字母、数字、下划线，长度 1-64）
- `GET /api/providers/:id` - 获取供应商
- `PUT /api/providers/:id` - 更新供应商（`id` 不可修改）
- `DELETE /api/providers/:id` - 删除供应商
#### 模型管理
- `GET /api/models` - 列出模型（支持 `?provider_id=xxx` 过滤）
- `POST /api/models` - 创建模型（`id` 由系统自动生成 UUID，`provider_id` + `model_name` 联合唯一）
- `GET /api/models/:id` - 获取模型（响应含 `unified_id` 字段，格式 `provider_id/model_name`）
- `PUT /api/models/:id` - 更新模型（不可修改 `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
make backend-test # 后端测试
make backend-test-coverage # 后端覆盖率
make frontend-test # 前端测试
make frontend-test-e2e # 前端 E2E 测试
```
## 开发
```bash
make backend-build # 构建后端
make backend-run # 运行后端
make backend-lint # 后端代码检查
make backend-migrate-up # 数据库迁移
make frontend-build # 构建前端
make frontend-dev # 前端开发模式
make frontend-lint # 前端代码检查
```
## 开发规范
详见各子项目的 README.md：
- [后端 README](backend/README.md) - 分层架构、依赖注入、数据库迁移
- [前端 README](frontend/README.md) - TypeScript strict、SCSS Modules、测试策略
## 许可证
MIT
View Git Blame Copy Permalink