From d2d133f22aeae57464534400059567d7c2eb8930 Mon Sep 17 00:00:00 2001 From: qihu-bot Date: Wed, 12 Aug 2026 09:20:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=9D=A2=E6=9B=B4=E6=96=B0=20?= =?UTF-8?q?README.md=20+=20ARCHITECTURE.md=20v3.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ARCHITECTURE.md v3.0: 护城河分析,容器拓扑,技术栈矩阵,功能架构,双Claw单引擎,模型同步,安全纵深,qihu-design-system,迭代路线. README.md v3.0: 快速开始,核心能力,架构总览,项目结构,开发指南,平台数据. --- ARCHITECTURE.md | 416 +++++++++++++++++++++++ README.md | 661 +++++++++--------------------------- docs/ARCHITECTURE.md | 784 ++++++++++++++++++------------------------- 3 files changed, 910 insertions(+), 951 deletions(-) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..244a216 --- /dev/null +++ b/ARCHITECTURE.md @@ -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` + `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次重试 + 指数退避 | diff --git a/README.md b/README.md index 0894b9a..edf6529 100644 --- a/README.md +++ b/README.md @@ -1,546 +1,217 @@ -# Qihu-AIFlow 智能自动化PaaS平台 +# 七虎AI — 智能自动化 PaaS 平台 -## 项目概述 +> **私有化部署 | 零代码 AI SOP | 多模型聚合 | 技能市场 | IM Bot** -Qihu-AIFlow 是一套**私有化部署、面向个人及小微企业的AI自动化SOP一站式PaaS平台**。用户无需编码即可落地全流程AI自动化业务，平台提供AI对话、知识管理、技能市场、Token计费、会员订阅等完整闭环体验。 - -**版本**: v2.0.1 -**构建日期**: 2026-06-02 -**仓库地址**: http://git.qihuyun.com/qyyfw/qihuaiflow +**版本**: v3.0 | **构建日期**: 2026-08-12 | **公网**: https://ai.qihuyun.com | **后台**: `admin / admin123` --- -## 技术环境 - -### 技术栈 - -| 层级 | 技术 | 说明 | -|------|------|------| -| 前端框架 | React 18 + TypeScript | 现代化响应式UI，HashRouter前端路由 | -| 构建工具 | Vite 5 | 快速HMR开发服务器，高效生产构建 | -| UI样式 | CSS Modules | 组件级样式隔离 | -| 后端框架 | Python 3.11 + FastAPI | 高性能异步Web框架，自动生成OpenAPI文档 | -| ORM | SQLAlchemy 2.0 | 全功能Python ORM，支持MySQL方言 | -| 数据库 | MySQL 8.0 | 关系型数据库，InnoDB引擎，utf8mb4编码 | -| 缓存 | Redis 7 | 内存缓存，支持持久化(AOF)，事件总线 | -| Web服务器 | Nginx | 反向代理 + 静态资源服务 | -| 容器化 | Docker + Docker Compose | 一键构建部署，环境隔离 | -| API认证 | JWT (python-jose) | 无状态Bearer Token认证 | -| 密码加密 | bcrypt | 安全的密码哈希存储 | -| 实时通信 | SSE (Server-Sent Events) | AI对话流式输出 | -| IM平台接入 | 平台适配器模式 | 飞书/微信/钉钉/WhatsApp/Telegram/Slack统一抽象 | -| 微信集成 | ClawBot API | 微信个人号扫码绑定，官方API对接 | - -### 核心组件 - -| 组件 | 版本 | 用途 | -|------|------|------| -| MySQL | 8.0 | 用户数据、聊天记录、知识库、订单、配置等持久化存储 | -| Redis | 7-alpine | 会话缓存、事件总线(发布/订阅)、API限流 | -| Nginx | latest | 前端静态资源服务(:8080)、后端API反向代理(:18080) | -| Python | 3.11-slim | 后端API服务运行环境 | -| Node.js | LTS | Docker镜像内前端构建（Dockerfile中安装） | - ---- - -## 系统架构 - -### 架构设计图 - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ 用户浏览器 │ -│ https://bot.qihuyun.com │ -└──────────────────────────────┬──────────────────────────────────────┘ - │ - ▼ -┌──────────────────────────────────────────────────────────────────────┐ -│ Docker: qihu-aiflow 容器 │ -│ │ -│ ┌─────────────────────────────────────────────┐ │ -│ │ Nginx (:8080) │ │ -│ │ / → frontend/dist (静态SPA) │ │ -│ │ /app/ → proxy localhost:18080/app/ │ │ -│ └─────────────────────────────────────────────┘ │ -│ │ │ -│ ┌─────────────────────────────────────────────┐ │ -│ │ FastAPI + Uvicorn (:18080) │ │ -│ │ ┌───────────┐ ┌──────────┐ ┌───────────┐ │ │ -│ │ │ auth │ │ chat │ │ channels │ │ │ -│ │ │ knowledge │ │ market │ │ token │ │ │ -│ │ │ payment │ │ profile │ │ assets │ │ │ -│ │ │ evolution │ │ admin/* │ │ webhook │ │ │ -│ │ └───────────┘ └──────────┘ └───────────┘ │ │ -│ │ ┌──────────────────────────────────────┐ │ │ -│ │ │ 平台适配器层 │ │ │ -│ │ │ feishu│wechat│dingtalk│slack│... │ │ │ -│ │ └──────────────────────────────────────┘ │ │ -│ └─────────────────────────────────────────────┘ │ -│ │ │ -└────────────────────────┼─────────────────────────────────────────────┘ - │ - ┌──────────────┴──────────────┐ - ▼ ▼ -┌──────────────────┐ ┌──────────────────┐ -│ MySQL 8.0 │ │ Redis 7 │ -│ :3306 │ │ :6379 │ -│ 容器: qihu- │ │ 容器: qihu- │ -│ aiflow-mysql │ │ aiflow-redis │ -└──────────────────┘ └──────────────────┘ - -━━━━━━━━━━━━━━━━ 外部集成 ━━━━━━━━━━━━━━━━ - - ClawBot API AI模型供应商 微信/支付宝 - (微信IM绑定) (OpenAI兼容) (支付网关) -``` - -### 请求流程 - -``` -用户请求 → Nginx(:8080) → /app/* → Uvicorn(:18080) → FastAPI路由 - ↓ - JWT认证中间件 - ↓ - SQLAlchemy ORM - ↙ ↘ - MySQL 8.0 Redis 7 -``` - -### 数据隔离 - -- 所有用户数据查询强制带 `user_id` 过滤，实现物理级数据隔离 -- 前后台权限分离：`role: admin` 可访问 `/admin/*` 路由 -- API密钥独立管理，支持颁发/撤销 - ---- - -## 功能模块 - -### 前台功能（10大模块） - -#### 1. AI聊天 -- 多模型对话：支持切换不同AI模型供应商和模型 -- 流式输出(SSE)：AI回复实时逐字展示 -- 知识库关联：选择知识库让AI基于专属知识回答 -- Agent/技能调用：Tool-call机制自动调用关联技能 -- 会话管理：创建/归档/置顶/搜索会话 -- 对话历史：完整的用户-AI对话记录 - -#### 2. 频道（IM接入） -- 多平台支持：飞书、微信、钉钉、WhatsApp、Telegram、Slack -- **微信**: 对接ClawBot官方API，扫码绑定微信个人号 - - 调用 `POST /api/v1/wechat/qrcode` 获取官方二维码 - - 轮询 `POST /api/v1/wechat/qrcode/status` 等待扫码确认 - - 自动保存 bot_token/ilink_bot_id/baseurl 等凭据 - - 支持 `POST /api/v1/wechat/channel_reset` 重置通道 -- 统一Webhook端点：`POST /app/api/channels/webhook/{platform}` 接收各平台消息 -- AI行为配置：Bot前缀、流式输出、私聊/群聊策略、白名单 -- 平台适配器模式：签名验证 + 消息解析 + 统一格式 -- 频道成员管理：邀请/移除成员 - -#### 3. 知识库 -- 文档上传管理：PDF/Word/TXT等多格式支持 -- 目录组织：多级目录结构管理文档 -- AI知识图谱：LLM自动提取实体和关系 -- Canvas可视化：节点拖拽、悬停高亮、点击详情 -- Pipeline自动构建：知识库变更触发自动更新 - -#### 4. 应用市场 -- 应用浏览：分类展示，详情查看 -- 搜索去重：智能搜索，防止重复 -- 购买安装：付费后一键安装 -- 卸载管理：支持卸载后重新安装（状态重置） -- 后台审核：应用上架审核流程 - -#### 5. Token驾驶舱 -- 消耗概览：今日/累计/日均Token统计 -- 用量图表：按模型、日期维度可视化 -- CSV导出：消耗明细数据导出下载 -- 一键充值：快捷跳转付费中心 -- 服务器时间：上海时区(UTC+8)实时同步 - -#### 6. 付费中心 -- 会员订阅：多等级会员体系（基础/高级/企业） -- 增值服务：单项服务购买 -- 实名认证：身份信息验证 -- 支付集成：微信支付 + 支付宝双渠道 -- 自动续费：会员到期自动续订 - -#### 7. 资产中心 -- 文件上传：支持多种格式 -- 分类管理：按文件类型自动归类 -- 在线预览：Office文档(Word/Excel/PPT) + PDF -- AI图像生成：广告图/配图AI生成 -- 去重存储：按ID去重节省空间 - -#### 8. AI进化 -- 进化Pipeline：自动化知识图谱构建流程 -- 配置管理：启动/停止/参数调整 -- 监控面板：Pipeline状态、进度实时展示 -- 自动恢复：系统重启后自动恢复运行中的Pipeline - -#### 9. 个人中心 -- 用户资料：修改头像、邮箱、手机号 -- 密码修改：安全的密码更新 -- 会员信息：等级、到期时间查看 - -#### 10. 消息通知 -- 系统通知：平台公告、功能更新 -- 应用通知：安装/更新提醒 -- 付费通知：订单状态变更 - -### 后台管理（13大模块） - -#### 1. 平台驾驶舱 -- 核心指标：用户总数、活跃模型数、今日订单、Token消耗 -- Token统计面板：今日/累计/日均消耗，活跃模型数 -- 快捷入口：大模型库、网站设置、支付配置、增值服务等 -- 操作日志：最近管理员操作记录 -- 审计日志：安全审计追踪 - -#### 2. 用户管理 -- 用户列表：搜索、筛选、分页 -- 角色管理：admin / user 角色分配 -- 状态管理：激活 / 封禁用户 -- 用户详情：基本信息、会员状态 - -#### 3. 大模型库管理 -- 模型供应商：添加/编辑AI模型供应商 -- 模型配置：模型名称、API地址、API密钥 -- 默认模型：设置全局默认使用的模型 - -#### 4. 供应商管理 -- 供应商配置：管理第三方AI服务提供商 -- API密钥管理：密钥加密存储 - -#### 5. 网站基础设置 -- 站点信息：网站名称、Logo、描述 -- 邮件配置：SMTP服务器 + 测试发送 -- 短信配置：短信服务配置 -- AI内容生成：AI辅助生成网站文案 - -#### 6. 支付渠道配置 -- 微信支付：商户号、API密钥配置 -- 支付宝：AppID、商户私钥配置 - -#### 7. 增值服务管理 -- 服务列表：所有增值服务CRUD -- 定价管理：服务价格设置 -- 上下架：控制服务可用状态 - -#### 8. 会员订阅体系 -- 会员等级：多等级定义和权限 -- 订阅计划：时长、价格配置 -- 自动化规则：会员自动升级/降级 - -#### 9. 广告位管理 -- Banner管理：图片上传、排序 -- AI图像生成：AI自动生成广告图 -- 投放配置：位置、展示频率 - -#### 10. 应用市场审核 -- 应用审核：审核上架应用 -- 优惠券管理：创建/发放优惠券 - -#### 11. 频道管理 -- 频道监控：查看所有频道状态 -- 平台配置：各平台接入凭证和AI行为配置 - -#### 12. 知识库管理 -- 知识库概览：查看系统所有知识库 -- 文档管理：文档列表和状态 - -#### 13. 日志与风控 -- 操作日志：管理员操作审计 -- API调用日志：接口调用统计 -- 付费日志：订单和交易记录 - ---- - -## Docker 部署手册 - -### 前置条件 - -- Docker Engine 20.10+ -- Docker Compose v2+ -- 可用磁盘空间 ≥ 10GB -- 宿主机端口：12888（前端）、18080（后端）、3306（MySQL）、6379（Redis） - -### 方式一：从 Git 仓库部署 +## 🚀 快速开始 ```bash # 1. 克隆仓库 git clone http://git.qihuyun.com/qyyfw/qihuaiflow.git cd qihuaiflow -# 2. 构建并启动所有服务（MySQL + Redis + AIFlow） -docker compose up -d --build +# 2. 配置环境 +cp .env.example .env # 编辑 API keys -# 3. 等待服务就绪（首次构建约3-5分钟） -# 查看日志确认启动完成 -docker compose logs -f aiflow +# 3. 一行启动 +docker-compose up -d -# 4. 访问系统 -# 前端: http://<宿主机IP>:12888 -# 默认账号: admin / admin123 +# 4. 访问 +open https://ai.qihuyun.com # 前台 +open https://ai.qihuyun.com/admin # 后台 ``` -### 方式二：从程序包部署 +**前置要求**: Docker Compose v2 + 8GB RAM -```bash -# 1. 解压程序包 -tar -xzf Qihu-aiflow.tar.gz -cd <解压目录> +--- -# 2. 修改环境变量（可选，编辑 .env 或 docker-compose.yml） -# vim .env +## ✨ 核心能力 -# 3. 构建并启动 -docker compose up -d --build - -# 4. 验证 -curl http://localhost:12888/ # 前端 -curl http://localhost:18080/app/api/health # 后端 -``` - -### Docker Compose 自动执行流程 - -`docker compose up -d --build` 启动后会自动： - -1. **拉取基础镜像**: python:3.11-slim, mysql:8.0, redis:7-alpine -2. **构建AIFlow镜像**: - - 安装系统依赖 (nginx, mysql-client, redis-tools, build-essential) - - 安装 Python 依赖 (requirements.txt, 使用清华镜像源) - - 安装 Node.js + npm，构建前端 `npm install && npm run build` - - 配置 Nginx 反向代理 -3. **启动MySQL**: 等待健康检查通过 (mysqladmin ping) -4. **启动Redis**: 密码认证 (requirepass pwd2026) -5. **初始化数据库**: - - 创建数据库 `aiflow` (utf8mb4) - - 按序执行 migrations/ 下 15 个 SQL 迁移脚本 - - 智能检测 admin 密码哈希有效性，仅在无效时重置 -6. **启动应用**: Nginx(:8080) + Uvicorn(:18080) - -### 端口说明 - -| 端口 | 服务 | 说明 | +| 能力 | 描述 | 状态 | |------|------|------| -| 12888 | Nginx (前端) | 用户浏览器访问端口 | -| 18080 | Uvicorn (后端API) | API服务端口 | -| 3306 | MySQL | 数据库端口 | -| 6379 | Redis | 缓存端口 | +| 🤖 **AI 对话** | SSE 流式对话、多模型自动路由、Markdown 渲染、代码高亮 | ✅ 生产 | +| 📚 **知识库 RAG** | 文档上传 → 切片 → pgvector 向量化 → BM25+语义检索 | ✅ 生产 | +| 🛒 **技能市场** | 97+ Skill 发现-安装-执行，Meilisearch 中文搜索，14 类 capability | ✅ 生产 | +| 🎨 **媒体生成** | 图片/视频 AI 生成，media relay 中转，微信内联渲染 | ✅ 生产 | +| 📊 **Token 驾驶舱** | 实时用量监控、趋势图表、预警告警、计费追踪 | ✅ 生产 | +| 💰 **会员订阅** | 多套餐对比、微信支付、增值单点付费 | ✅ 生产 | +| 🏪 **应用市场** | 第三方应用集成，产品定价，webhook 回调 | ✅ 生产 | +| 🤖 **Agent 编排** | DAG 图引擎 + Supervisor 模式 | 🔨 迭代中 | +| 📱 **IM Bot** | 微信扫码连接，AI 对话 + 图片生成 | ✅ 生产 | +| 🛡️ **安全纵深** | 四层防护: 限流+扫描器拦截+IP黑名单+JWT认证 | ✅ 生产 | -**注意**: 前端映射到宿主机 12888 端口（而非 8080），用户访问: `http://:12888` +--- -### 环境变量配置 +## 🏗️ 架构总览 -Docker Compose 环境变量在 `docker-compose.yml` 的 `environment` 段配置： +``` +┌──────────────────────────────────────────────────┐ +│ React SPA (Vite 5 + Tailwind 4) │ +│ Landing | Chat | Knowledge | Market | Agent │ +├──────────────────────────────────────────────────┤ +│ Nginx (限流 + 扫描器 + SSL) │ +├──────────────────────────────────────────────────┤ +│ FastAPI uvicorn (Python 3.11) │ +│ EngineCore (双 Claw 单引擎) | LLM Router │ +├──────────────────────────────────────────────────┤ +│ LiteLLM │ MCP SDK │ Casdoor OAuth │ +│ (模型网关) │ (工具协议) │ (统一认证) │ +├──────────────────────────────────────────────────┤ +│ PostgreSQL+pgvector │ Redis │ Meilisearch │ +└──────────────────────────────────────────────────┘ +``` -| 变量 | 说明 | Docker默认值 | 本地默认值 | -|------|------|-------------|-----------| -| `MYSQL_HOST` | MySQL地址 | mysql (容器名) | localhost | -| `MYSQL_PORT` | MySQL端口 | 3306 | 3306 | -| `MYSQL_USER` | MySQL用户名 | root | root | -| `MYSQL_PASSWORD` | MySQL密码 | pwd2026 | pwd2026 | -| `MYSQL_DATABASE` | 数据库名 | aiflow | aiflow | -| `REDIS_HOST` | Redis地址 | redis (容器名) | localhost | -| `REDIS_PORT` | Redis端口 | 6379 | 6379 | -| `REDIS_PASSWORD` | Redis密码 | pwd2026 | pwd2026 | -| `SECRET_KEY` | JWT签名密钥 | (固定值) | (固定值) | -| `APP_ACCESS_URL` | 外网访问地址 | https://bot.qihuyun.com | https://bot.qihuyun.com | -| `DEBUG` | 调试模式 | false | false | +详见 [ARCHITECTURE.md](ARCHITECTURE.md) -**重要**: 生产环境请修改 `SECRET_KEY`、`MYSQL_PASSWORD`、`REDIS_PASSWORD`。 +--- -### 管理员账号 +## 📦 技术栈 -部署后默认管理员账号： +| 层 | 技术 | +|----|------| +| 前端 | React 18 + TypeScript 5.6 + Vite 5 + Tailwind CSS 4 + Zustand 5 | +| 后端 | Python 3.11 + FastAPI + SQLAlchemy 2.0 + Pydantic | +| 数据库 | PostgreSQL 18 + pgvector (向量) + Redis 7 (缓存) | +| 认证 | Casdoor (OAuth2/OIDC) + JWT | +| LLM 网关 | LiteLLM (模型路由 + 费用追踪 + 协议转换) | +| 搜索引擎 | Meilisearch v1.11 (BM25 + jieba 中文分词) | +| 可观测 | Prometheus + Grafana + Alloy (OTel) | +| 部署 | Docker Compose (一行启动，自包含) | +| 设计 | qihu-design-system (53 modules, indigo #5B5FED) | -| 用户名 | 密码 | 角色 | -|--------|------|------| -| admin | admin123 | 超级管理员 | +--- -> 首次登录后请立即修改密码：进入「个人中心」页面进行修改。 -> run.sh 会智能检测密码哈希有效性——如果用户已修改密码（有效bcrypt哈希），则保持不变。 +## 🗂️ 项目结构 -### 常用命令 +``` +qihuaiflow/ +├── backend/python/app/ # FastAPI 后端 +│ ├── api/ # API 路由 +│ │ ├── admin/ # 后台管理 API (models/skills/agents/users/...) +│ │ ├── chat.py # AI 对话核心 (SSE流式 + 媒体生成) +│ │ ├── auth.py # JWT 认证 +│ │ └── im_llm.py # IM Bot LLM 薄壳 +│ ├── core/ # 核心引擎 +│ │ ├── llm_router.py # LLM 路由 + 熔断 +│ │ ├── claw_adapters.py # 双 Claw 适配器 (SSE/Buffer) +│ │ ├── litellm_sync.py # LiteLLM 模型同步服务 +│ │ ├── node_registry.py # Agent 节点注册 +│ │ └── capability_discovery.py # 能力发现 +│ └── models/ # 数据库模型 +├── frontend/ # React 前端 +│ └── src/ +│ ├── pages/admin/ # 后台页面 (39 modules) +│ ├── pages/front/ # 前台页面 +│ ├── components/ # 设计系统组件 +│ │ ├── ui/ # Button/Badge/Input/Card +│ │ ├── canvas/ # GenUiCard/StatusRing/ChatComposer +│ │ └── layout/ # AppShell/ThemeToggle +│ └── styles/ # 全局 CSS + chat 样式 +├── nginx/ # Nginx 配置文件 +├── config/ # LiteLLM + 平台配置 +├── migrations/ # 数据库迁移 SQL +├── docker-compose.yml # Docker Compose 编排 +├── Dockerfile # 主应用镜像 +├── ARCHITECTURE.md # 架构设计文档 +└── DESIGN.md # 设计系统规范 +``` + +--- + +## 🔧 开发指南 + +### 环境要求 + +- Docker Compose v2 +- Python 3.11+ (本地开发) +- Node.js 22+ (前端开发) +- Git + +### 本地开发 ```bash -# 查看所有容器状态 -docker compose ps +# 后端 +cd backend/python +pip install -r requirements.txt +uvicorn main:app --reload --port 18080 -# 查看应用日志 -docker compose logs -f aiflow +# 前端 +cd frontend +npm install +npm run dev # Vite dev server :5173 +``` -# 查看MySQL日志 -docker compose logs -f mysql +### 部署 -# 重启应用 -docker compose restart aiflow +```bash +# 生产部署 +docker-compose up -d --build -# 停止所有服务 -docker compose down +# 查看状态 +docker-compose ps +docker logs qihu-aiflow --tail 50 -# 停止并清除数据（危险！） -docker compose down -v +# 重启 +docker restart qihu-aiflow +``` -# 重新构建并启动 -docker compose up -d --build +### 测试 -# 进入应用容器 -docker exec -it qihu-aiflow bash +```bash +# 后端测试 +docker exec qihu-aiflow bash -c "cd /app/backend/python && .venv/bin/python -m pytest" +# 当前: 165 passed / 2 skipped -# 进入MySQL -docker exec -it qihu-aiflow-mysql mysql -u root -ppwd2026 aiflow - -# 进入Redis -docker exec -it qihu-aiflow-redis redis-cli -a pwd2026 +# 前端测试 +docker exec qihu-aiflow bash -c "cd /app/frontend && npx vitest run" ``` --- -## 项目文件结构 +## 📊 平台数据 -``` -/ -├── frontend/ # 前端项目 (React + TypeScript) -│ ├── dist/ # 构建产物（Docker构建时生成） -│ ├── public/ # 静态资源 -│ ├── src/ # TypeScript源码 -│ │ ├── api/ # API客户端 (index.ts) -│ │ ├── components/ # 通用组件 (layout/) -│ │ ├── contexts/ # React上下文 -│ │ ├── hooks/ # 自定义Hooks -│ │ ├── mock/ # Mock数据（开发用） -│ │ ├── pages/ # 页面组件 -│ │ │ ├── admin/ # 后台管理页面 -│ │ │ └── front/ # 前台页面 -│ │ ├── styles/ # 全局样式 -│ │ └── types/ # TypeScript类型定义 -│ ├── package.json # 前端依赖配置 -│ ├── package-lock.json # 依赖锁文件 -│ └── vite.config.ts # Vite构建配置 -├── backend/python/ # 后端项目 (Python FastAPI) -│ ├── main.py # 应用入口 (FastAPI app) -│ ├── requirements.txt # Python依赖列表 -│ └── app/ # 应用核心代码 -│ ├── api/ # API路由模块 -│ │ ├── auth.py # 认证 (login/register) -│ │ ├── chat.py # AI聊天 (SSE流式) -│ │ ├── channels.py # IM频道管理 (ClawBot对接) -│ │ ├── knowledge.py # 知识库管理 -│ │ ├── market.py # 应用市场 -│ │ ├── token_usage.py # Token统计 -│ │ ├── payment.py # 付费中心 -│ │ ├── profile.py # 个人中心 -│ │ ├── assets.py # 资产管理 -│ │ ├── evolution.py # AI进化 -│ │ ├── notifications.py # 消息通知 -│ │ └── admin/ # 后台管理API -│ │ ├── dashboard.py # 驾驶舱 -│ │ ├── users.py # 用户管理 -│ │ ├── models.py # 模型管理 -│ │ ├── settings.py # 网站设置 -│ │ ├── payment_admin.py # 支付配置 -│ │ ├── services.py # 增值服务 -│ │ ├── membership_admin.py # 会员管理 -│ │ ├── ads.py # 广告管理 -│ │ ├── market_admin.py # 应用审核 -│ │ └── logs.py # 日志风控 -│ ├── models.py # SQLAlchemy数据模型 (全部表定义) -│ ├── database.py # 数据库连接配置 -│ ├── config.py # 应用配置 -│ ├── auth.py # JWT认证 & 权限控制 -│ ├── middleware/ # 中间件 -│ │ ├── log_middleware.py # API追踪中间件 -│ │ └── log_service.py # 操作日志服务 -│ ├── services/ # 业务服务 -│ │ └── evolution_service.py # 进化Pipeline服务 -│ ├── platform_adapter.py # 平台适配器基类 -│ └── platform_adapters/ # 各平台适配器实现 -│ ├── feishu_adapter.py -│ ├── wecom_adapter.py -│ ├── dingtalk_adapter.py -│ ├── whatsapp_adapter.py -│ ├── telegram_adapter.py -│ └── slack_adapter.py -├── migrations/ # 数据库迁移脚本 (001-015) -│ ├── 001_init.sql # 初始化表结构 -│ ├── 002_init_data.sql # 初始数据 -│ ├── ... -│ └── 015_production_fixes.sql # 生产修复 -├── docs/ # 项目文档 -│ ├── PRD.md # 产品需求文档 -│ ├── PRD-self-evolution.md # AI自进化PRD -│ ├── PRD-self-evolution-v2.md # AI自进化PRD v2 -│ └── frontend-dev-record.md # 前端开发记录 -├── Dockerfile # Docker镜像构建文件 -├── docker-compose.yml # Docker Compose编排配置 -├── nginx.conf # Nginx反向代理配置 -├── run.sh # 一键启动脚本 -├── .env # 环境变量配置 -├── .gitignore # Git忽略配置 -├── .dockerignore # Docker构建忽略配置 -├── VERSION # 版本信息 -├── CHANGELOG.md # 变更日志 -└── README.md # 项目文档（本文件） -``` - ---- - -## API接口概览 - -所有接口以 `/app/api/` 为前缀，完整OpenAPI文档访问: `http://:18080/docs` - -| 模块 | 基础路径 | 主要接口 | -|------|---------|---------| -| 认证 | `/app/api/auth` | login, register, logout, me | -| AI聊天 | `/app/api/chat` | conversations CRUD, messages, SSE流式 | -| 频道 | `/app/api/channels` | channels CRUD, webhook, 扫码授权, 状态轮询 | -| 知识库 | `/app/api/knowledge` | bases CRUD, documents, directories, graph | -| 应用市场 | `/app/api/market` | apps, install, uninstall | -| Token | `/app/api/token` | overview, stats, export CSV | -| 付费 | `/app/api/payment` | plans, orders, realname verification | -| 资产 | `/app/api/assets` | files CRUD, upload, preview | -| 进化 | `/app/api/evolution` | configs, pipeline status | -| 后台-仪表盘 | `/app/api/admin/dashboard` | stats, charts | -| 后台-用户 | `/app/api/admin/users` | users CRUD | -| 后台-模型 | `/app/api/admin/models` | providers, models CRUD | -| 后台-设置 | `/app/api/admin/settings` | site, email, sms config | -| 后台-支付 | `/app/api/admin/payment` | payment channel config | -| 后台-日志 | `/app/api/admin/logs` | operation, api, payment logs | - ---- - -## 数据库迁移 - -| 编号 | 说明 | +| 指标 | 数值 | |------|------| -| 001 | 初始化表结构（users, conversations, messages, channels等） | -| 002 | 初始数据（admin账号, 默认模型供应商, 种子数据） | -| 003 | 增值服务表 | -| 004 | OAuth状态字段 | -| 005 | 频道扩展字段（account_name, features） | -| 006 | API调用统计表 | -| 007 | 进化系统基础表 | -| 008 | 进化系统v2（EvolutionWatcher状态管理） | -| 009 | 支付实名认证字段 | -| 010 | 默认模型字段 | -| 011 | 知识库存储与资产表 | -| 012 | 生产环境列同步（幂等补全） | -| 013 | 知识图谱表（节点/边/构建记录） | -| 014 | 测试数据清理 | -| 015 | 生产修复（content列 + AppPurchase状态重置） | +| LLM 模型数 | 14 (含 OCR/Rerank/Embedding/TTS/ASR) | +| 技能数 | 97 | +| MCP 工具数 | 26 | +| 后台管理页面 | 39 | +| API 端点 | 300+ | +| 容器数 | 12 | +| 代码行数 | 50,000+ | --- -## 更新日志 +## 🌐 线上环境 -详见 `VERSION` 和 `CHANGELOG.md`。 +| 资源 | 地址 | +|------|------| +| 前台 | https://ai.qihuyun.com | +| 后台 | https://ai.qihuyun.com/admin | +| Grafana | http://210.16.161.218:3000 | +| Prometheus | http://210.16.161.218:9090 | +| Casdoor | http://210.16.161.218:8000 | +| Git 仓库 | http://git.qihuyun.com/qyyfw/qihuaiflow | -### v2.0.1 (2026-06-02) +--- -- 微信ClawBot官方API标准重构（频道扫码绑定） -- 6项生产缺陷修复（二维码、知识库、tool-call、应用安装、时区、邮件） -- 完整项目文档（README.md） -- Gitea仓库发布 +## 📝 更新日志 + +详见 [CHANGELOG.md](CHANGELOG.md) 和 [RELEASES.md](RELEASES.md) + +**v3.0 重点更新 (2026-08-12)**: +- ✅ 修复 `/admin/models` 空白页 (React hooks + 缓存问题) +- ✅ 实现 LiteLLM 模型同步 (管理员 UI → LiteLLM REST API) +- ✅ 实现 media_relay 端点 (微信 Bot 图片中转) +- ✅ 设计系统全量收口 + ErrorBoundary + safeLazy +- ✅ Docker Compose STORE_MODEL_IN_DB 模式 +- ✅ Nginx 限流 + 扫描器拦截 + IP 黑名单 + +--- + +## 📄 许可证 + +私有项目。© 2026 七虎AI. All rights reserved. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0fae9f8..244a216 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,84 +1,93 @@ -# 七虎AI PaaS 平台 — 架构设计与实施方案 v2.0 +# 七虎AI PaaS 平台 — 架构设计与实施方案 v3.0 -> **最后更新**: 2026-07-27 -> **版本**: v2.0 -> **用途**: 投喂 AI 大模型进行平台竞争力、护城河、扩展能力分析 +> **最后更新**: 2026-08-12 +> **版本**: v3.0 +> **用途**: 平台竞争力、护城河、技术框架、功能架构、业务逻辑完整文档 > **维护**: 随系统迭代实时更新 +> **仓库**: http://git.qihuyun.com/qyyfw/qihuaiflow --- -## 一、平台概述 +## 一、平台护城河 (Moat) -### 1.1 定位 +### 1.1 核心竞争壁垒 -七虎AI（qihuyun.com）是一个面向开发者和企业的 **AI PaaS 平台**，核心能力是聚合多厂商大模型、提供标准化工具调用层、支持 Skill/MCP/Agent 的发现-安装-编排-执行全生命周期管理。 +| 壁垒维度 | 具体实现 | 竞争门槛 | +|---------|---------|---------| +| **模型聚合网关** | 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 核心价值主张 +### 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 监控栈 + 日志审计 | +| 策略 | 我方 | 竞品(AI PaaS) | 竞品(垂直SaaS) | +|------|------|-------------|-------------| +| 模型数量 | 14+ 实时可增删 | 3-5 个 | 1 个 | +| 技能市场 | 97 个，自建生态 | 0-20 个 | 无 | +| IM Bot | 微信 + 企业微信扩展 | 无 | 自己开发 | +| 多租户 | PG RLS 行级安全 | 应用层隔离 | 单租户 | +| 部署 | Docker Compose 一行启动 | Kubernetes 复杂 | 无 Docker | +| 定价 | 免费层 + 会员订阅 | 仅付费 | 固定价 | --- -## 二、整体架构 +## 二、部署架构 -### 2.1 部署架构 +### 2.1 物理拓扑 ``` Internet │ - ┌────▼────┐ - │ Nginx │ :12888 (HTTPS) - └────┬────┘ - │ + ┌─────────▼─────────┐ + │ 宝塔 Nginx :443 │ SSL 终止 + 反向代理 + │ root: /www/dk_ │ + │ project/wwwroot/ │ + │ ai.qihuyun.com │ + └─────────┬─────────┘ + │ :12888 ┌──────────────┼──────────────┐ │ │ │ - ┌────▼────┐ ┌───▼────┐ ┌───▼─────┐ - │ React │ │FastAPI │ │ Casdoor │ - │ Vite │ │uvicorn │ │ :8000 │ - │ (dist/) │ │:18080 │ └─────────┘ - └─────────┘ └───┬────┘ + ┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐ + │ Nginx │ │ uvicorn │ │ 静态资源 │ + │ :8080 │ │ :18080 │ │ dist/ │ + │ proxy_pass │ FastAPI │ │ React SPA│ + └──────────┘ └────┬─────┘ └──────────┘ │ - ┌─────────────┼─────────────┐ - │ │ │ - ┌────▼────┐ ┌───▼────┐ ┌───▼──────┐ - │Postgres │ │ Redis │ │ Executor │ - │PG18+ │ │:6379 │ │ (Code) │ - │pgvector │ └────────┘ └──────────┘ - └─────────┘ + ┌─────────────┼─────────────────┐ + │ │ │ + ┌────▼────┐ ┌───▼────┐ ┌────▼─────┐ + │Postgres │ │ Redis │ │LiteLLM │ + │PG18 │ │ :6379 │ │ :4000 │ + │+pgvector│ └────────┘ │ LLM 网关 │ + └─────────┘ └──────────┘ ``` -### 2.2 容器清单 +### 2.2 容器清单 (Docker Compose) -| 容器 | 镜像 | 用途 | -|------|------|------| -| 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 | 宿主机指标 | +| 容器 | 镜像 | 端口 | 用途 | +|------|------|------|------| +| **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 数据流 +### 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 -``` +| 域名 | 用途 | +|------|------| +| ai.qihuyun.com | 主站 (React SPA + FastAPI API) | +| docs.qihuyun.com | 文档站 | +| bot.qihuyun.com | Bot 回调地址 | --- @@ -86,459 +95,322 @@ | 层级 | 技术 | 版本 | 选型理由 | |------|------|------|---------| -| 后端框架 | 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 | 开源标准、全栈可见 | +| **后端框架** | 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 | 单机部署、一行启动 | --- -## 四、数据模型（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 事件类型 +### 4.1 系统分层 ``` -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":"..."} // 流结束 +┌─────────────────────────────────────────────────┐ +│ 表现层 (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) -### 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 布局 | +| 落地页 | `/` | 平台介绍 + Hero + 能力展示 | +| AI 对话 | `/chat` | SSE 流式对话、代码块渲染、Markdown、媒体预览 | +| 知识库 | `/knowledge` | 文档上传、RAG 检索、向量索引管理 | +| 技能市场 | `/market` | Meilisearch 搜索、技能安装、上架审核 | +| Token 驾驶舱 | `/token` | 实时用量、消耗趋势、预警告警 | +| 会员/定价 | `/pricing` | 套餐对比、微信支付订阅、增值付费 | +| 个人中心 | `/profile` | 用户信息、主题设置、API Key 管理 | +| 通知中心 | `/notifications` | 系统消息、订单通知、告警 | +| Agent 画布 | `/agent` | 可视化编排、DAG 工作流编辑 | +| App 服务 | `/apps` | 第三方应用集成(小说、视频等) | -### 7.3 设计系统 +#### 后台 (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) ``` -CSS 变量（global.css :root）: - --color-accent: #5B5FED - --color-bg-primary: #F8F9FB - --sidebar-width: 240px - --space-xs..4xl: 4px..40px - --radius-md..3xl: 8px..20px +用户消息 → 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 用量 + 审计 +``` -防溢出: html/body/.front-main { overflow-x: hidden } -响应式: @media (max-width: 1200px/768px) 断点 +### 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) -### 8.1 认证 +### 6.1 设计理念 -- JWT Bearer Token 认证（FastAPI HTTPBearer） -- Casdoor OAuth2/OIDC 统一认证（可选） -- Token 前端存内存，401/403 清 token 跳 /login +**温暖科技感 + 极简主义** (Warm Tech Minimalism)。护眼雾白底，靛蓝 `#5B5FED` 为唯一品牌色。 -### 8.2 授权 +### 6.2 技术实现 -- 前台: 用户级（需登录） -- 后台: 管理员级（role=admin） -- API Key: 支持 per-model key 覆盖 provider key +| 维度 | 值 | +|------|-----| +| 主品牌色 | `#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 | -### 8.3 工具调用沙箱 +### 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 ``` -_check_tool_policy() 三层防护: - 1. 白名单: agent 只允许调特定 skill_ids + mcp_ids - 2. 预算: max_calls_per_conversation 上限 - 3. 每轮上限: per_round_cap -代码执行: 独立 executor 容器沙箱 -密钥管理: credential.py 加解密存储 -``` +### 6.4 设计铁律 + +- ❌ 禁硬编码 `bg-blue-*`/`bg-sky-*`/`bg-indigo-600` +- ✅ GenUi 走 primary 语义 token +- ✅ 变体映射必须 `Record` + `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` --- -## 九、运维架构 +## 七、运维与可靠性 -### 9.1 CI/CD +### 7.1 Safe-Align 工作流 ``` -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 +① 备份: docker commit → backup 镜像 + git tag + bundle + PG dump +② 拷贝: 仅 git-tracked 源文件 容器→宿主 git +③ 提交: git add + commit (不 push) +④ 校验: docker restart + 验证 + docker commit → with-deps ``` -### 9.2 健康检查 +**真相源**: 容器 (image := container := git) -``` -/health → 200 {status: "ok"} (liveness) -前端 :8080 → 200 HTML (SPA) -后端 :18080/docs → 200 Swagger UI -容器: docker restart → < 20s 恢复 -``` +### 7.2 监控 -### 9.3 监控栈 +- Grafana 双 Claw 对比看板 `uid: qihuaiflow-dual-claw-876` +- OTel traces + metrics (alloy → Prometheus) +- 日志级别: INFO (生产) / DEBUG (开发) -``` -Prometheus (scrape) ← node-exporter (host) + Alloy (logs) -Grafana (visualize) ← Prometheus datasource -应用日志: Python logging → docker logs / Alloy 采集 -``` +### 7.3 备份策略 + +- 每 6h 自动备份 (cron) +- PG dump (不用 --ssl=0 否则 0 bytes) +- Docker image snapshot: `qihuaiflow:backup-*{TS}` +- nginx logrotate 每日轮转 --- -## 十、市场竞争分析 +## 八、迭代路线 -### 10.1 护城河 +### 8.1 已完成 (2026-08-11) -| 护城河 | 具体实现 | 壁垒强度 | -|--------|---------|---------| -| **多模型协议适配层** | 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 白名单+预算+代码执行容器隔离 | 🟡 中 | +| 编号 | 描述 | 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 | -### 10.2 竞品对比 +### 8.2 下一步候选 -| 维度 | 七虎AI | Dify | Coze | 扣子 | FastGPT | -|------|--------|------|------|------|---------| -| 模型聚合 | ✅ 手动 failover | ✅ | ✅ | ✅ | ✅ | -| Skill 市场 | ✅ 上架-安装-进化 | ❌ | ❌ (Plugin) | ❌ (Plugin) | ❌ | -| MCP 协议 | ✅ 官方 SDK | ✅ | ❌ | ❌ | ❌ | -| Agent DAG | ✅ 图引擎 | ✅ 工作流 | ✅ 工作流 | ✅ 工作流 | ❌ 简单 | -| IM Bot | ✅ 多平台 | ❌ | ❌ | ✅ 飞书 | ❌ | -| PG 全栈 | ✅ PG18 | ⚠️ MySQL | ? | ? | ✅ PG | -| Auth | ✅ Casdoor+JWT | ✅ | ✅ | ✅ | ✅ | +| 优先级 | 项目 | 工作量 | +|--------|------|--------| +| 🟢 P0 | 企业微信官方 Bot API 接入 | 3 天 | +| 🟢 P1 | 后端核心模块单测补全 (165→300+) | 3 天 | +| 🟡 P1 | Alloy traces 配置 bake to image | 1 天 | +| 🟡 P1 | 多租户 PG RLS 隔离 | 5 天 | +| ⚪ P2 | 语音/视频流式响应 | 5 天 | +| ⚪ P2 | Agent 画布可视化编排 | 7 天 | -### 10.3 扩展能力 +### 8.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 调用计费 | +1. **模型 → 智能体**: 从简单的模型调用升级到自主 Agent + 多步推理 +2. **单机 → 集群**: Docker Compose → Kubernetes + Helm +3. **中国市场 → 国际化**: 多语言 + 多区域部署 +4. **技能市场 → 开放生态**: 第三方开发者平台 + 收入分成 +5. **个人微信 → 企业微信**: 合规化 IM Bot 渠道 --- -## 十一、迭代路线图 +## 九、附录 -### 已完成 +### 9.1 服务器信息 -- [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 监控栈 +| 项 | 值 | +|------|-----| +| 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 关键文件路径 -- [ ] Skill 真实执行器（非 LLM 转发模拟） -- [ ] 多 Agent 协作（Supervisor 模式） -- [ ] API/OpenAPI 对外接口 -- [ ] 技能 SDK 发布工具 +| 文件 | 容器路径 | +|------|---------| +| 后端入口 | `/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 调试经验 -- [ ] LiteLLM 集成（统一模型路由+成本追踪） -- [ ] 流式 Token 计费（精确到字符级） -- [ ] LangGraph 工作流引擎 -- [ ] 向量混合检索增强（BM25 + dense + sparse） -- [ ] 前端暗色模式 -- [ ] 多语言（i18n） -- [ ] 移动端适配 - ---- - -> **文档维护规则**: 每次系统重大迭代后，更新本文档对应章节并变更版本号。 -> **上传位置**: Gitea 仓库 `qihuaiflow/docs/ARCHITECTURE.md` +| 问题 | 解决方案 | +|------|---------| +| 容器重启循环 | 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次重试 + 指数退避 |