Files

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

- SRS/SDD/README/PROGRESS 统一将部署目标由"美国服务器"更正为"NAS 本机 + 甲骨文服务器反向代理"（此前已确认但未入库）
- 新增 docker-compose.yml / nginx.conf / .env.example（对应待办任务4）
- 相对 SDD 草稿的安全加固：one-api 端口改绑 127.0.0.1（原为公网端口映射），lobe-chat 不再发布主机端口，仅走容器内网

2026-08-23 08:31:09 +08:00

7.6 KiB

Raw Permalink Blame History

软件需求规格说明书（SRS）

自建多模态 AI 网关系统（AI Gateway System）

项目	内容
文档版本	V1.0
编写日期	2026-08-23
项目负责人	紫川
文档状态	草案

1. 引言

1.1 编写目的

本文档描述"自建多模态 AI 网关系统"的功能需求、非功能需求与约束条件，作为后续软件设计说明书（SDD）编写和开发实现的依据。

1.2 项目背景

由于公司内网访问 NVIDIA NIM、Gemini 等免费大模型 API 不稳定，希望在自有 NAS 上搭建一套类似 Gemini 首页体验的对话系统（由甲骨文服务器反向代理端口对外提供访问），聚合多个免费 AI API 渠道，实现"一个渠道不可用自动切换下一个"的高可用能力，同时支持图文多模态问答。

1.3 项目目标

提供稳定、统一的 Web 对话入口，界面体验接近 Gemini 首页
聚合至少 5 家免费多模态 API（Gemini、NVIDIA NIM、Groq、OpenRouter、Mistral）
单一渠道失败时自动故障转移（Failover），用户无感知
支持图片 + 文字混合输入的问答
部署于 NAS 本机（Docker Compose），由甲骨文服务器反向代理端口对外访问，规避公司内网对海外 API 的直连限制
全部使用免费额度，不产生 API 调用费用

1.4 术语定义

术语	说明
渠道（Channel）	指某一家 AI API 提供商的接入配置，如 Gemini 渠道、Groq 渠道
网关（Gateway）	统一转发、聚合多个渠道请求的中间层服务，本项目采用 One-API
Failover	故障转移，某渠道不可用时自动切换到下一优先级渠道
多模态（Multimodal）	同时支持文本与图像作为输入的模型能力
RPM	Requests Per Minute，每分钟请求数限制

2. 总体描述

2.1 产品定位

本系统是一个私有部署的 AI 对话网关，面向单用户（紫川本人，未来可扩展至团队），核心价值是"聚合免费额度 + 高可用" —— 让用户无需关心具体调用了哪家模型，只需要在统一界面里提问、上传图片，系统自动选择当前可用的免费渠道完成响应。

2.2 用户角色

角色	描述
终端用户	使用 LobeChat 前端进行日常图文问答的人（紫川本人）
系统管理员	配置渠道、监控用量、调整优先级的人（紫川本人，同一人身兼两角）

2.3 运行环境

部署位置：NAS 本机（Docker Compose），由甲骨文服务器（129.146.203.203）反向代理端口对外提供访问
访问方来源：公司内网（网络不稳定，仅需保证到甲骨文服务器一段链路可用）
容器化部署：Docker + Docker Compose（NAS 使用 ContainerManager）
操作系统：Synology DSM 7（Linux 内核）

2.4 约束与假设

假设：NAS 本机可稳定访问 Google、NVIDIA、Groq、OpenRouter、Mistral 官方域名
约束：仅使用各平台免费额度，不产生付费调用
约束：不做未成年人相关内容、不涉及企业内部代码泄露到公网模型（需用户自行注意脱敏）
假设：公司内网到甲骨文服务器、甲骨文到 NAS 的链路比公司内网直连各 API 官方域名更稳定

3. 功能需求

FR-1 统一对话界面

编号	描述	优先级
FR-1.1	提供 Web 端对话界面，支持文本输入	高
FR-1.2	支持图片上传并随文本一起提问（多模态输入）	高
FR-1.3	支持流式输出（打字机效果）	中
FR-1.4	支持多轮对话上下文保留	高
FR-1.5	支持对话历史保存与查看	中
FR-1.6	界面访问需密码验证（Access Code）	高

