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