188c02478b
- SRS/SDD/README/PROGRESS 统一将部署目标由"美国服务器"更正为"NAS 本机 + 甲骨文服务器反向代理"（此前已确认但未入库） - 新增 docker-compose.yml / nginx.conf / .env.example（对应待办任务4） - 相对 SDD 草稿的安全加固：one-api 端口改绑 127.0.0.1（原为公网端口映射），lobe-chat 不再发布主机端口，仅走容器内网
203 lines
8.5 KiB
Markdown
203 lines
8.5 KiB
Markdown
# NexusAI — 自建多模态 AI 网关系统（AI Gateway System）
|
||
|
||
> 聚合多家免费多模态 AI API 的统一对话网关：Nginx + LobeChat + One-API + MySQL 容器化部署。
|
||
> 单一渠道不可用时自动故障转移（Failover），用户无感知。
|
||
> 最后更新：2026-08-23（文档入库，尚未部署）
|
||
|
||
---
|
||
|
||
## 1. 项目简介与设计目标
|
||
|
||
公司内网直连 NVIDIA NIM、Gemini 等免费大模型 API 不稳定，本系统**部署在 NAS 本机**（Docker Compose），聚合 5 家免费多模态 API（Gemini、NVIDIA NIM、Groq、OpenRouter、Mistral），通过 One-API 网关统一路由，实现"一个渠道不可用自动切换下一个"的高可用能力，并提供接近 Gemini 首页体验的 Web 对话界面（LobeChat），支持图片 + 文字混合输入问答；对外由**甲骨文服务器（129.146.203.203）反向代理端口**提供访问（与 FAM 项目 frp 方案一致）。
|
||
|
||
### 1.1 核心价值
|
||
|
||
- **聚合免费额度 + 高可用**：用户只需在统一界面提问/上传图片，无需关心调用哪家模型
|
||
- **配置驱动**：渠道增删、优先级调整通过 One-API 后台界面完成，不改代码
|
||
- **全部免费**：仅使用各平台免费额度，不产生 API 调用费用
|
||
|
||
### 1.2 文档
|
||
|
||
- [软件需求规格说明书（SRS）V1.0](docs/01-软件需求文档-SRS.md)
|
||
- [软件设计说明书（SDD）V1.0](docs/02-软件设计文档-SDD.md)
|
||
|
||
---
|
||
|
||
## 2. 系统架构
|
||
|
||
```
|
||
浏览器 / 移动端浏览器（公司内网）
|
||
│ HTTPS (443)
|
||
▼
|
||
甲骨文服务器（129.146.203.203）—— frp/nginx 反代端口（对外统一入口）
|
||
│ 反代 / 隧道（frp）
|
||
▼
|
||
NAS 本机（Docker 宿主机）
|
||
├─ Nginx（HTTPS 终止，流式透传）──► LobeChat（:3210）──► One-API（:3000 仅内网）──► MySQL
|
||
│
|
||
▼ NAS 出站直连海外 API
|
||
Gemini · NVIDIA NIM · Groq · OpenRouter · Mistral
|
||
```
|
||
|
||
| 层级 | 组件 | 职责 |
|
||
|---|---|---|
|
||
| 反代层 | 甲骨文服务器 | frp/nginx 反向代理端口，对外统一访问入口 |
|
||
| 接入层 | Nginx | HTTPS 终止、反向代理（NAS 本机） |
|
||
| 表现层 | LobeChat | 对话界面渲染、图片上传、Access Code 鉴权、对话历史（IndexedDB） |
|
||
| 网关层 | One-API | 协议转换、渠道路由、Failover、用量统计 |
|
||
| 数据层 | MySQL | 渠道配置 / Token / 调用日志持久化 |
|
||
|
||
### 2.1 渠道设计（优先级数字越小越优先）
|
||
|
||
| 渠道名 | Base URL | 优先级 | 支持视觉 |
|
||
|---|---|---|---|
|
||
| nvidia-nim | integrate.api.nvidia.com/v1 | 1 | 部分模型 |
|
||
| gemini | generativelanguage.googleapis.com/v1beta | 1 | 是 |
|
||
| openrouter | openrouter.ai/api/v1 | 2 | 部分模型(:free) |
|
||
| groq | api.groq.com/openai/v1 | 2 | 有限 |
|
||
| mistral | api.mistral.ai/v1 | 3 | Pixtral 系列 |
|
||
|
||
### 2.2 模型映射（前端只感知两个聚合模型名）
|
||
|
||
| 对外模型名 | 用途 | 关联渠道 |
|
||
|---|---|---|
|
||
| `auto-vision` | 图文混合问答 | Gemini、NVIDIA(视觉模型)、OpenRouter(视觉模型)、Mistral(Pixtral) |
|
||
| `auto-text` | 纯文本问答 | 上述全部 + Groq |
|
||
|
||
### 2.3 故障转移策略
|
||
|
||
1. 请求按 `auto-vision` / `auto-text` 匹配渠道池，按优先级从高到低尝试
|
||
2. 渠道返回 429/5xx/超时 → 标记本次失败，自动尝试下一渠道
|
||
3. 连续失败超阈值 → 渠道进入"冷却禁用"，冷却期后自动恢复
|
||
4. 全部渠道失败 → 向前端返回明确错误提示（不静默失败）
|
||
|
||
---
|
||
|
||
## 3. 部署概览
|
||
|
||
- **部署位置**：NAS 本机（Synology DSM 7，Docker Compose / ContainerManager）
|
||
- **对外访问**：甲骨文服务器（129.146.203.203）frp/nginx 反向代理端口 → NAS 的 Nginx 443
|
||
- **方式**：所有服务在同一 `ai-network` 内，仅 Nginx 80/443 对局域网暴露
|
||
- **目录结构**：`docker-compose.yml` / `.env`（敏感变量，不入库）/ `nginx.conf` / `certs/` / `one-api-data/` / `mysql-data/`
|
||
- **详细部署步骤**：见 [SDD 第 6 章](docs/02-软件设计文档-SDD.md#6-部署设计)
|
||
|
||
### 3.1 容器服务
|
||
|
||
| 服务 | 镜像 | 端口 | 说明 |
|
||
|---|---|---|---|
|
||
| nginx | nginx:alpine | 80/443（NAS 局域网） | HTTPS 终止、反向代理 |
|
||
| lobe-chat | lobehub/lobe-chat:latest | 3210（内网） | 前端对话界面 |
|
||
| one-api | justsong/one-api:latest | 3000（内网） | 网关聚合层 |
|
||
| mysql | mysql:8.0 | 3306（内网） | One-API 数据存储 |
|
||
|
||
### 3.2 安全要点
|
||
|
||
- 对外仅暴露甲骨文服务器反代端口，NAS 本机不直接暴露公网
|
||
- One-API 后台端口（3000）不映射公网，远程管理走 SSH 隧道 / VPN
|
||
- 所有 API Key 通过服务器 `.env` 注入容器环境变量，`.env` 不入库（见 [SDD 第 5 章](docs/02-软件设计文档-SDD.md#5-安全设计)）
|
||
- 前端强制 `ACCESS_CODE` 校验；Nginx 全站 HTTPS
|
||
|
||
---
|
||
|
||
## 4. 服务器访问信息
|
||
|
||
### 4.1 Synology NAS（AI 网关部署目标 + FAM + Gitea）
|
||
|
||
| 项目 | 值 |
|
||
|---|---|
|
||
| IP | 192.168.50.64 |
|
||
| SSH 端口 | 2222（scp 禁用，用 stdin 管道传文件） |
|
||
| SSH 用户 / 密码 | ericwyuan / iLoveJava5 |
|
||
| 系统 | Synology DS220+ (Geminilake), DSM 7 |
|
||
| Tailscale IP | 100.70.234.39（userspace 模式，端口不通待修） |
|
||
| 登录命令 | `ssh -p 2222 ericwyuan@192.168.50.64` |
|
||
|
||
### 4.2 MariaDB（NAS）
|
||
|
||
| 项目 | 值 |
|
||
|---|---|
|
||
| 版本 | MariaDB 10.11.11 |
|
||
| Socket | /run/mysqld/mysqld10.sock |
|
||
| Root 密码 | iLoveJava5! |
|
||
| 连接 | `/usr/local/mariadb10/bin/mysql -S /run/mysqld/mysqld10.sock -u root -p` |
|
||
|
||
### 4.3 Oracle Cloud（反代层，129.146.203.203）
|
||
|
||
| 项目 | 值 |
|
||
|---|---|
|
||
| 公网 IP | 129.146.203.203 |
|
||
| SSH 用户 | ubuntu（密钥 `~/.ssh/oracle_sentinel`） |
|
||
| 系统 | aarch64 (Ampere A1 2C12G), Ubuntu 20.04 LTS |
|
||
| Tailscale | 100.74.137.126（已安装在线，与 NAS 端口不通） |
|
||
| 登录命令 | `ssh -i ~/.ssh/oracle_sentinel ubuntu@129.146.203.203` |
|
||
| 反代职责 | frp/nginx 反代公网端口 → NAS AI 网关入口 |
|
||
|
||
### 4.4 Gitea 代码仓库
|
||
|
||
| 项目 | 值 |
|
||
|---|---|
|
||
| URL | http://192.168.50.64:3000/ericwyuan/NexusAI |
|
||
| 账号 / 密码 | ericwyuan / iLoveJava5 |
|
||
|
||
---
|
||
|
||
## 5. AI 渠道 API Key（服务器 `.env` 管理，不入库）
|
||
|
||
> ⚠️ Gemini 与 NVIDIA 的 Key 将申请新值，此处不写入旧 Key，配置于 NAS `.env` 的占位变量。
|
||
|
||
| 渠道 | 模型 / 端点 | Key 环境变量（NAS .env） |
|
||
|---|---|---|
|
||
| Gemini | `generativelanguage.googleapis.com/v1beta`，模型 `gemini-flash-latest` | `${GEMINI_API_KEY}`（新 Key 待申请） |
|
||
| NVIDIA NIM | `integrate.api.nvidia.com/v1`，默认 `meta/llama-3.2-11b-vision-instruct` | `${NVIDIA_API_KEY}`（新 Key 待申请） |
|
||
| Groq | `api.groq.com/openai/v1` | `${GROQ_API_KEY}` |
|
||
| OpenRouter | `openrouter.ai/api/v1` | `${OPENROUTER_API_KEY}` |
|
||
| Mistral | `api.mistral.ai/v1` | `${MISTRAL_API_KEY}` |
|
||
|
||
> 各渠道 Key 申请后填入 NAS `.env`，One-API 后台添加渠道时引用，切勿提交版本库。
|
||
|
||
---
|
||
|
||
## 6. 提交规范（AI Agent 必读）
|
||
|
||
**工作流程（强制）**：
|
||
|
||
1. **开工前**：仓库根目录 `git pull --rebase`
|
||
2. **每完成一项验收子任务**：立即 `git add` + `git commit` + `git push`，一任务一 commit，不批量合并
|
||
3. **遇到阻塞**：先 commit 可工作部分，message 加 `[WIP]` 前缀
|
||
4. **修 Bug**：单独 commit，格式 `fix(模块): 问题简述`
|
||
|
||
**commit message 格式**：
|
||
|
||
- 任务：`[阶段X.Y子任务号] 子任务名称 - 完成内容简述`
|
||
- Bug：`fix(模块): 问题简述`
|
||
- 性能/文档：`perf(...)` / `docs(...)`
|
||
|
||
**禁止**：不 commit 直接继续；一次 commit 多个子任务；`git push --force`；跳过 hooks（`--no-verify`）。
|
||
|
||
**自检清单**：任务对应哪一行验收标准？是否已 commit + push？message 是否合规？开工前是否 pull --rebase？
|
||
|
||
---
|
||
|
||
## 7. 当前进度与待办
|
||
|
||
### 已完成（截至 2026-08-23）
|
||
|
||
- 软件需求文档（SRS V1.0）与软件设计文档（SDD V1.0）入库（`docs/`）
|
||
- 项目仓库初始化（Gitea: ericwyuan/NexusAI）
|
||
|
||
### 待办（见 SDD 第 8 章待确认事项）
|
||
|
||
| # | 任务 | 优先级 |
|
||
|---|------|--------|
|
||
| 1 | 验证 NAS 到各海外 API 官方域名的直连稳定性 | 高 |
|
||
| 2 | 申请新 Gemini / NVIDIA API Key | 高 |
|
||
| 3 | 确认 Oracle 反代方式（frp 隧道 vs nginx 反代） | 高 |
|
||
| 4 | ~~生成部署骨架（docker-compose.yml / nginx.conf / .env.example）~~ 已完成 | 高 |
|
||
| 5 | NAS 实际部署 + One-API 渠道配置 + Failover 验证 | 高 |
|
||
| 6 | 确认 HTTPS 域名与证书方案 | 中 |
|
||
| 7 | 确认 Server-Side 模式 / 管理端口访问方式 / 监控方案 | 中 |
|
||
|
||
---
|
||
|
||
文档结束
|