diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..0fae9f8 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -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`