层级	技术	说明
前端框架	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 仓库部署

# 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

方式二：从程序包部署

# 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 启动后会自动：

拉取基础镜像: python:3.11-slim, mysql:8.0, redis:7-alpine
构建AIFlow镜像:
- 安装系统依赖 (nginx, mysql-client, redis-tools, build-essential)
- 安装 Python 依赖 (requirements.txt, 使用清华镜像源)
- 安装 Node.js + npm，构建前端 npm install && npm run build
- 配置 Nginx 反向代理
启动MySQL: 等待健康检查通过 (mysqladmin ping)
启动Redis: 密码认证 (requirepass pwd2026)
初始化数据库:
- 创建数据库 aiflow (utf8mb4)
- 按序执行 migrations/ 下 15 个 SQL 迁移脚本
- 智能检测 admin 密码哈希有效性，仅在无效时重置
启动应用: 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哈希），则保持不变。

常用命令

# 查看所有容器状态
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仓库发布

README.md Unescape Escape

Qihu-AIFlow 智能自动化PaaS平台

项目概述

技术环境

技术栈