Files
qihuaiflow/README.md
T
qyyfw bd3b0df4f0 docs: 完善README.md项目文档
- 新增完整技术栈和核心组件说明
- 新增Mermaid风格系统架构设计图
- 新增13个后台管理模块详细介绍
- 完善Docker部署手册(前置条件/部署方式/自动化流程/端口/环境变量)
- 新增管理员账号说明和常用Docker命令
- 新增完整项目文件结构说明
- 新增API接口概览
2026-07-02 14:49:22 +08:00

547 lines
23 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Qihu-AIFlow 智能自动化PaaS平台
## 项目概述
Qihu-AIFlow 是一套**私有化部署、面向个人及小微企业的AI自动化SOP一站式PaaS平台**。用户无需编码即可落地全流程AI自动化业务,平台提供AI对话、知识管理、技能市场、Token计费、会员订阅等完整闭环体验。
**版本**: v2.0.1
**构建日期**: 2026-06-02
**仓库地址**: http://git.qihuyun.com/qyyfw/qihuaiflow
---
## 技术环境
### 技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| 前端框架 | 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
# 3. 等待服务就绪(首次构建约3-5分钟)
# 查看日志确认启动完成
docker compose logs -f aiflow
# 4. 访问系统
# 前端: http://<宿主机IP>:12888
# 默认账号: admin / admin123
```
### 方式二:从程序包部署
```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 | 缓存端口 |
**注意**: 前端映射到宿主机 12888 端口(而非 8080),用户访问: `http://<IP>:12888`
### 环境变量配置
Docker Compose 环境变量在 `docker-compose.yml` 的 `environment` 段配置:
| 变量 | 说明 | 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 |
**重要**: 生产环境请修改 `SECRET_KEY`、`MYSQL_PASSWORD`、`REDIS_PASSWORD`。
### 管理员账号
部署后默认管理员账号:
| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | admin123 | 超级管理员 |
> 首次登录后请立即修改密码:进入「个人中心」页面进行修改。
> run.sh 会智能检测密码哈希有效性——如果用户已修改密码(有效bcrypt哈希),则保持不变。
### 常用命令
```bash
# 查看所有容器状态
docker compose ps
# 查看应用日志
docker compose logs -f aiflow
# 查看MySQL日志
docker compose logs -f mysql
# 重启应用
docker compose restart aiflow
# 停止所有服务
docker compose down
# 停止并清除数据(危险!)
docker compose down -v
# 重新构建并启动
docker compose up -d --build
# 进入应用容器
docker exec -it qihu-aiflow bash
# 进入MySQL
docker exec -it qihu-aiflow-mysql mysql -u root -ppwd2026 aiflow
# 进入Redis
docker exec -it qihu-aiflow-redis redis-cli -a pwd2026
```
---
## 项目文件结构
```
/
├── 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://<host>: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状态重置) |
---
## 更新日志
详见 `VERSION` 和 `CHANGELOG.md`。
### v2.0.1 (2026-06-02)
- 微信ClawBot官方API标准重构(频道扫码绑定)
- 6项生产缺陷修复(二维码、知识库、tool-call、应用安装、时区、邮件)
- 完整项目文档(README.md)
- Gitea仓库发布