ericwyuan/NexusAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(部署方案): 同步 NAS+甲骨文反代决策 + 生成部署骨架

Browse Source 
- SRS/SDD/README/PROGRESS 统一将部署目标由"美国服务器"更正为"NAS 本机 + 甲骨文服务器反向代理"（此前已确认但未入库）
- 新增 docker-compose.yml / nginx.conf / .env.example（对应待办任务4）
- 相对 SDD 草稿的安全加固：one-api 端口改绑 127.0.0.1（原为公网端口映射），lobe-chat 不再发布主机端口，仅走容器内网
This commit is contained in:
ericwyuan
2026-08-23 08:31:09 +08:00
parent 557ec170da
commit 188c02478b
7 changed files with 218 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/01-软件需求文档-SRS.md
View File

@@ -18,7 +18,7 @@
### 1.2 项目背景
由于公司内网访问 NVIDIA NIM、Gemini 等免费大模型 API 不稳定，希望在自有美国服务器上搭建一套类似 Gemini 首页体验的对话系统，聚合多个免费 AI API 渠道，实现"一个渠道不可用自动切换下一个"的高可用能力，同时支持图文多模态问答。
由于公司内网访问 NVIDIA NIM、Gemini 等免费大模型 API 不稳定，希望在自有 NAS 上搭建一套类似 Gemini 首页体验的对话系统（由甲骨文服务器反向代理端口对外提供访问），聚合多个免费 AI API 渠道，实现"一个渠道不可用自动切换下一个"的高可用能力，同时支持图文多模态问答。
### 1.3 项目目标
@@ -26,7 +26,7 @@
- 聚合至少 5 家免费多模态 API（Gemini、NVIDIA NIM、Groq、OpenRouter、Mistral）
- 单一渠道失败时自动故障转移（Failover），用户无感知
- 支持图片 + 文字混合输入的问答
- 部署在美国服务器，规避公司内网对海外 API 的直连限制
- 部署于 NAS 本机（Docker Compose），由甲骨文服务器反向代理端口对外访问，规避公司内网对海外 API 的直连限制
- 全部使用免费额度，不产生 API 调用费用
### 1.4 术语定义
@@ -56,17 +56,17 @@
### 2.3 运行环境
- 部署位置：美国服务器（无地区网络限制）
- 访问方来源：公司内网（网络不稳定，仅需保证到本服务器一段链路可用）
- 容器化部署：Docker + Docker Compose
- 操作系统：Linux（Ubuntu/Debian 系）
- 部署位置：NAS 本机（Docker Compose），由甲骨文服务器（129.146.203.203）反向代理端口对外提供访问
- 访问方来源：公司内网（网络不稳定，仅需保证到甲骨文服务器一段链路可用）
- 容器化部署：Docker + Docker Compose（NAS 使用 ContainerManager）
- 操作系统：Synology DSM 7（Linux 内核）
### 2.4 约束与假设
- 假设：美国服务器可稳定访问 Google、NVIDIA、Groq、OpenRouter、Mistral 官方域名
- 假设：NAS 本机可稳定访问 Google、NVIDIA、Groq、OpenRouter、Mistral 官方域名
- 约束：仅使用各平台免费额度，不产生付费调用
- 约束：不做未成年人相关内容、不涉及企业内部代码泄露到公网模型（需用户自行注意脱敏）
- 假设：公司内网到美国服务器的连接比公司内网直连各 API 官方域名更稳定
- 假设：公司内网到甲骨文服务器、甲骨文到 NAS 的链路比公司内网直连各 API 官方域名更稳定
---

27
docs/02-软件设计文档-SDD.md
View File

