# 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 隧道（frps 已运行，`frpc.toml` 追加 `nexusai` 代理）转发公网 443 → NAS 的 Nginx 容器（NAS 本机端口 8443）
- **方式**：所有服务在同一 `ai-network` 内；NAS 本机 80/443/3000 已被 Gitea/DSM 等既有服务占用，AI 网关改用 8443（nginx）与 3001（one-api，仅 127.0.0.1）
- **目录结构**：`docker-compose.yml` / `.env`（敏感变量，不入库）/ `nginx.conf` / `certs/` / `one-api-data/` / `mysql-data/`
- **详细部署步骤**：见 [SDD 第 6 章](docs/02-软件设计文档-SDD.md#6-部署设计)

### 3.1 容器服务

| 服务 | 镜像 | 端口（NAS 本机） | 说明 |
|---|---|---|---|
| nginx | nginx:alpine | 8443→443（经 frp 隧道对外） | HTTPS 终止、反向代理 |
| lobe-chat | lobehub/lobe-chat:latest | 未发布主机端口，仅容器内网 3210 | 前端对话界面 |
| one-api | justsong/one-api:latest | 127.0.0.1:3001→3000（仅本机回环） | 网关聚合层 |
| mysql | mysql:8.0 | 未发布主机端口，仅容器内网 3306 | One-API 数据存储 |

> NAS 本机 80/443/3000 已被 Gitea（3000）与其他既有服务（80/443）占用，故 AI 网关容器改用上表端口；甲骨文侧无需改动，frps 按 `frpc.toml` 中新增的 `[[proxies]] name="nexusai"` 动态接受 remotePort 443。

### 3.2 安全要点

- 对外仅暴露甲骨文服务器 frp 隧道转发的 443 端口，NAS 本机不直接暴露公网
- One-API 后台端口只绑定 `127.0.0.1:3001`，不接入 frp 隧道；远程管理走 SSH 隧道：`ssh -p 2222 -L 3001:127.0.0.1:3001 ericwyuan@192.168.50.64`
- 所有 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）
- NAS→各渠道直连稳定性验证、frp 隧道打通、四容器（mysql/one-api/lobe-chat/nginx）部署上线，端到端 `https://129.146.203.203/` 已可访问（详见 [PROGRESS.md](PROGRESS.md)）

### 待办（见 SDD 第 8 章待确认事项）

| # | 任务 | 优先级 | 说明 |
|---|------|--------|---|
| 1 | ~~验证 NAS 到各海外 API 官方域名的直连稳定性~~ 已完成 | 高 | 五渠道均直连正常 |
| 2 | 申请新 Gemini / NVIDIA API Key | 高 | 需用户在对应厂商控制台自行申请 |
| 3 | ~~确认 Oracle 反代方式（frp 隧道 vs nginx 反代）~~ 已完成 | 高 | 复用既有 frps，新增 nexusai 代理 |
| 4 | ~~生成部署骨架（docker-compose.yml / nginx.conf / .env.example）~~ 已完成 | 高 | |
| 5 | NAS 实际部署 + One-API 渠道配置 + Failover 验证 | 高 | 容器已部署上线；管理员账号/渠道/Token 需用户在 One-API Web UI 手动完成（涉及密钥输入，AI 不代做） |
| 6 | 确认 HTTPS 域名与证书方案 | 中 | 当前为临时自签名证书跑通链路；是否购买正式域名待紫川决定，届时替换证书即可 |
| 7 | ~~确认 Server-Side 模式 / 管理端口访问方式 / 监控方案~~ 已给出默认结论 | 中 | 详见 [SDD 第 8 章](docs/02-软件设计文档-SDD.md#8-待确认事项2026-08-23-更新已实际部署多数事项已给出默认结论)：保持 Client-Side、管理端口走 SSH 隧道、暂不接入 Prometheus/Grafana |

---

文档结束