qihuaiflow/docs/ARCHITECTURE.md

七虎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 组件体系

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次重试 + 指数退避