docs: 全面更新 README.md + ARCHITECTURE.md v3.0

ARCHITECTURE.md v3.0: 护城河分析,容器拓扑,技术栈矩阵,功能架构,双Claw单引擎,模型同步,安全纵深,qihu-design-system,迭代路线. README.md v3.0: 快速开始,核心能力,架构总览,项目结构,开发指南,平台数据.
2026-08-12 09:20:55 +08:00
1 parent 54b444b651
commit d2d133f22a
@@ -0,0 +1,416 @@
+# 七虎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次重试 + 指数退避 |