docs(项目启动): SRS/SDD 文档入库 + README/PROGRESS + 仓库初始化

2026-08-23 08:24:56 +08:00
commit 557ec170da
5 changed files with 843 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,195 @@
+# NexusAI — 自建多模态 AI 网关系统（AI Gateway System）
+
+> 聚合多家免费多模态 AI API 的统一对话网关：Nginx + LobeChat + One-API + MySQL 容器化部署。
+> 单一渠道不可用时自动故障转移（Failover），用户无感知。
+> 最后更新：2026-08-23（文档入库，尚未部署）
+
+---
+
+## 1. 项目简介与设计目标
+
+公司内网直连 NVIDIA NIM、Gemini 等免费大模型 API 不稳定，本系统部署在美国服务器上，聚合 5 家免费多模态 API（Gemini、NVIDIA NIM、Groq、OpenRouter、Mistral），通过 One-API 网关统一路由，实现"一个渠道不可用自动切换下一个"的高可用能力，并提供接近 Gemini 首页体验的 Web 对话界面（LobeChat），支持图片 + 文字混合输入问答。
+
+### 1.1 核心价值
+
+- **聚合免费额度 + 高可用**：用户只需在统一界面提问/上传图片，无需关心调用哪家模型
+- **配置驱动**：渠道增删、优先级调整通过 One-API 后台界面完成，不改代码
+- **全部免费**：仅使用各平台免费额度，不产生 API 调用费用
+
+### 1.2 文档
+
+- [软件需求规格说明书（SRS）V1.0](docs/01-软件需求文档-SRS.md)
+- [软件设计说明书（SDD）V1.0](docs/02-软件设计文档-SDD.md)
+
+---
+
+## 2. 系统架构
+
+```
+浏览器 / 移动端浏览器（公司内网）
+        │ HTTPS (443)
+        ▼
+Nginx（反向代理，HTTPS 终止，流式透传）──► LobeChat（前端，:3210）──► One-API（网关，:3000 仅内网）──► MySQL
+                                                                             │
+                                    ┌──────────────┬──────────────┬──────────────┐
+                                    ▼              ▼              ▼              ▼
+                               Gemini       NVIDIA NIM       Groq         OpenRouter   Mistral
+```
+
+| 层级 | 组件 | 职责 |
+|---|---|---|
+| 接入层 | Nginx | HTTPS 终止、反向代理、访问入口统一 |
+| 表现层 | 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. 部署概览
+
+- **方式**：单机 Docker Compose，所有服务在同一 `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（公网） | HTTPS 终止、反向代理 |
+| lobe-chat | lobehub/lobe-chat:latest | 3210（内网） | 前端对话界面 |
+| one-api | justsong/one-api:latest | 3000（内网） | 网关聚合层 |
+| mysql | mysql:8.0 | 3306（内网） | One-API 数据存储 |
+
+### 3.2 安全要点
+
+- 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（FAM-Core + FAM-UI + MariaDB + 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（FAM-Edge + Ollama + FFmpeg）
+
+| 项目 | 值 |
+|---|---|
+| 公网 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` |
+
+### 4.4 Gitea 代码仓库
+
+| 项目 | 值 |
+|---|---|
+| URL | http://192.168.50.64:3000/ericwyuan/NexusAI |
+| 账号 / 密码 | ericwyuan / iLoveJava5 |
+
+> 美国服务器（AI 网关部署目标）访问信息待补充。
+
+---
+
+## 5. AI 渠道 API Key（服务器 `.env` 管理，不入库）
+
+> ⚠️ Gemini 与 NVIDIA 的 Key 将申请新值，此处不写入旧 Key，配置于美国服务器 `.env` 的占位变量。
+
+| 渠道 | 模型 / 端点 | Key 环境变量（服务器 .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 申请后填入美国服务器 `.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 | 申请美国服务器，确认访问信息 | 高 |
+| 2 | 申请新 Gemini / NVIDIA API Key | 高 |
+| 3 | 确认 HTTPS 域名与证书方案 | 中 |
+| 4 | 生成部署骨架（docker-compose.yml / nginx.conf / .env.example） | 高 |
+| 5 | 实际部署 + One-API 渠道配置 + Failover 验证 | 高 |
+| 6 | 确认 Server-Side 模式 / 管理端口访问方式 / 监控方案 | 中 |
+
+---
+
+文档结束