@@ -36,7 +36,13 @@
│ HTTPS (443)
▼
┌───────────────────────────────────────────────────────────────┐
│ 美国服务器（Docker 宿主机） │
│ 甲骨文服务器（129.146.203.203，公网反代层） │
│ frp / nginx 反向代理端口 → NAS（对外统一入口） │
└──────────────────────────┬────────────────────────────────────┘
│ 反代 / 隧道（frp）
▼
┌───────────────────────────────────────────────────────────────┐
│ NAS 本机（Docker 宿主机） │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Nginx（反向代理层） │ │
@@ -77,7 +83,8 @@
| 层级 | 组件 | 职责 |
|---|---|---|
| 接入层 | Nginx | HTTPS 终止、反向代理、访问入口统一 |
| 反代层 | 甲骨文服务器 | frp/nginx 反向代理端口，对外统一访问入口 |
| 接入层 | Nginx | HTTPS 终止、反向代理、访问入口统一（NAS 本机） |
| 表现层 | LobeChat | 用户交互、对话渲染、多模态输入采集 |
| 网关层 | One-API | 协议转换、渠道路由、故障转移、用量统计 |
| 数据层 | MySQL | 网关配置与日志持久化 |
@@ -85,7 +92,7 @@
### 2.3 部署视图
单机 Docker Compose 部署，各服务以容器形式运行在同一 Docker 网络（`ai-network`）内，服务间通过容器名互相寻址，仅 Nginx 的 80/443 端口对公网暴露。
单机 Docker Compose 部署于 **NAS 本机**，各服务以容器形式运行在同一 Docker 网络（`ai-network`）内，服务间通过容器名互相寻址，仅 Nginx 的 80/443 端口对局域网暴露；对外由**甲骨文服务器（129.146.203.203）**通过 frp/nginx 反向代理该端口，供公司内网公网访问。
---
@@ -94,7 +101,7 @@
### 3.1 Nginx 反向代理模块
**职责**
- 对外仅暴露 443（HTTPS）与 80（HTTP 跳转 443）
- 在 NAS 本机暴露 443（HTTPS）与 80（HTTP 跳转 443）；公网访问由甲骨文服务器反向代理到本机 443 端口
- 将请求转发至 `lobe-chat:3210`
- 关闭代理缓冲以支持流式输出（SSE）
@@ -233,10 +240,11 @@ server {
| 风险点 | 设计对策 |
|---|---|
| 后台管理端口暴露 | One-API 的 3000 端口不映射到公网，仅容器内网可访问；如需远程管理，走 SSH 隧道或 VPN |
| 后台管理端口暴露 | One-API 的 3000 端口不映射到公网，仅容器内网可访问；Oracle 反代仅转发前端端口，管理端口走 SSH 隧道或 VPN |
| API Key 泄露 | 所有 Key 通过 `.env` 文件注入容器环境变量，`.env` 加入 `.gitignore`，不提交版本库 |
| 未授权访问前端 | LobeChat `ACCESS_CODE` 强制校验 |
| 传输层安全 | Nginx 强制 HTTPS，HTTP 请求 301 跳转 |
| 公网入口暴露 | 对外仅暴露甲骨文服务器反代端口，NAS 本机不直接暴露公网 |
| 密钥被盗用后的止损 | One-API 后台可随时吊销/轮换 Token，不影响各渠道原始 Key |
---
@@ -327,15 +335,16 @@ networks:
### 6.3 部署步骤
1. 服务器安装 Docker + Docker Compose
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://<服务器IP>:3000` 完成 One-API 初始化（设置管理员密码）
5. 访问 `http://<NAS-IP>:3000` 完成 One-API 初始化（设置管理员密码）
6. 后台按 3.3 节渠道设计表逐个添加渠道，设置优先级
7. 创建对外 Token，写入 `.env` 的 `ONE_API_TOKEN`
8. `docker-compose restart lobe-chat` 使配置生效
9. 访问 `https://<域名>` 验证前端可正常对话、上传图片、触发 Failover
9. 在甲骨文服务器配置 frp（或 nginx 反代）将公网端口转发至 NAS 的 Nginx 443 端口
10. 访问 `https://<域名>`（经甲骨文反代）验证前端可正常对话、上传图片、触发 Failover
### 6.4 运维监控设计
@@ -368,3 +377,5 @@ networks:
2. 后台管理端口是否需要通过 VPN/SSH 隧道访问，还是接受当前仅内网暴露的方案
3. 是否需要接入 Prometheus/Grafana 做可视化监控（当前为后续扩展项，非本期必做）
4. 域名与证书由紫川自行准备，还是需要方案建议
5. **NAS 到各海外 API 官方域名的直连稳定性验证**（部署目标已改为 NAS 本机 + 甲骨文反代，需确认 NAS 出站访问 Google/NVIDIA/Groq/OpenRouter/Mistral 的稳定性）
6. **甲骨文反代方式确认**：frp 隧道（参照 FAM 项目方案）还是 nginx 反代