# 七虎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`