FR-2 多渠道聚合与路由

编号	描述	优先级
FR-2.1	支持接入 Gemini、NVIDIA NIM、Groq、OpenRouter、Mistral 五家渠道	高
FR-2.2	支持为渠道设置优先级与权重	高
FR-2.3	支持将多个渠道的不同模型映射为统一对外模型名	高
FR-2.4	请求失败（限流/超时/额度耗尽）时自动切换下一优先级渠道	高
FR-2.5	渠道故障后自动禁用，冷却期后自动恢复重试	中

FR-3 多模态能力

编号	描述	优先级
FR-3.1	图文问答仅路由到支持视觉的渠道/模型	高
FR-3.2	纯文本问答可路由到所有渠道（含无视觉能力的 Groq）	中

FR-4 渠道管理（管理员）

编号	描述	优先级
FR-4.1	支持在后台新增/编辑/删除渠道	高
FR-4.2	支持查看每个渠道的调用次数、成功率、余额/额度状态	中
FR-4.3	支持手动启用/禁用某个渠道	中
FR-4.4	支持生成/吊销对外 Token	高

FR-5 安全与访问控制

编号	描述	优先级
FR-5.1	前端需 Access Code 才能进入对话界面	高
FR-5.2	后台管理端口不直接暴露公网	高
FR-5.3	全站启用 HTTPS	高
FR-5.4	API Key 等敏感信息通过环境变量管理，不写入代码仓库	高

4. 非功能需求

4.1 性能需求

指标	目标值
单次请求响应首字延迟	< 3 秒（视具体渠道而定）
Failover 切换耗时	< 5 秒
并发用户数	支持 1~5 人同时使用（当前阶段单用户为主）

4.2 可用性需求

系统整体可用性目标：99%（不含各免费 API 官方自身故障）
任一单个渠道不可用不应导致整体服务中断

4.3 可维护性需求

渠道配置修改无需重新部署代码，后台界面操作即可生效
日志需可追溯每次请求实际路由到了哪个渠道，便于排查

4.4 兼容性需求

前端需兼容主流桌面浏览器（Chrome/Edge/Safari）及移动端浏览器
网关对外接口需兼容 OpenAI API 格式，便于未来接入其他客户端（如 Claude Code、第三方 App）

4.5 安全需求

所有对外 API Key 不得硬编码在配置文件中提交至版本库
HTTPS 全站加密传输
访问密码需具备一定复杂度

5. 外部接口需求

5.1 用户接口

Web 浏览器访问，响应式布局，适配桌面与移动端

5.2 外部 API 接口

渠道	Base URL	认证方式
Gemini	generativelanguage.googleapis.com/v1beta	API Key（Header/Query）
NVIDIA NIM	integrate.api.nvidia.com/v1	Bearer Token（OpenAI 兼容）
Groq	api.groq.com/openai/v1	Bearer Token（OpenAI 兼容）
OpenRouter	openrouter.ai/api/v1	Bearer Token（OpenAI 兼容）
Mistral	api.mistral.ai/v1	Bearer Token（OpenAI 兼容）

6. 数据需求

数据项	存储位置	说明
对话历史	LobeChat（浏览器 IndexedDB 或 PostgreSQL）	视部署模式而定
渠道配置、API Key	One-API 数据库（MySQL）	敏感信息，需备份加密
调用日志	One-API 数据库	用于用量统计与故障排查

7. 验收标准

通过 Web 界面可正常发起文本对话并获得响应
上传图片后可正常获得图片理解相关的回答
手动关闭优先级最高的渠道后，系统能自动切换到下一渠道且用户侧无明显感知
后台可查看各渠道当日调用次数
全站访问强制 HTTPS，非法访问无法进入后台管理端口

8. 后续可扩展需求（非本期范围）

多用户账号体系与权限隔离
语音输入/输出支持
与紫川的 FAM（家庭 AI 监控系统）前端集成展示
接入更多免费渠道（如 Cerebras、阿里云百炼等）

7.6 KiB Raw Permalink Blame History Unescape Escape