docs-add-architecture-blueprint

2026-07-27 09:10:11 +08:00
1 parent efa63f9d25
commit ec7de645f4
@@ -0,0 +1,544 @@
+# 七虎AI PaaS 平台 — 架构设计与实施方案 v2.0
+
+> **最后更新**: 2026-07-27
+> **版本**: v2.0
+> **用途**: 投喂 AI 大模型进行平台竞争力、护城河、扩展能力分析
+> **维护**: 随系统迭代实时更新
+
+---
+
+## 一、平台概述
+
+### 1.1 定位
+
+七虎AI（qihuyun.com）是一个面向开发者和企业的 **AI PaaS 平台**，核心能力是聚合多厂商大模型、提供标准化工具调用层、支持 Skill/MCP/Agent 的发现-安装-编排-执行全生命周期管理。
+
+### 1.2 核心价值主张
+
+| 价值维度 | 实现方式 |
+|---------|---------|
+| 模型聚合 | 统一 OpenAI 兼容协议接入 4+ 厂商（SiliconFlow、MiMo、AGNES、DeepSeek），自动 failover |
+| 技能市场 | Skills 的上架-搜索-安装-执行闭环，支持 14 个能力分类 |
+| MCP 协议 | 官方 Anthropic MCP SDK 实现，支持 streamable_http/SSE 传输 |
+| Agent 编排 | DAG 图引擎 + Supervisor 模式，支持外部 Agent（Dify/n8n/Coze）远程调用 |
+| IM Bot | 多平台（微信/企业微信/飞书/QQ）统一消息网关 |
+| 知识库 RAG | PostgreSQL pgvector + 混合检索 |
+| 媒体生成 | 异步图片/视频生成（后台线程，不阻塞 SSE） |
+| 可观测 | Prometheus+Grafana 监控栈 + 日志审计 |
+
+---
+
+## 二、整体架构
+
+### 2.1 部署架构
+
+```
+                    Internet
+                        │
+                   ┌────▼────┐
+                   │  Nginx  │  :12888 (HTTPS)
+                   └────┬────┘
+                        │
+         ┌──────────────┼──────────────┐
+         │              │              │
+    ┌────▼────┐    ┌───▼────┐    ┌───▼─────┐
+    │ React   │    │FastAPI │    │ Casdoor │
+    │ Vite    │    │uvicorn │    │  :8000  │
+    │ (dist/) │    │:18080  │    └─────────┘
+    └─────────┘    └───┬────┘
+                       │
+         ┌─────────────┼─────────────┐
+         │             │             │
+    ┌────▼────┐   ┌───▼────┐   ┌───▼──────┐
+    │Postgres │   │ Redis  │   │ Executor │
+    │PG18+    │   │:6379   │   │ (Code)   │
+    │pgvector │   └────────┘   └──────────┘
+    └─────────┘
+```
+
+### 2.2 容器清单
+
+| 容器 | 镜像 | 用途 |
+|------|------|------|
+| qihu-aiflow | 自建(custom) | 主应用（Nginx + FastAPI uvicorn + React dist） |
+| qihu-aiflow-pg18 | pgvector/pgvector:pg16 | PostgreSQL 主库 + 向量扩展 |
+| qihu-aiflow-redis | redis:7-alpine | 缓存/队列/会话 |
+| qihu-aiflow-casdoor | casdoor | 统一认证 |
+| qihuaiflow-executor | 自建 | 代码执行沙箱 |
+| qihu-aiflow-prometheus | prom/prometheus | 指标采集 |
+| qihu-aiflow-grafana | grafana/grafana | 可视化监控 |
+| qihu-aiflow-alloy | grafana/alloy | 日志采集 Agent |
+| qihu-aiflow-node-exporter | prom/node-exporter | 宿主机指标 |
+
+### 2.3 数据流
+
+```
+用户请求 → Nginx(:12888) → uvicorn(:18080)
+  ├── /app/api/chat/* → chat.py (SSE streaming)
+  ├── /app/api/auth/* → auth.py (JWT)
+  ├── /app/api/admin/* → admin/* (CRUD + 管理)
+  └── / → index.html → React SPA
+```
+
+---
+
+## 三、技术栈矩阵
+
+| 层级 | 技术 | 版本 | 选型理由 |
+|------|------|------|---------|
+| 后端框架 | FastAPI (Python) | 0.115+ | 异步原生、SSE 流式支持、Pydantic 验证 |
+| ASGI 服务器 | uvicorn | 0.30+ | 单进程事件循环、生产级 |
+| 前端框架 | React + Vite | 18 + 5 | 组件化、HMR 热更新、Tree-shaking |
+| 前端语言 | TypeScript | 5.6+ | 类型安全 |
+| 关系数据库 | PostgreSQL | 18 | JSONB、pgvector 原生支持、AIO 引擎 |
+| 向量引擎 | pgvector | 0.8.4 | 与主库同集群、免运维 |
+| 缓存 | Redis | 7 | 会话、队列、工具列表缓存 |
+| 认证 | Casdoor | latest | 开源统一认证、OAuth2/OIDC |
+| ORM | SQLAlchemy | 2.0.36 | 成熟生态、支持 async |
+| LLM 客户端 | openai Python SDK | 1.x | OpenAI 兼容协议统一接入 |
+| MCP 客户端 | mcp Python SDK | 1.28.1 | Anthropic 官方 SDK |
+| 代理 | Nginx | 1.25+ | 反向代理、静态文件、SSL |
+| 容器 | Docker Compose | v2 | 单机编排 |
+| 监控 | Prometheus + Grafana | latest | 开源标准、全栈可见 |
+
+---
+
+## 四、数据模型（67 张表，按域分组）
+
+### 4.1 核心业务域
+
+| 表名 | 说明 | 关键字段 |
+|------|------|---------|
+| users | 用户 | id, username, password_hash, role |
+| conversations | 对话 | id, user_id, title, model_id |
+| messages | 消息 | id, conv_id, role, content, tool_calls, used_skills |
+| models | AI 模型 | id, provider_id, name, endpoint, capabilities, is_default |
+| model_providers | 模型提供商 | id, name, protocol, api_key, api_base_url, auth_header |
+| site_settings | 站点配置 | key, value (JSON) |
+| mcpservers | MCP 服务 | id, name, url, transport_type, is_enabled, tools_count |
+
+### 4.2 技能市场域
+
+| 表名 | 说明 |
+|------|------|
+| market_apps | 市场应用（Skills/MCP/Agents） |
+| market_app_versions | 应用版本 |
+| app_purchases | 购买记录 |
+| app_reviews | 评价 |
+| app_installations | 安装记录 |
+| skill_versions | 技能版本 |
+| skill_publish_records | 发布记录 |
+| evolution_skills | 进��技能 |
+| evolution_events | 进化事件 |
+| evolution_trajectories | 进化轨迹 |
+| team_shared_skills | 团队共享技能 |
+
+### 4.3 知识库域
+
+| 表名 | 说明 |
+|------|------|
+| knowledge_bases | 知识库 |
+| knowledge_directories | 知识目录 |
+| knowledge_documents | 文档 |
+| knowledge_document_chunks | 文档分块 |
+| knowledge_graph_nodes | 知识图谱节点 |
+| knowledge_graph_edges | 知识图谱边 |
+| external_kb_services | 外部 KB 服务 |
+
+### 4.4 会员/支付域
+
+| 表名 | 说明 |
+|------|------|
+| membership_plans | 会员计划 |
+| membership_subscriptions | 订阅 |
+| orders | 订单 |
+| coupons | 优惠券 |
+| user_coupons | 用户优惠券 |
+| value_added_services | 增值服务 |
+| payment_configs | 支付配置 |
+
+### 4.5 监控/运维域
+
+| 表名 | 说明 |
+|------|------|
+| token_usage_logs | Token 用量日志 |
+| token_balances | 余额 |
+| operation_logs | 操作日志 |
+| audit_logs | 审计日志 |
+| login_logs | 登录日志 |
+| risk_rules | 风控规则 |
+| slow_request_logs | 慢请求日志 |
+| api_call_stats | API 调用统计 |
+| task_execution_logs | 任务执行日志 |
+
+---
+
+## 五、API 全景
+
+### 5.1 前台 API（用户面）
+
+| 路由前缀 | 端点 | 方法 | 说明 |
+|---------|------|------|------|
+| /app/api/auth | /login | POST | 用户登录，返回 JWT |
+| /app/api/auth | /register | POST | 注册 |
+| /app/api/chat | /conversations | GET/POST | 对话列表/创建 |
+| /app/api/chat | /conversations/{id}/messages | POST | 发送消息（非流式） |
+| /app/api/chat | /conversations/{id}/messages/stream | POST | **SSE 流式聊天** |
+| /app/api/chat | /models | GET | 可用模型列表 |
+| /app/api/chat | /media/relay | GET | 媒体代理 |
+| /app/api/market | /apps | GET | 应用市场列表 |
+| /app/api/market | /apps/{id} | GET | 应用详情 |
+| /app/api/knowledge | /search | POST | 知识库搜索 |
+
+### 5.2 后台 API（管理面）
+
+| 路由前缀 | 说明 |
+|---------|------|
+| /app/api/admin/users | 用户管理 |
+| /app/api/admin/models | 模型管理 |
+| /app/api/admin/skills | 技能管理 |
+| /app/api/admin/agents | Agent 管理 |
+| /app/api/admin/mcp | MCP 服务管理 |
+| /app/api/admin/workflow | 工作流管理 |
+| /app/api/admin/market | 市场管理 |
+| /app/api/admin/analytics | 数据分析 |
+| /app/api/admin/developer | 开发者 API |
+| /app/api/admin/settings | 站点设置 |
+| /app/api/admin/storage | 存储管理 |
+| /app/api/admin/logs | 日志查看 |
+| /app/api/admin/automation | 自动化任务 |
+
+### 5.3 SSE 事件类型
+
+```
+POST /conversations/{id}/messages/stream
+Content-Type: text/event-stream
+
+事件帧:
+  data: {"type":"reasoning","content":"..."}   // 模型推理过程
+  data: {"type":"delta","content":"..."}        // 逐字回复增量  
+  data: {"type":"step","step":{...}}            // 工具调用步骤
+    step.type: "thinking" | "skill" | "mcp"
+  data: {"type":"done","message_id":"..."}      // 流结束
+```
+
+---
+
+## 六、核心管道与工作流
+
+### 6.1 消息处理管道（主循环）
+
+```
+用户消息
+  → 鉴权（JWT Bearer）
+  → 上下文恢复（skill_ids/agent_ids/mcp_ids 跨轮继承）
+  → 技能解析（显式选择 → 自动发现 → Agent 合并）
+  → MCP 工具列表拉取（带缓存 TTL 120s，按 url + transport 缓存）
+  → 知识库检索（RAG，BM25 + vector hybrid）
+  → System Prompt 组装（AGENT_GUIDE + platform_knowledge + agent_role + skill_desc + kb_context）
+  → Function Definitions 组装（skills → tools + MCP → tools + install_app）
+  → LLM 调用（OpenAI 兼容协议，stream=True）
+  → Tool Calls 循环（max 15 轮，每轮 tool_policy 沙箱检查）
+     ├── MCP Tool → call_mcp_tool() via Anthropic SDK
+     ├── Skill → _execute_skill_tool() 指令转发
+     └── install_app → 安装到市场
+  → 工具结果回注 → 继续 LLM 循环 → 最终回复
+  → 上下文压缩（后台异步，fire-and-forget）
+  → 结构化记忆抽取（实体/事实/偏好/决策/待办 五类）
+  → 媒体生成（后台 daemon 线程，独立事件循环）
+```
+
+### 6.2 模型路由与 Failover 管道
+
+```
+模型选择 → 解析 api_url/api_key/provider.auth_header
+  → build_openai_client（httpx.Timeout + trust_env=False + auth_header 支持）
+  → 首次调用失败（Exception）→ continue 下一个模型
+  → 备用模型列表（order_by is_default desc × 5）
+  → 成功 → break
+  → 全部失败 → 返回错误消息
+```
+
+### 6.3 MCP 协议管道
+
+```
+Client: mcp_client.py (官方 Anthropic SDK)
+  list_mcp_tools(server) → tools/list (JSON-RPC)
+    ⇢ 缓存: _TOOLS_CACHE[url] = (timestamp, tools), TTL 120s
+  call_mcp_tool(server, name, arguments) → tools/call (JSON-RPC)
+    ⇢ 返回: text content blocks → 拼接为字符串 → 反馈给 LLM
+
+传输层:
+  streamable_http (默认) → streamablehttp_client()
+  sse → sse_client()
+
+Schema 适配:
+  MCP inputSchema (JSON Schema 2020-12) → _normalize_mcp_schema()
+    ⇢ 展开 $ref → 处理 oneOf/anyOf → allOf 合并 → 剥离非 OpenAI 关���字
+    ⇢ 转为 OpenAI function calling 兼容的 parameters
+
+认证:
+  Authorization: Bearer {key} (默认)
+  api-key: {key} (MiMo Token Plan 等自定义)
+```
+
+### 6.4 Agent 编排管道（DAG 图引擎）
+
+```
+YAML 定义 → validate_graph() → topological_layers() (Kahn算法)
+  → 按层并行执行 (asyncio.gather)
+  
+节点类型:
+  llm     → _build_system_prompt + LLM 调用
+  local   → _execute_skill_tool (本地技能)
+  external → _call_external_agent (Dify/n8n/Coze 远程)
+  reduce  → 多路结果聚合
+
+边: 有向边定义数据流 → 拓扑排序 → 分层并行
+失败隔离: per-node on_error=halt|continue
+并发安全: 每节点独立 SessionLocal()
+
+预处理流水线:
+  外部 Agent endpoint → 直接远程调用（跳过本地 LLM）
+  Orchestrator → run_graph() → 图执行 → 聚合回答
+```
+
+### 6.5 媒体生成管道
+
+```
+SSE 回复结束 → _launch_media_task_bg()
+  → daemon Thread → asyncio.run(_generate_media_task)
+    → 独立事件循环（不阻塞主 uvicorn 循环）
+    → HTTP 调用图片/视频生成 API
+    → 写入存储 → 更新 Message 记录
+    → 前端轮询 → 渲染结果
+```
+
+### 6.6 上下文压缩管道
+
+```
+(后台异步, fire-and-forget, 不阻塞用户响应)
+
+旧消息 (>20 条保护窗口外)
+  → 分块 (CHUNK=30) → _summarize_via_llm()
+  → chunk_summaries 合并
+  → _recursive_compress() (depth≤3, budget=700 tokens)
+  → _extract_structured_memory()
+    实体/事实/偏好/决策/待办 五类
+  → _merge_structured_memory(old, new)
+  → ConversationSummary 写入 PG
+```
+
+---
+
+## 七、前端架构
+
+### 7.1 路由设计
+
+```
+前台 (/):
+  /login                      - 登录
+  /chat[/:id]                 - AI 对话（核心页面，SSE 流式）
+  /knowledge                  - 知识库管理
+  /market                     - 应用市场（Skills/MCP/Agents）
+  /token                      - Token 用量面板
+  /pricing                    - 定价/会员
+  /profile                    - 个人中心
+  /assets[/novel/:id]         - 资产/小说
+  /evolution                  - 进化仪表板
+  /wechat-bot                 - 微信 Bot
+  /im-bots                    - 多平台 IM Bot Hub
+  /app-services               - 应用服务
+
+后台 (/admin):
+  /admin                      - 仪表板
+  /admin/users                - 用户管理
+  /admin/models               - 模型管理
+  /admin/skills               - 技能管理
+  /admin/agents               - Agent 管理
+  /admin/mcp                  - MCP 管理
+  /admin/workflow             - 工作流
+  /admin/market               - 市场审核
+  /admin/knowledge            - 知识库管理
+  /admin/code-exec            - 代码执行
+  /admin/storage              - 存储管理
+  /admin/developer[/tools]    - 开发者 API/工具
+  /admin/automation           - 自动化任务
+  /admin/settings             - 站点设置
+  /admin/analytics            - 数据分析
+  /admin/logs                 - 日志
+  /admin/membership           - 会员管理
+  /admin/payment              - 支付配置
+  /admin/services             - 增值服务
+  /admin/ads                  - 广告管理
+  /admin/apps                 - 应用管理
+```
+
+### 7.2 核心组件
+
+| 组件 | 文件 | 功能 |
+|------|------|------|
+| ChatPage | front/ChatPage.tsx | SSE 流式聊天、Step 渲染、推理展示 |
+| AiProcessBlock | ChatPage.tsx 内 | 工具调用过程可视化（⏳/✅/❌） |
+| MarketPage | front/MarketPage.tsx | 应用市场网格、分类筛选 |
+| FrontLayout | components/layout/FrontLayout.tsx | 前台 sidebar + main 布局 |
+| AdminLayout | components/layout/AdminLayout.tsx | 后台 sidebar + main 布局 |
+
+### 7.3 设计系统
+
+```
+CSS 变量（global.css :root）:
+  --color-accent: #5B5FED
+  --color-bg-primary: #F8F9FB
+  --sidebar-width: 240px
+  --space-xs..4xl: 4px..40px
+  --radius-md..3xl: 8px..20px
+
+防溢出: html/body/.front-main { overflow-x: hidden }
+响应式: @media (max-width: 1200px/768px) 断点
+```
+
+---
+
+## 八、安全设计
+
+### 8.1 认证
+
+- JWT Bearer Token 认证（FastAPI HTTPBearer）
+- Casdoor OAuth2/OIDC 统一认证（可选）
+- Token 前端存内存，401/403 清 token 跳 /login
+
+### 8.2 授权
+
+- 前台: 用户级（需登录）
+- 后台: 管理员级（role=admin）
+- API Key: 支持 per-model key 覆盖 provider key
+
+### 8.3 工具调用沙箱
+
+```
+_check_tool_policy() 三层防护:
+  1. 白名单: agent 只允许调特定 skill_ids + mcp_ids
+  2. 预算: max_calls_per_conversation 上限
+  3. 每轮上限: per_round_cap
+
+代码执行: 独立 executor 容器沙箱
+密钥管理: credential.py 加解密存储
+```
+
+---
+
+## 九、运维架构
+
+### 9.1 CI/CD
+
+```
+Git push → pre-push hook (.git/hooks/pre-push)
+  → 容器内 backend pytest (28 用例)
+  → 容器内 frontend vitest (2 文件, 15 用例)
+  → 全绿 → push 放行
+  → 失败 → block
+
+部署:
+  docker cp 容器文件 → 宿主 Git
+  → git add -A + commit
+  → docker commit → qihuaiflow:with-deps (新镜像)
+  → docker compose up -d --force-recreate
+```
+
+### 9.2 健康检查
+
+```
+/health          → 200 {status: "ok"}     (liveness)
+前端 :8080       → 200 HTML               (SPA)
+后端 :18080/docs → 200 Swagger UI
+容器: docker restart → < 20s 恢复
+```
+
+### 9.3 监控栈
+
+```
+Prometheus (scrape) ← node-exporter (host) + Alloy (logs)
+Grafana (visualize) ← Prometheus datasource
+应用日志: Python logging → docker logs / Alloy 采集
+```
+
+---
+
+## 十、市场竞争分析
+
+### 10.1 护城河
+
+| 护城河 | 具体实现 | 壁垒强度 |
+|--------|---------|---------|
+| **多模型协议适配层** | OpenAI/Anthropic/Token Plan 三种认证头、MCP Schema → OpenAI 转换 | 🔴 高 |
+| **Skill 全生命周期** | 发布→审核→上架→安装→执行→进化，闭环 | 🔴 高 |
+| **Agent DAG 编排** | 拓扑排序+分层并行+失败隔离+外部 Agent 远程调用 | 🟡 中 |
+| **工具调��标准化** | AGENT_GUIDE + tool_policy 沙箱 + 15 轮 loop + 错误自修正 | 🟡 中 |
+| **PG 统一数据层** | 主库+向量+Casdoor 同集群 pgvector，混合检索零延迟 | 🟡 中 |
+| **IM Bot 多平台** | 统一消息网关，微信/企业微信/飞书/QQ | 🟢 低 |
+| **安全沙箱** | Tool Policy 白名单+预算+代码执行容器隔离 | 🟡 中 |
+
+### 10.2 竞品对比
+
+| 维度 | 七虎AI | Dify | Coze | 扣子 | FastGPT |
+|------|--------|------|------|------|---------|
+| 模型聚合 | ✅ 手动 failover | ✅ | ✅ | ✅ | ✅ |
+| Skill 市场 | ✅ 上架-安装-进化 | ❌ | ❌ (Plugin) | ❌ (Plugin) | ❌ |
+| MCP 协议 | ✅ 官方 SDK | ✅ | ❌ | ❌ | ❌ |
+| Agent DAG | ✅ 图引擎 | ✅ 工作流 | ✅ 工作流 | ✅ 工作流 | ❌ 简单 |
+| IM Bot | ✅ 多平台 | ❌ | ❌ | ✅ 飞书 | ❌ |
+| PG 全栈 | ✅ PG18 | ⚠️ MySQL | ? | ? | ✅ PG |
+| Auth | ✅ Casdoor+JWT | ✅ | ✅ | ✅ | ✅ |
+
+### 10.3 扩展能力
+
+| 扩展方向 | 当前能力 | 增长空间 |
+|---------|---------|---------|
+| 模型厂商 | 4 家 | 新增厂商只需配 ModelProvider |
+| Skill 类型 | 14 场景分类 | 支持自定义执行器（非纯 LLM 转发） |
+| MCP 服务 | 任意 MCP Server | MCP Registry 对接 |
+| Agent | Dify/n8n/Coze + 自研 DAG | CrewAI/LangGraph 集成 |
+| 前端渠道 | Web Chat + IM Bot | API/Webhook/SDK |
+| 计费 | Token + 会员 | 按 Skill/MCP 调用计费 |
+
+---
+
+## 十一、迭代路线图
+
+### 已完成
+
+- [x] PostgreSQL 迁移（MySQL → PG18 + pgvector）
+- [x] SSE 四类事件（reasoning/delta/step/done）
+- [x] MCP 协议标准化（官方 SDK，Schema 转换）
+- [x] Agent DAG 编排引擎 + YAML workflow
+- [x] 工具调用标准化（AGENT_GUIDE + install_app 优化 + max_rounds 15 + MCP 命名）
+- [x] 模型 Failover + 事件循环防冻（#812）
+- [x] Token Plan 适配（MiMo custom auth_header）
+- [x] 前端 Step 渲染增强（⏳/✅/❌ 状态）
+- [x] 横向溢出防护（overflow-x: hidden 三层）
+- [x] 知识库 KG 构建
+- [x] 多平台 IM Bot Hub
+- [x] Prometheus+Grafana 监控栈
+
+### 进行中
+
+- [ ] Skill 真实执行器（非 LLM 转发模拟）
+- [ ] 多 Agent 协作（Supervisor 模式）
+- [ ] API/OpenAPI 对外接口
+- [ ] 技能 SDK 发布工具
+
+### 计划中
+
+- [ ] LiteLLM 集成（统一模型路由+成本追踪）
+- [ ] 流式 Token 计费（精确到字符级）
+- [ ] LangGraph 工作流引擎
+- [ ] 向量混合检索增强（BM25 + dense + sparse）
+- [ ] 前端暗色模式
+- [ ] 多语言（i18n）
+- [ ] 移动端适配
+
+---
+
+> **文档维护规则**: 每次系统重大迭代后，更新本文档对应章节并变更版本号。
+> **上传位置**: Gitea 仓库 `qihuaiflow/docs/ARCHITECTURE.md`