ericwyuan/NexusAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
557ec170da18a84b44384e3446cc3819e0d36617
NexusAI/README.md

8.1 KiB
Raw Blame History

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 文档

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 章

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 章）
  • 前端强制 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 模式 / 管理端口访问方式 / 监控方案 中

文档结束

Reference in New Issue View Git Blame Copy Permalink