a4421d76b4
- 与 Gitea(3000)/WordPress(8500)/FAM-core(8000) 保持同一约定：每个服务用专属端口而非默认 443 - NAS frpc.toml 的 nexusai 代理 remotePort 由 443 改为 3210，已重启 frpc 并验证 https://129.146.203.203:3210/ 端到端可访问 - 同步更新 README/PROGRESS/SDD 中所有相关端口引用
382 lines
18 KiB
Markdown
382 lines
18 KiB
Markdown
# 软件设计说明书（SDD）
|
||
## 自建多模态 AI 网关系统（AI Gateway System）
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 文档版本 | V1.0 |
|
||
| 编写日期 | 2026-08-23 |
|
||
| 对应需求文档 | 01-软件需求文档-SRS.md V1.0 |
|
||
|
||
---
|
||
|
||
## 1. 设计概述
|
||
|
||
### 1.1 设计目标
|
||
|
||
在满足 SRS 中全部功能需求与非功能需求的前提下，采用**成熟开源组件 + 容器化编排**的方式快速搭建系统，降低自研成本，优先保证 Failover 可靠性与部署可维护性。
|
||
|
||
### 1.2 设计原则
|
||
|
||
- **不重复造轮子**：网关、前端均采用成熟开源方案（One-API + LobeChat），仅做配置层工作
|
||
- **松耦合**：前端、网关、各 AI 渠道之间通过标准 OpenAI 兼容接口通信，任一组件可替换
|
||
- **配置驱动**：渠道增删、优先级调整通过后台界面完成，不需改代码重新部署
|
||
- **最小暴露面**：仅前端端口对公网开放，管理端口和数据库端口仅内网可访问
|
||
|
||
---
|
||
|
||
## 2. 系统架构设计
|
||
|
||
### 2.1 总体架构图
|
||
|
||
```
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ 公司内网（用户侧） │
|
||
│ 浏览器 / 移动端浏览器 │
|
||
└──────────────────────────┬────────────────────────────────────┘
|
||
│ HTTPS (443)
|
||
▼
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ 甲骨文服务器（129.146.203.203，公网反代层） │
|
||
│ frp / nginx 反向代理端口 → NAS（对外统一入口） │
|
||
└──────────────────────────┬────────────────────────────────────┘
|
||
│ 反代 / 隧道（frp）
|
||
▼
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ NAS 本机（Docker 宿主机） │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ Nginx（反向代理层） │ │
|
||
│ │ - HTTPS 终止 / 证书管理 │ │
|
||
│ │ - 请求转发至 LobeChat │ │
|
||
│ │ - 流式响应透传（proxy_buffering off） │ │
|
||
│ └───────────────────────┬─────────────────────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ LobeChat（前端应用层） 端口 3210 │ │
|
||
│ │ - 对话界面渲染 │ │
|
||
│ │ - 图片上传处理 │ │
|
||
│ │ - Access Code 鉴权 │ │
|
||
│ │ - 对话历史管理（IndexedDB / PostgreSQL） │ │
|
||
│ └───────────────────────┬─────────────────────────────────┘ │
|
||
│ │ OpenAI 兼容协议 │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ One-API（网关聚合层） 端口 3000（仅内网） │ │
|
||
│ │ - 渠道管理 / 优先级路由 │ │
|
||
│ │ - 模型名映射 │ │
|
||
│ │ - 失败重试 / 自动禁用 / 冷却恢复 │ │
|
||
│ │ - 调用日志 / 用量统计 │ │
|
||
│ └───────────────────────┬─────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ MySQL（网关数据存储） │ │
|
||
│ │ - 渠道配置表 / Token 表 / 调用日志表 │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────┬────────────────────────────────────┘
|
||
│ 各家官方 HTTPS API
|
||
┌───────────┬───────────┬───────────┬───────────┐
|
||
▼ ▼ ▼ ▼ ▼
|
||
Gemini NVIDIA NIM Groq OpenRouter Mistral
|
||
```
|
||
|
||
### 2.2 分层说明
|
||
|
||
| 层级 | 组件 | 职责 |
|
||
|---|---|---|
|
||
| 反代层 | 甲骨文服务器 | frp/nginx 反向代理端口，对外统一访问入口 |
|
||
| 接入层 | Nginx | HTTPS 终止、反向代理、访问入口统一（NAS 本机） |
|
||
| 表现层 | LobeChat | 用户交互、对话渲染、多模态输入采集 |
|
||
| 网关层 | One-API | 协议转换、渠道路由、故障转移、用量统计 |
|
||
| 数据层 | MySQL | 网关配置与日志持久化 |
|
||
| 外部服务层 | 5 家 AI API | 实际推理能力提供方 |
|
||
|
||
### 2.3 部署视图
|
||
|
||
单机 Docker Compose 部署于 **NAS 本机**，各服务以容器形式运行在同一 Docker 网络（`ai-network`）内，服务间通过容器名互相寻址，仅 Nginx 的 80/443 端口对局域网暴露；对外由**甲骨文服务器（129.146.203.203）**通过 frp/nginx 反向代理该端口，供公司内网公网访问。
|
||
|
||
---
|
||
|
||
## 3. 模块设计
|
||
|
||
### 3.1 Nginx 反向代理模块
|
||
|
||
**职责**
|
||
- 在 NAS 本机暴露 443（HTTPS）与 80（HTTP 跳转 443）；公网访问由甲骨文服务器反向代理到本机 443 端口
|
||
- 将请求转发至 `lobe-chat:3210`
|
||
- 关闭代理缓冲以支持流式输出（SSE）
|
||
|
||
**关键配置片段**
|
||
```nginx
|
||
server {
|
||
listen 443 ssl;
|
||
server_name <domain-or-ip>;
|
||
|
||
ssl_certificate /etc/nginx/certs/fullchain.pem;
|
||
ssl_certificate_key /etc/nginx/certs/privkey.pem;
|
||
|
||
location / {
|
||
proxy_pass http://lobe-chat:3210;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_buffering off;
|
||
proxy_cache off;
|
||
}
|
||
}
|
||
|
||
server {
|
||
listen 80;
|
||
server_name <domain-or-ip>;
|
||
return 301 https://$host$request_uri;
|
||
}
|
||
```
|
||
|
||
### 3.2 LobeChat 前端模块
|
||
|
||
**职责**
|
||
- 渲染对话界面、处理用户输入（含图片）
|
||
- 通过 `OPENAI_PROXY_URL` 将请求发送至 One-API，而非直连任一具体厂商
|
||
- 校验 `ACCESS_CODE` 完成访问控制
|
||
|
||
**关键环境变量设计**
|
||
|
||
| 变量名 | 说明 | 示例值 |
|
||
|---|---|---|
|
||
| `OPENAI_API_KEY` | 填 One-API 生成的聚合 Token（非各厂商原始 Key） | `sk-xxxxx` |
|
||
| `OPENAI_PROXY_URL` | 指向 One-API 的 v1 路径 | `http://one-api:3000/v1` |
|
||
| `ACCESS_CODE` | 前端访问密码 | 自定义 |
|
||
| `DEFAULT_LANG` | 默认语言 | `zh-CN` |
|
||
| `OPENAI_MODEL_LIST` | 控制模型下拉菜单显示项 | 见 3.3 模型映射设计 |
|
||
|
||
**数据存储**：本期采用 Client-Side（IndexedDB），后续如需多端同步再切换 Server-Side（PostgreSQL）。
|
||
|
||
### 3.3 One-API 网关模块
|
||
|
||
**职责**
|
||
- 维护渠道（Channel）配置表：Base URL、Key、支持模型、优先级、权重
|
||
- 维护 Token 表：对外暴露给 LobeChat 使用的聚合密钥
|
||
- 请求路由：按优先级+权重选择渠道，失败时按策略重试下一渠道
|
||
- 日志记录：每次请求实际路由渠道、耗时、成功/失败状态
|
||
|
||
**渠道设计表**
|
||
|
||
| 渠道名 | 类型 | Base URL | 优先级 | 支持视觉 |
|
||
|---|---|---|---|---|
|
||
| nvidia-nim | 自定义(OpenAI兼容) | `integrate.api.nvidia.com/v1` | 1 | 部分模型 |
|
||
| gemini | Google Gemini | `generativelanguage.googleapis.com/v1beta` | 1 | 是 |
|
||
| openrouter | 自定义(OpenAI兼容) | `openrouter.ai/api/v1` | 2 | 部分模型(:free) |
|
||
| groq | 自定义(OpenAI兼容) | `api.groq.com/openai/v1` | 2 | 有限 |
|
||
| mistral | 自定义(OpenAI兼容) | `api.mistral.ai/v1` | 3 | Pixtral系列 |
|
||
|
||
> 优先级数字越小越优先；同优先级内按权重轮询分摊负载。
|
||
|
||
**模型映射设计**
|
||
|
||
对外统一暴露两个聚合模型名，前端只需感知这两个名字：
|
||
|
||
| 对外模型名 | 用途 | 关联渠道 |
|
||
|---|---|---|
|
||
| `auto-vision` | 图文混合问答 | Gemini、NVIDIA(视觉模型)、OpenRouter(视觉模型)、Mistral(Pixtral) |
|
||
| `auto-text` | 纯文本问答 | 上述全部 + Groq |
|
||
|
||
**故障转移策略**
|
||
|
||
1. 请求到达 One-API，按 `auto-vision` 或 `auto-text` 匹配渠道池
|
||
2. 按优先级从高到低尝试，同优先级内按权重随机/轮询选择
|
||
3. 若渠道返回 429（限流）/5xx（服务错误）/超时，标记该渠道本次失败，自动尝试下一渠道
|
||
4. 连续失败次数超过阈值（如 5 次/5 分钟），该渠道进入"冷却禁用"状态，冷却期（如 10 分钟）后自动恢复参与路由
|
||
5. 全部渠道均失败时，向前端返回明确错误提示（而非静默失败）
|
||
|
||
### 3.4 MySQL 数据模块
|
||
|
||
**职责**：持久化 One-API 的渠道配置、Token、调用日志
|
||
|
||
**核心表设计（概念级，实际以 One-API 内建 schema 为准）**
|
||
|
||
| 表 | 关键字段 | 说明 |
|
||
|---|---|---|
|
||
| channels | id, name, base_url, key, priority, weight, models, status | 渠道配置 |
|
||
| tokens | id, key, name, quota, status | 对外令牌 |
|
||
| logs | id, channel_id, model, status_code, latency, created_at | 调用日志 |
|
||
|
||
---
|
||
|
||
## 4. 接口设计
|
||
|
||
### 4.1 前端 ↔ 网关接口
|
||
|
||
遵循 OpenAI `/v1/chat/completions` 协议，支持多模态 `content` 数组格式：
|
||
|
||
```json
|
||
{
|
||
"model": "auto-vision",
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": [
|
||
{ "type": "text", "text": "这张图片里有什么？" },
|
||
{ "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,..." } }
|
||
]
|
||
}
|
||
],
|
||
"stream": true
|
||
}
|
||
```
|
||
|
||
### 4.2 网关 ↔ 各 AI 渠道接口
|
||
|
||
| 渠道 | 协议特点 | 转换要点 |
|
||
|---|---|---|
|
||
| Gemini | 原生协议与 OpenAI 不同（`contents`/`parts`结构） | One-API 内建适配器自动转换 |
|
||
| NVIDIA NIM | OpenAI 兼容 | 直接透传，仅替换 Base URL 和 Key |
|
||
| Groq | OpenAI 兼容 | 直接透传 |
|
||
| OpenRouter | OpenAI 兼容 | 直接透传，模型名需带 `:free` 后缀 |
|
||
| Mistral | OpenAI 兼容 | 直接透传，视觉模型指定 `pixtral-*` |
|
||
|
||
---
|
||
|
||
## 5. 安全设计
|
||
|
||
| 风险点 | 设计对策 |
|
||
|---|---|
|
||
| 后台管理端口暴露 | One-API 的 3000 端口不映射到公网，仅容器内网可访问；Oracle 反代仅转发前端端口，管理端口走 SSH 隧道或 VPN |
|
||
| API Key 泄露 | 所有 Key 通过 `.env` 文件注入容器环境变量，`.env` 加入 `.gitignore`，不提交版本库 |
|
||
| 未授权访问前端 | LobeChat `ACCESS_CODE` 强制校验 |
|
||
| 传输层安全 | Nginx 强制 HTTPS，HTTP 请求 301 跳转 |
|
||
| 公网入口暴露 | 对外仅暴露甲骨文服务器反代端口，NAS 本机不直接暴露公网 |
|
||
| 密钥被盗用后的止损 | One-API 后台可随时吊销/轮换 Token，不影响各渠道原始 Key |
|
||
|
||
---
|
||
|
||
## 6. 部署设计
|
||
|
||
### 6.1 目录结构
|
||
|
||
```
|
||
~/ai-gateway/
|
||
├── docker-compose.yml
|
||
├── .env # 敏感变量，不提交版本库
|
||
├── nginx.conf
|
||
├── certs/ # HTTPS 证书
|
||
├── one-api-data/ # One-API 持久化数据
|
||
└── mysql-data/ # MySQL 持久化数据
|
||
```
|
||
|
||
### 6.2 Docker Compose 设计
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
one-api:
|
||
image: justsong/one-api:latest
|
||
container_name: one-api
|
||
restart: always
|
||
ports:
|
||
- "3000:3000" # 建议后续改为仅内网映射
|
||
volumes:
|
||
- ./one-api-data:/data
|
||
environment:
|
||
- SQL_DSN=root:${MYSQL_ROOT_PASSWORD}@tcp(mysql:3306)/oneapi
|
||
- TZ=Asia/Shanghai
|
||
depends_on:
|
||
- mysql
|
||
networks:
|
||
- ai-network
|
||
|
||
mysql:
|
||
image: mysql:8.0
|
||
container_name: one-api-mysql
|
||
restart: always
|
||
environment:
|
||
- MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
|
||
- MYSQL_DATABASE=oneapi
|
||
volumes:
|
||
- ./mysql-data:/var/lib/mysql
|
||
networks:
|
||
- ai-network
|
||
|
||
lobe-chat:
|
||
image: lobehub/lobe-chat:latest
|
||
container_name: lobe-chat
|
||
restart: always
|
||
ports:
|
||
- "3210:3210"
|
||
environment:
|
||
- OPENAI_API_KEY=${ONE_API_TOKEN}
|
||
- OPENAI_PROXY_URL=http://one-api:3000/v1
|
||
- ACCESS_CODE=${LOBE_ACCESS_CODE}
|
||
- DEFAULT_LANG=zh-CN
|
||
depends_on:
|
||
- one-api
|
||
networks:
|
||
- ai-network
|
||
|
||
nginx:
|
||
image: nginx:alpine
|
||
container_name: nginx-proxy
|
||
restart: always
|
||
ports:
|
||
- "80:80"
|
||
- "443:443"
|
||
volumes:
|
||
- ./nginx.conf:/etc/nginx/nginx.conf:ro
|
||
- ./certs:/etc/nginx/certs:ro
|
||
depends_on:
|
||
- lobe-chat
|
||
networks:
|
||
- ai-network
|
||
|
||
networks:
|
||
ai-network:
|
||
driver: bridge
|
||
```
|
||
|
||
### 6.3 部署步骤
|
||
|
||
1. NAS 安装 Docker + Docker Compose（ContainerManager）
|
||
2. 按 6.1 结构创建目录，放置 `docker-compose.yml`、`.env`、`nginx.conf`
|
||
3. 申请 HTTPS 证书（Let's Encrypt/certbot）放入 `certs/`
|
||
4. 执行 `docker-compose up -d` 启动全部服务
|
||
5. 访问 `http://<NAS-IP>:3000` 完成 One-API 初始化（设置管理员密码）
|
||
6. 后台按 3.3 节渠道设计表逐个添加渠道，设置优先级
|
||
7. 创建对外 Token，写入 `.env` 的 `ONE_API_TOKEN`
|
||
8. `docker-compose restart lobe-chat` 使配置生效
|
||
9. 在甲骨文服务器配置 frp（或 nginx 反代）将公网端口转发至 NAS 的 Nginx 443 端口
|
||
10. 访问 `https://<域名>`（经甲骨文反代）验证前端可正常对话、上传图片、触发 Failover
|
||
|
||
### 6.4 运维监控设计
|
||
|
||
| 监控项 | 方式 |
|
||
|---|---|
|
||
| 渠道可用性 | One-API 后台"渠道"页面查看状态与最近调用日志 |
|
||
| 免费额度消耗 | 各厂商官方控制台 + One-API 用量统计页面双重核对 |
|
||
| 容器健康状态 | `docker-compose ps` / 可选接入 Prometheus+Grafana（后续扩展） |
|
||
| 证书到期提醒 | certbot 自动续期 + 到期前邮件提醒（后续扩展） |
|
||
|
||
---
|
||
|
||
## 7. 设计与需求追溯表
|
||
|
||
| SRS 需求编号 | 对应设计章节 |
|
||
|---|---|
|
||
| FR-1 统一对话界面 | 3.2 LobeChat 前端模块 |
|
||
| FR-2 多渠道聚合与路由 | 3.3 One-API 网关模块 |
|
||
| FR-3 多模态能力 | 3.3 模型映射设计 |
|
||
| FR-4 渠道管理 | 3.3 / 3.4 |
|
||
| FR-5 安全与访问控制 | 第 5 章 安全设计 |
|
||
| 非功能-可用性 | 3.3 故障转移策略 |
|
||
| 非功能-可维护性 | 6.4 运维监控设计 |
|
||
|
||
---
|
||
|
||
## 8. 待确认事项（2026-08-23 更新：已实际部署，多数事项已给出默认结论）
|
||
|
||
1. ~~是否需要 Server-Side 模式支持多端对话同步~~ **默认结论**：本期保持 Client-Side（IndexedDB），不额外部署 PostgreSQL；仅单用户/单浏览器使用，暂无多端同步需求。如后续需要，再单独排期
|
||
2. ~~后台管理端口是否需要通过 VPN/SSH 隧道访问~~ **已实施**：One-API 仅绑定 NAS `127.0.0.1:3001`，不接入 frp 隧道，不映射公网；远程管理走 `ssh -p 2222 -L 3001:127.0.0.1:3001 ericwyuan@192.168.50.64`
|
||
3. ~~是否需要接入 Prometheus/Grafana~~ **默认结论**：本期不接入，沿用 SDD 6.4 既定的轻量监控（`docker compose ps` + One-API 后台渠道页面）；用量不大，暂不需要额外可视化监控栈
|
||
4. **域名与证书**：尚未有正式域名，当前用**临时自签名证书**（`certs/fullchain.pem`/`privkey.pem`，CN=nexusai.local）跑通链路，浏览器会提示"不安全"但功能不受影响；若紫川后续购买/已有域名，替换证书为 Let's Encrypt 即可，无需改动其他组件——**此项仍待紫川决定是否购买域名**
|
||
5. ~~NAS 到各海外 API 官方域名的直连稳定性验证~~ **已完成（2026-08-23）**：五渠道 TCP/TLS 握手均 2 秒内完成，NAS 出站直连稳定，无需额外代理
|
||
6. ~~甲骨文反代方式确认~~ **已完成（2026-08-23）**：采用 frp 隧道（与 FAM 项目一致），复用 Oracle 上已运行的 `frps`，NAS `frpc.toml` 新增 `nexusai` 代理（remotePort **3210**（专属端口，非默认 443，与 gitea:3000/wordpress:8500/fam-core:8000 同一约定）→ NAS 8443），对外访问地址为 `https://129.146.203.203:3210`
|