qihu-bot
d2d133f22a
CI / gate (push) Has been cancelled
ARCHITECTURE.md v3.0: 护城河分析,容器拓扑,技术栈矩阵,功能架构,双Claw单引擎,模型同步,安全纵深,qihu-design-system,迭代路线. README.md v3.0: 快速开始,核心能力,架构总览,项目结构,开发指南,平台数据.
417 lines
18 KiB
Markdown
417 lines
18 KiB
Markdown
# 七虎AI PaaS 平台 — 架构设计与实施方案 v3.0
|
||
|
||
> **最后更新**: 2026-08-12
|
||
> **版本**: v3.0
|
||
> **用途**: 平台竞争力、护城河、技术框架、功能架构、业务逻辑完整文档
|
||
> **维护**: 随系统迭代实时更新
|
||
> **仓库**: http://git.qihuyun.com/qyyfw/qihuaiflow
|
||
|
||
---
|
||
|
||
## 一、平台护城河 (Moat)
|
||
|
||
### 1.1 核心竞争壁垒
|
||
|
||
| 壁垒维度 | 具体实现 | 竞争门槛 |
|
||
|---------|---------|---------|
|
||
| **模型聚合网关** | LiteLLM + STORE_MODEL_IN_DB，4+ 厂商统一 OpenAI 协议，管理员 UI 一键增删模型自动同步 | 竞品需手动配置模型路由，无 admin UI 驱动 |
|
||
| **双 Claw 单引擎** | Web SSE + IM Bot (微信) 共享 `EngineCore._send_message_core`，能力发现、MCP 调用、LLM 路由只实现一次 | 竞品 Web/IM 两套代码，同步成本高 |
|
||
| **技能市场闭环** | Skills 发现-安装-搜索(Meilisearch)-执行全生命周期，支持 97+ 技能、14 类 capability | 需自建市场 + 搜索引擎 + 沙箱执行 |
|
||
| **ngnix 安全纵深** | 四层防护: 限流(API 30r/s/Admin 5r/s/Login 1r/s) + 扫描器拦截(14类path/20类UA) + 自动IP黑名单(5min cron/24h TTL) + SSL终止 | 竞品大多只做限流 |
|
||
| **模型双轨制已消除** | #965 平台→LiteLLM REST API 同步，管理员 UI 操作即生效，不再 SSH 手动改 yaml | 多数平台仍手动配置网关 |
|
||
| **设计语言系统** | 完整 `qihu-design-system` (53 modules, CSS 55KB, 品牌色 #5B5FED + 渐变 + 玻璃/辉光 + 暗态) | 需专业设计师 + 前端团队长期维护 |
|
||
| **可观测性** | Prometheus+Grafana+Alloy OTel 双 Claw 标签看板 + 日志审计 | 中小企业平台通常缺监控 |
|
||
|
||
### 1.2 竞争策略
|
||
|
||
| 策略 | 我方 | 竞品(AI PaaS) | 竞品(垂直SaaS) |
|
||
|------|------|-------------|-------------|
|
||
| 模型数量 | 14+ 实时可增删 | 3-5 个 | 1 个 |
|
||
| 技能市场 | 97 个，自建生态 | 0-20 个 | 无 |
|
||
| IM Bot | 微信 + 企业微信扩展 | 无 | 自己开发 |
|
||
| 多租户 | PG RLS 行级安全 | 应用层隔离 | 单租户 |
|
||
| 部署 | Docker Compose 一行启动 | Kubernetes 复杂 | 无 Docker |
|
||
| 定价 | 免费层 + 会员订阅 | 仅付费 | 固定价 |
|
||
|
||
---
|
||
|
||
## 二、部署架构
|
||
|
||
### 2.1 物理拓扑
|
||
|
||
```
|
||
Internet
|
||
│
|
||
┌─────────▼─────────┐
|
||
│ 宝塔 Nginx :443 │ SSL 终止 + 反向代理
|
||
│ root: /www/dk_ │
|
||
│ project/wwwroot/ │
|
||
│ ai.qihuyun.com │
|
||
└─────────┬─────────┘
|
||
│ :12888
|
||
┌──────────────┼──────────────┐
|
||
│ │ │
|
||
┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐
|
||
│ Nginx │ │ uvicorn │ │ 静态资源 │
|
||
│ :8080 │ │ :18080 │ │ dist/ │
|
||
│ proxy_pass │ FastAPI │ │ React SPA│
|
||
└──────────┘ └────┬─────┘ └──────────┘
|
||
│
|
||
┌─────────────┼─────────────────┐
|
||
│ │ │
|
||
┌────▼────┐ ┌───▼────┐ ┌────▼─────┐
|
||
│Postgres │ │ Redis │ │LiteLLM │
|
||
│PG18 │ │ :6379 │ │ :4000 │
|
||
│+pgvector│ └────────┘ │ LLM 网关 │
|
||
└─────────┘ └──────────┘
|
||
```
|
||
|
||
### 2.2 容器清单 (Docker Compose)
|
||
|
||
| 容器 | 镜像 | 端口 | 用途 |
|
||
|------|------|------|------|
|
||
| **qihu-aiflow** | qihuaiflow:with-deps | 12888/18080/8080 | 主应用: Nginx + FastAPI + React dist |
|
||
| **qihu-aiflow-litellm** | berriai/litellm:main-stable | 14000→4000 | LLM 网关 + DB 模式模型管理 |
|
||
| **qihu-aiflow-pg18** | pgvector/pgvector:pg16 | 5432 | PostgreSQL 主库 + 向量引擎 |
|
||
| **qihu-aiflow-redis** | redis:7-alpine | 6379 | 缓存/队列/会话 |
|
||
| **qihu-aiflow-casdoor** | casdoor | 8000 | 统一认证 OAuth2/OIDC |
|
||
| **qihu-aiflow-meilisearch** | meilisearch:v1.11 | 17700 | 技能市场搜索引擎 |
|
||
| **qihu-aiflow-prometheus** | prom/prometheus | 9090 | 指标采集 |
|
||
| **qihu-aiflow-grafana** | grafana/grafana | 3000 | 可视化看板 |
|
||
| **qihu-aiflow-alloy** | grafana/alloy | - | 日志采集 Agent |
|
||
| **qihu-aiflow-node-exporter** | prom/node-exporter | 9100 | 宿主机指标 |
|
||
|
||
### 2.3 网络与域名
|
||
|
||
| 域名 | 用途 |
|
||
|------|------|
|
||
| ai.qihuyun.com | 主站 (React SPA + FastAPI API) |
|
||
| docs.qihuyun.com | 文档站 |
|
||
| bot.qihuyun.com | Bot 回调地址 |
|
||
|
||
---
|
||
|
||
## 三、技术栈矩阵
|
||
|
||
| 层级 | 技术 | 版本 | 选型理由 |
|
||
|------|------|------|---------|
|
||
| **后端框架** | FastAPI (Python 3.11) | 0.115+ | 异步原生、SSE 流式、Pydantic 验证、自动 OpenAPI |
|
||
| **ASGI 服务器** | uvicorn | 0.30+ | 单进程事件循环、生产级 |
|
||
| **前端框架** | React + Vite | 18.3 + 5.4 | 组件化、HMR、TypeScript 5.6 严格模式 |
|
||
| **前端构建** | Tailwind CSS v4.3 | @tailwindcss/vite | utility-first, design token 驱动 |
|
||
| **状态管理** | Zustand 5 | persist | 轻量级，三态主题 (light/dark/system) |
|
||
| **关系数据库** | PostgreSQL 18 | pgvector 0.8.4 | JSONB、向量原生命支持 |
|
||
| **向量引擎** | pgvector | 0.8.4 | 与主库同集群、混合检索 BM25+语义 |
|
||
| **缓存/队列** | Redis 7 | - | 会话、工具列表缓存、事件总线 |
|
||
| **认证** | Casdoor | latest | OAuth2/OIDC、自建身份提供商 |
|
||
| **ORM** | SQLAlchemy 2.0 | 2.0.36 | 成熟生态、async 支持、psycopg |
|
||
| **LLM 客户端** | openai Python SDK | 1.x | 统一 OpenAI 协议接入 |
|
||
| **LLM 网关** | LiteLLM | main-stable | 模型路由、协议转换、费用追踪、key 管理 |
|
||
| **MCP 客户端** | mcp Python SDK | 0.28.1 | Anthropic 官方 SDK、streamable_http/SSE |
|
||
| **搜索引擎** | Meilisearch | v1.11 | BM25 + jieba 中文分词、sub-50ms 响应 |
|
||
| **代理** | Nginx | 1.25+ | 反向代理、静态文件、SSL、限流、扫描器拦截 |
|
||
| **可观测** | Prometheus + Grafana | latest | 指标仪表盘、双 Claw OTel 标签 |
|
||
| **容器** | Docker Compose | v2 | 单机部署、一行启动 |
|
||
|
||
---
|
||
|
||
## 四、功能架构
|
||
|
||
### 4.1 系统分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 表现层 (Frontend) │
|
||
│ React SPA | Tailwind CSS | Zustand State │
|
||
│ AppShell (NavRail+抽屉) | 三态主题 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 网关层 (Gateway) │
|
||
│ Nginx | SSL 终止 | 限流 | 扫描器拦截 | IP 黑名单 │
|
||
├─────────────────────────────────────────────────┤
|
||
│ API 层 (FastAPI) │
|
||
│ auth | chat | admin | market | agents | mcp │
|
||
│ skills | storage | billing | im_llm │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 业务逻辑层 (Core) │
|
||
│ EngineCore | LLM Router | Node Registry │
|
||
│ Claw Adapters (SSE/Buffer) | OTel │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 协议网关层 │
|
||
│ LiteLLM (model routing) | MCP Protocol │
|
||
├─────────────────────────────────────────────────┤
|
||
│ 数据层 (Storage) │
|
||
│ PostgreSQL+pgvector | Redis | Meilisearch │
|
||
│ Qiniu/OSS Object Storage | Casdoor OAuth │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.2 核心功能模块
|
||
|
||
#### 前台 (Frontend Pages)
|
||
|
||
| 模块 | 路径 | 功能 |
|
||
|------|------|------|
|
||
| 落地页 | `/` | 平台介绍 + Hero + 能力展示 |
|
||
| AI 对话 | `/chat` | SSE 流式对话、代码块渲染、Markdown、媒体预览 |
|
||
| 知识库 | `/knowledge` | 文档上传、RAG 检索、向量索引管理 |
|
||
| 技能市场 | `/market` | Meilisearch 搜索、技能安装、上架审核 |
|
||
| Token 驾驶舱 | `/token` | 实时用量、消耗趋势、预警告警 |
|
||
| 会员/定价 | `/pricing` | 套餐对比、微信支付订阅、增值付费 |
|
||
| 个人中心 | `/profile` | 用户信息、主题设置、API Key 管理 |
|
||
| 通知中心 | `/notifications` | 系统消息、订单通知、告警 |
|
||
| Agent 画布 | `/agent` | 可视化编排、DAG 工作流编辑 |
|
||
| App 服务 | `/apps` | 第三方应用集成(小说、视频等) |
|
||
|
||
#### 后台 (Admin Pages)
|
||
|
||
| 模块 | 路径 | 功能 |
|
||
|------|------|------|
|
||
| 平台驾驶舱 | `/admin` | 用户数/模型数/调用量/营收概览 |
|
||
| 大模型库 | `/admin/models` | 供应商管理、模型 CRUD、连接测试、能力默认值配置、**自动同步 LiteLLM** |
|
||
| Agent 管理 | `/admin/agents` | Agent 创建/编辑/状态 |
|
||
| 技能管理 | `/admin/skills` | 技能审批、上架/下架、分类 |
|
||
| MCP 管理 | `/admin/mcp` | MCP Server 注册/授权 |
|
||
| 用户管理 | `/admin/users` | 用户 CRUD、角色分配 |
|
||
| 会员管理 | `/admin/membership` | 套餐配置、续费管理 |
|
||
| 推广系统 | `/admin/promotion` | 邀请链接、佣金结算 |
|
||
| 计费管理 | `/admin/billing` | 充值记录、订单、退款 |
|
||
| 应用市场 | `/admin/market` | 应用审核、产品定价、webhook |
|
||
| 系统设置 | `/admin/settings` | 站点配置、SMS、存储 |
|
||
| 日志审计 | `/admin/logs` | 操作日志、不可删除 |
|
||
| Wechat Bot | `/admin/imbots` | 微信连接状态、消息历史 |
|
||
|
||
### 4.3 模型能力体系
|
||
|
||
| 能力分类 | 英文标识 | 代表模型 | 用途 |
|
||
|---------|---------|---------|------|
|
||
| 文本对话 | text | DeepSeek-V4-Flash, MiMo-v2.5 | 通用聊天、文档生成 |
|
||
| 推理思考 | thinking | MiMo-v2.5 | 复杂推理、逻辑分析 |
|
||
| 视觉理解 | vision | MiMo-v2.5 | 图片识别、OCR |
|
||
| 工具调用 | tool | MiMo-v2.5 | Function Calling |
|
||
| 图像生成 | image | AGNES-Image-2.0-Flash | AI 绘图 |
|
||
| 视频生成 | video | AGNES-Video-v2.0 | AI 视频生成 |
|
||
| 语音合成 | audio | MOSS-TTSD | TTS 文字转语音 |
|
||
| 语音识别 | asr | TeleSpeechASR | 语音转文字 |
|
||
| OCR 识别 | ocr | DeepSeek-OCR | 文档 OCR |
|
||
| 嵌入向量 | embedding | BAAI/bge-m3 | 文本向量化 |
|
||
| 重排序 | rerank | BAAI/bge-reranker-v2-m3 | 检索结果重排 |
|
||
|
||
---
|
||
|
||
## 五、核心业务逻辑
|
||
|
||
### 5.1 AI 对话处理流 (chat.py)
|
||
|
||
```
|
||
用户消息 → chat.py _send_message_core
|
||
→ capability_discovery (发现可用 MCP/Skills/Models)
|
||
→ System Prompt 组装 (知识库 + 能力清单 + 对话历史)
|
||
→ LiteLLM /v1/chat/completions (master key 认证)
|
||
→ SSE 流式返回 → BufferAdapter 缓冲 → SseAdapter 推送
|
||
→ 图片生成: AGNES API → async thread → media relay → 微信推送
|
||
→ 日志: Token 用量 + 审计
|
||
```
|
||
|
||
### 5.2 双 Claw 单引擎架构 (Dual Claw)
|
||
|
||
```
|
||
Web Claw (SSE) IM Bot Claw (微信)
|
||
│ │
|
||
▼ ▼
|
||
SseAdapter BufferAdapter
|
||
│ │
|
||
└──────────┬───────────────────┘
|
||
▼
|
||
EngineCore._send_message_core (唯一引擎)
|
||
│
|
||
┌────────┼────────┐
|
||
▼ ▼ ▼
|
||
LLM Router MCP SDK Capability Discovery
|
||
```
|
||
|
||
**关键设计原则**:
|
||
- 能力发现 `capability_discovery.py` Web/IM 共用
|
||
- MCP 命名 `mcp__{safe(name,30)}__{safe(tool,50)}__{idx}` 统一
|
||
- `tests/test_dual_claw.py` R-DUAL 集成哨兵
|
||
|
||
### 5.3 模型同步机制 (#965 LiteLLM Sync)
|
||
|
||
```
|
||
管理员 UI "添加模型" → models.py create_model()
|
||
→ PostgreSQL aiflow.AIModel 写入 ✅
|
||
→ threading.Thread → LiteLLM REST API /model/new ✅
|
||
→ LiteLLM litellm DB 热加载 ✅
|
||
→ 用户立即可用 ✅
|
||
|
||
STORE_MODEL_IN_DB=True (docker-compose)
|
||
```
|
||
|
||
### 5.4 媒体生成与中转 (#967 media_relay)
|
||
|
||
```
|
||
用户请求 "生成图片" → chat.py 检测 intent
|
||
→ AGNES API /v1/images/generations
|
||
→ SiliconFlow S3 存储 → 临时 URL (24h)
|
||
→ media/relay (httpx stream + domain whitelist)
|
||
→ WeChat / Web SSE 内联渲染
|
||
```
|
||
|
||
### 5.5 安全纵深防御
|
||
|
||
```
|
||
第一层: Nginx 限流
|
||
- API: 30 r/s | Admin: 5 r/s | Login: 1 r/s
|
||
第二层: 扫描器拦截
|
||
- Path 14 类 (.git/.env/wp-login/etc) → 444
|
||
- UA 20 类 (zgrab/nmap/gobuster/etc) → 444
|
||
- Client SDK (curl/wget/python-requests) → 444
|
||
第三层: 自动黑名单
|
||
- /app/backend/nginx/block_ip.py
|
||
- 5min cron + 24h TTL
|
||
- 基于 4xx 错误率和 UA 模式
|
||
第四层: JWT + Casdoor 认证
|
||
- JWT Bearer Token
|
||
- role-based 路由 (super_admin/admin/user)
|
||
```
|
||
|
||
---
|
||
|
||
## 六、设计系统 (qihu-design-system)
|
||
|
||
### 6.1 设计理念
|
||
|
||
**温暖科技感 + 极简主义** (Warm Tech Minimalism)。护眼雾白底，靛蓝 `#5B5FED` 为唯一品牌色。
|
||
|
||
### 6.2 技术实现
|
||
|
||
| 维度 | 值 |
|
||
|------|-----|
|
||
| 主品牌色 | `#5B5FED` (indigo) |
|
||
| 暗态品牌色 | `#8289F5` |
|
||
| 签名渐变 | indigo → violet(#8B5CF6) → fuchsia(#D946EF) |
|
||
| 字体 | Inter (正文/标题) + JetBrains Mono (代码) |
|
||
| CSS 框架 | Tailwind v4.3 (@tailwindcss/vite) |
|
||
| 主题 | light / dark / system 三态，Zustand persist + matchMedia |
|
||
| 组件库 | 53 modules，CSS 55KB / JS 244KB / 1.36s build |
|
||
|
||
### 6.3 组件体系
|
||
|
||
```yaml
|
||
ui: Button(6 variants) | Badge(6v) | Input | Card(6v+cardSurface)
|
||
canvas: GenUiCard(7 themes) | StatusRing(6 states) | ChatComposer(glass)
|
||
layout: AppShell(NavRail+drawer+skip-link) | ThemeToggle | ReaderTabs
|
||
```
|
||
|
||
### 6.4 设计铁律
|
||
|
||
- ❌ 禁硬编码 `bg-blue-*`/`bg-sky-*`/`bg-indigo-600`
|
||
- ✅ GenUi 走 primary 语义 token
|
||
- ✅ 变体映射必须 `Record<Variant, string>` + `cn()`，禁 `bg-primary-${w}`
|
||
- ✅ 暗态 `.dark` 双写；玻璃/辉光统一 `.glass`/`.glow`
|
||
- ✅ 动效尊重 `prefers-reduced-motion`
|
||
- ✅ 条纹: `--chat-accent` / `--r-sm|md|lg` / `--chat-ease cubic-bezier(0.2,0.8,0.2,1)` / `--chat-duration 200ms`
|
||
|
||
---
|
||
|
||
## 七、运维与可靠性
|
||
|
||
### 7.1 Safe-Align 工作流
|
||
|
||
```
|
||
① 备份: docker commit → backup 镜像 + git tag + bundle + PG dump
|
||
② 拷贝: 仅 git-tracked 源文件 容器→宿主 git
|
||
③ 提交: git add + commit (不 push)
|
||
④ 校验: docker restart + 验证 + docker commit → with-deps
|
||
```
|
||
|
||
**真相源**: 容器 (image := container := git)
|
||
|
||
### 7.2 监控
|
||
|
||
- Grafana 双 Claw 对比看板 `uid: qihuaiflow-dual-claw-876`
|
||
- OTel traces + metrics (alloy → Prometheus)
|
||
- 日志级别: INFO (生产) / DEBUG (开发)
|
||
|
||
### 7.3 备份策略
|
||
|
||
- 每 6h 自动备份 (cron)
|
||
- PG dump (不用 --ssl=0 否则 0 bytes)
|
||
- Docker image snapshot: `qihuaiflow:backup-*{TS}`
|
||
- nginx logrotate 每日轮转
|
||
|
||
---
|
||
|
||
## 八、迭代路线
|
||
|
||
### 8.1 已完成 (2026-08-11)
|
||
|
||
| 编号 | 描述 | commit |
|
||
|------|------|--------|
|
||
| #957 | Nginx server 级 root 修复 | 53bbbf3 |
|
||
| #959 | Index.html no-store cache | 45b6939 |
|
||
| #961 | React hydration error fix | 4cf910e |
|
||
| #962 | Global ErrorBoundary | 420e0f6 |
|
||
| #963 | safeLazy chunk load fallback | 679f23f |
|
||
| #964 | React hooks rules fix (#321) | fa38d2c |
|
||
| #965 | LiteLLM platform-model sync | fd84fec |
|
||
| #966 | Container restart loop fix | 75be24c |
|
||
| #967 | media_relay endpoint impl | 54b444b |
|
||
|
||
### 8.2 下一步候选
|
||
|
||
| 优先级 | 项目 | 工作量 |
|
||
|--------|------|--------|
|
||
| 🟢 P0 | 企业微信官方 Bot API 接入 | 3 天 |
|
||
| 🟢 P1 | 后端核心模块单测补全 (165→300+) | 3 天 |
|
||
| 🟡 P1 | Alloy traces 配置 bake to image | 1 天 |
|
||
| 🟡 P1 | 多租户 PG RLS 隔离 | 5 天 |
|
||
| ⚪ P2 | 语音/视频流式响应 | 5 天 |
|
||
| ⚪ P2 | Agent 画布可视化编排 | 7 天 |
|
||
|
||
### 8.3 长期方向
|
||
|
||
1. **模型 → 智能体**: 从简单的模型调用升级到自主 Agent + 多步推理
|
||
2. **单机 → 集群**: Docker Compose → Kubernetes + Helm
|
||
3. **中国市场 → 国际化**: 多语言 + 多区域部署
|
||
4. **技能市场 → 开放生态**: 第三方开发者平台 + 收入分成
|
||
5. **个人微信 → 企业微信**: 合规化 IM Bot 渠道
|
||
|
||
---
|
||
|
||
## 九、附录
|
||
|
||
### 9.1 服务器信息
|
||
|
||
| 项 | 值 |
|
||
|------|-----|
|
||
| IP | 210.16.161.218 |
|
||
| OS | Ubuntu 24.04 |
|
||
| 公网地址 | https://ai.qihuyun.com |
|
||
| 后台地址 | https://ai.qihuyun.com/admin |
|
||
| 默认账户 | admin / admin123 |
|
||
| Git | http://git.qihuyun.com/qyyfw/qihuaiflow |
|
||
|
||
### 9.2 关键文件路径
|
||
|
||
| 文件 | 容器路径 |
|
||
|------|---------|
|
||
| 后端入口 | `/app/backend/python/main.py` |
|
||
| AI 对话 | `/app/backend/python/app/api/chat.py` |
|
||
| LLM 网关 | `/app/backend/python/app/core/llm_router.py` |
|
||
| 双 Claw | `/app/backend/python/app/core/claw_adapters.py` |
|
||
| 同步服务 | `/app/backend/python/app/core/litellm_sync.py` |
|
||
| 前端入口 | `/app/frontend/src/main.tsx` |
|
||
| Nginx 配置 | `/etc/nginx/conf.d/aiflow.conf` |
|
||
| LiteLLM 配置 | `/app/config.yaml` (litellm 容器) |
|
||
|
||
### 9.3 调试经验
|
||
|
||
| 问题 | 解决方案 |
|
||
|------|---------|
|
||
| 容器重启循环 | docker stop → docker cp 修复文件 → docker start |
|
||
| React #321 hooks error | useState 必须在组件函数内，不能模块顶层 |
|
||
| Chrome 缓存旧 HTML | index.html 加 Cache-Control: no-store |
|
||
| nginx 调测 444 | curl 用 -A 'Mozilla/5.0' 避免被 P1-2 拦截 |
|
||
| Docker tag 短ID 报错 | 必须用完整 sha256: 格式 ID |
|
||
| SSH paramiko 掉线 | get_ssh() 3次重试 + 指数退避 |
|