qyyfw/qihuaiflow
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 完善README.md项目文档

Browse Source 
- 新增完整技术栈和核心组件说明
- 新增Mermaid风格系统架构设计图
- 新增13个后台管理模块详细介绍
- 完善Docker部署手册（前置条件/部署方式/自动化流程/端口/环境变量）
- 新增管理员账号说明和常用Docker命令
- 新增完整项目文件结构说明
- 新增API接口概览
This commit is contained in:
qyyfw committed 2026-07-02 14:49:22 +08:00
1 parent 78ff261b5a
commit bd3b0df4f0
1 file changed
+462 -202
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+462 -202
View File
@@ -2,169 +2,357 @@
## 项目概述
Qihu-AIFlow 是一套**私有化部署、面向个人及小微企业的AI自动化SOP一站式PaaS平台**。用户无需编码即可落地全流程AI自动化业务，平台支持AI对话、知识管理、技能市场、Token计费、会员订阅等完整闭环体验。
Qihu-AIFlow 是一套**私有化部署、面向个人及小微企业的AI自动化SOP一站式PaaS平台**。用户无需编码即可落地全流程AI自动化业务，平台提供AI对话、知识管理、技能市场、Token计费、会员订阅等完整闭环体验。
**版本**: v2.0.1
**构建日期**: 2026-06-02
**构建日期**: 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中安装） |
---
## 系统架构
### 架构设计图
```
┌──────────────────────────────────────────────────┐
│ 前端 (React + TypeScript) │
│ Nginx :8080 → /#/ (HashRouter) │
├──────────────────────────────────────────────────┤
│ 后端 API (Python FastAPI) │
│ Uvicorn :18080 → /app/api/* │
├──────────────────────────────────────────────────┤
│ MySQL 8.0 (:3306) │
│ Redis (:6379) │
├──────────────────────────────────────────────────┤
│ 外部集成: │
│ - 微信ClawBot API (IM频道绑定) │
│ - AI模型供应商 (OpenAI兼容API) │
│ - 邮件SMTP / 短信服务 │
│ - 微信/支付宝支付 │
└──────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ 用户浏览器 │
│ 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兼容) (支付网关)
```
### 技术栈
### 请求流程
| 层级 | 技术 |
|------|------|
| 前端 | React 18 + TypeScript + Vite |
| 后端 | Python 3.11 + FastAPI + SQLAlchemy |
| 数据库 | MySQL 8.0 (SQLAlchemy ORM) |
| 缓存 | Redis |
| 容器化 | Docker + Docker Compose |
| Web服务器 | Nginx |
```
用户请求 → Nginx(:8080) → /app/* → Uvicorn(:18080) → FastAPI路由
↓
JWT认证中间件
↓
SQLAlchemy ORM
↙ ↘
MySQL 8.0 Redis 7
```
### 数据隔离
- 所有用户数据查询强制带 `user_id` 过滤，实现物理级数据隔离
- 前后台权限分离：`role: admin` 可访问 `/admin/*` 路由
- API密钥独立管理，支持颁发/撤销
---
## 功能模块
### 前台功能（8大模块）
### 前台功能（10大模块）
| 模块 | 功能说明 |
|------|----------|
| **AI聊天** | 多模型对话、知识库关联、Agent/技能调用、会话管理 |
| **频道（IM接入）** | 飞书/微信/钉钉/WhatsApp/Telegram/Slack多渠道AI接入，微信通过ClawBot API扫码绑定 |
| **知识库** | 文档上传/解析、知识图谱(LLM实体关系提取)、Canvas可视化 |
| **应用市场** | 应用浏览/安装/卸载、搜索去重、一键安装 |
| **Token驾驶舱** | Token消耗统计、CSV导出、用量图表、上海时区同步 |
| **付费中心** | 会员订阅(多等级)、增值服务、实名认证、微信/支付宝支付 |
| **资产中心** | 文件上传/分类/在线预览(Office/PDF)、AI生成图片管理 |
| **AI进化** | 进化Pipeline管理、知识图谱自动构建、定时任务监控 |
| **个人中心** | 用户资料管理、密码修改 |
| **消息通知** | 系统通知、应用安装通知 |
#### 1. AI聊天
- 多模型对话：支持切换不同AI模型供应商和模型
- 流式输出(SSE)：AI回复实时逐字展示
- 知识库关联：选择知识库让AI基于专属知识回答
- Agent/技能调用：Tool-call机制自动调用关联技能
- 会话管理：创建/归档/置顶/搜索会话
- 对话历史：完整的用户-AI对话记录
### 后台管理（7大模块）
#### 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前缀、流式输出、私聊/群聊策略、白名单
- 平台适配器模式：签名验证 + 消息解析 + 统一格式
- 频道成员管理：邀请/移除成员
| 模块 | 功能说明 |
|------|----------|
| **平台驾驶舱** | 用户/模型/订单/Token统计概览、操作日志、审计日志 |
| **用户管理** | 用户CRUD、角色管理、状态管理(封禁/激活) |
| **大模型库管理** | 模型供应商管理、模型配置、默认模型设置 |
| **网站基础设置** | 站点信息、邮件/SMS配置、AI文案生成 |
| **支付渠道配置** | 微信支付、支付宝商户配置 |
| **增值服务管理** | 服务定价、服务上下架 |
| **会员订阅体系** | 会员等级、订阅计划、自动化规则 |
| **广告位管理** | Banner图片上传、AI图像生成 |
| **应用市场审核** | 应用审核、优惠券管理 |
| **日志与风控** | 操作日志、API调用日志、付费日志审计 |
#### 3. 知识库
- 文档上传管理：PDF/Word/TXT等多格式支持
- 目录组织：多级目录结构管理文档
- AI知识图谱：LLM自动提取实体和关系
- Canvas可视化：节点拖拽、悬停高亮、点击详情
- Pipeline自动构建：知识库变更触发自动更新
### AI自进化系统
#### 4. 应用市场
- 应用浏览：分类展示，详情查看
- 搜索去重：智能搜索，防止重复
- 购买安装：付费后一键安装
- 卸载管理：支持卸载后重新安装（状态重置）
- 后台审核：应用上架审核流程
- **进化Pipeline**: 自动监控知识库变化，触发知识图谱构建
- **知识图谱**: LLM提取实体/关系，Canvas交互式可视化
- **服务自动恢复**: 系统重启后自动恢复运行中的进化Pipeline
#### 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 & Docker Compose
- MySQL 8.0（或使用docker-compose中的MySQL服务）
- Redis（或使用docker-compose中的Redis服务）
- Docker Engine 20.10+
- Docker Compose v2+
- 可用磁盘空间 ≥ 10GB
- 宿主机端口：12888（前端）、18080（后端）、3306（MySQL）、6379（Redis）
### Docker 部署
### 方式一：从 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传入）
# 关键配置: 数据库/Redis连接、APP_ACCESS_URL（外网访问地址）
# 2. 修改环境变量（可选，编辑 .env 或 docker-compose.yml）
# vim .env
# 3. 启动服务
docker-compose up -d
# 3. 构建并启动
docker compose up -d --build
# 4. 验证服务
curl http://localhost:8080/ # 前端
# 4. 验证
curl http://localhost:12888/ # 前端
curl http://localhost:18080/app/api/health # 后端
```
Docker Compose 会自动：
- 启动 MySQL + Redis 容器（如配置）
- 执行数据库迁移脚本（migrations/目录下001-015）
- 创建管理员账号
- 启动 Nginx (8080) + FastAPI (18080)
### Docker Compose 自动执行流程
### 本地开发部署
`docker compose up -d --build` 启动后会自动：
```bash
# 1. 创建Python虚拟环境
cd backend/python
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
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)
# 2. 配置.env文件
cp .env.example .env # 编辑数据库/Redis连接信息
### 端口说明
# 3. 执行数据库迁移
mysql -u root -p aiflow < migrations/001_init.sql
# ... 依次执行002-015
| 端口 | 服务 | 说明 |
|------|------|------|
| 12888 | Nginx (前端) | 用户浏览器访问端口 |
| 18080 | Uvicorn (后端API) | API服务端口 |
| 3306 | MySQL | 数据库端口 |
| 6379 | Redis | 缓存端口 |
# 4. 启动后端
cd /data/share/project
bash run.sh
**注意**: 前端映射到宿主机 12888 端口（而非 8080），用户访问: `http://<IP>:12888`
# 5. 启动前端（开发模式）
cd frontend
npm install
npm run dev
```
### 环境变量配置
---
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 |
`.env` 文件配置项：
**重要**: 生产环境请修改 `SECRET_KEY`、`MYSQL_PASSWORD`、`REDIS_PASSWORD`。
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MYSQL_HOST` | MySQL地址 | localhost |
| `MYSQL_PORT` | MySQL端口 | 3306 |
| `MYSQL_USER` | MySQL用户名 | root |
| `MYSQL_PASSWORD` | MySQL密码 | pwd2026 |
| `MYSQL_DATABASE` | 数据库名 | aiflow |
| `REDIS_HOST` | Redis地址 | localhost |
| `REDIS_PORT` | Redis端口 | 6379 |
| `REDIS_PASSWORD` | Redis密码 | pwd2026 |
| `SECRET_KEY` | JWT签名密钥 | (随机字符串) |
| `APP_ACCESS_URL` | 前端外网访问地址 | https://bot.qihuyun.com |
| `DEBUG` | 调试模式 | false |
| `KNOWLEDGE_STORAGE_DIR` | 知识库文件存储路径 | /data/share/project/data/knowledge |
---
## 管理员账号
### 管理员账号
部署后默认管理员账号：
@@ -172,73 +360,42 @@ npm run dev
|--------|------|------|
| admin | admin123 | 超级管理员 |
> 首次登录后建议立即修改密码。可在「个人中心」页面进行修改。
> 首次登录后请立即修改密码：进入「个人中心」页面进行修改。
> run.sh 会智能检测密码哈希有效性——如果用户已修改密码（有效bcrypt哈希），则保持不变。
---
### 常用命令
## 主要功能使用说明
```bash
# 查看所有容器状态
docker compose ps
### AI聊天
1. 登录后进入「AI聊天」页面
2. 选择模型（左侧模型选择器）
3. 可选关联知识库、Agent或技能
4. 输入消息开始对话，支持流式输出
# 查看应用日志
docker compose logs -f aiflow
### 频道（IM接入）
1. 进入「频道」页面，点击「接入新平台」
2. 选择目标平台（飞书/微信/钉钉等）
3. 填写频道信息和平台凭证
4. **微信**: 填写AppID/AppSecret后点击「生成绑定二维码」，用微信扫码授权
5. **其他平台**: 按指引获取官方凭证后填写
6. 授权成功后，AI机器人即可在该IM平台响应消息
# 查看MySQL日志
docker compose logs -f mysql
### 知识库
1. 创建知识库，上传文档（支持PDF/Word/TXT等）
2. 系统自动解析文档内容
3. 在AI聊天中选择知识库，AI将基于知识库内容回答
4. 知识图谱功能可自动提取实体和关系，以Canvas可视化展示
# 重启应用
docker compose restart aiflow
### 应用市场
1. 浏览可用的AI应用
2. 查看应用详情
3. 付费购买后一键安装
4. 已安装应用可卸载（支持重新安装）
# 停止所有服务
docker compose down
### Token驾驶舱
1. 查看Token消耗概览和趋势图表
2. 按模型/日期维度分析用量
3. 支持CSV格式导出消耗明细
4. 一键跳转充值页面
# 停止并清除数据（危险！）
docker compose down -v
### 付费中心
1. 选择会员等级订阅
2. 购买增值服务
3. 支持微信支付/支付宝
4. 需先完成实名认证
# 重新构建并启动
docker compose up -d --build
---
# 进入应用容器
docker exec -it qihu-aiflow bash
## 数据库迁移
# 进入MySQL
docker exec -it qihu-aiflow-mysql mysql -u root -ppwd2026 aiflow
迁移脚本位于 `migrations/` 目录，按编号顺序执行：
| 编号 | 说明 |
|------|------|
| 001 | 初始化表结构 |
| 002 | 初始数据（管理员账号、种子数据） |
| 003 | 增值服务表 |
| 004 | OAuth状态字段 |
| 005 | 频道扩展字段 |
| 006 | API调用统计表 |
| 007 | 进化系统基础表 |
| 008 | 进化系统v2 |
| 009 | 支付实名认证字段 |
| 010 | 默认模型字段 |
| 011 | 知识库存储与资产表 |
| 012 | 生产环境列同步 |
| 013 | 知识图谱表 |
| 014 | 测试数据清理 |
| 015 | 生产修复（content列+AppPurchase状态） |
# 进入Redis
docker exec -it qihu-aiflow-redis redis-cli -a pwd2026
```
---
@@ -246,41 +403,144 @@ npm run dev
```
/
├── frontend/ # 前端项目
│ ├── dist/ # 构建产物
│ ├── src/ # TypeScript源码
│ │ ├── api/ # API客户端
│ │ ├── components/ # 通用组件
│ │ ├── pages/ # 页面组件
│ │ └── types/ # 类型定义
│ ├── package.json
│ └── vite.config.ts
├── backend/python/ # 后端项目
│ ├── app/
│ │ ├── api/ # API路由
│ │ │ └── admin/ # 后台管理API
│ │ ├── models.py # 数据模型
│ │ ├── services/ # 业务服务
│ │ ├── middleware/ # 中间件
│ │ └── platform_adapters/ # IM平台适配器
│ ├── main.py # 应用入口
│ └── requirements.txt # Python依赖
├── migrations/ # 数据库迁移脚本
├── docs/ # 项目文档（PRD等）
├── Dockerfile # Docker镜像构建
├── docker-compose.yml # Docker编排配置
├── nginx.conf # Nginx配置
├── run.sh # 启动脚本
├── .env # 环境变量配置
└── VERSION # 版本信息
├── 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`。主要里程碑：
详见 `VERSION` 和 `CHANGELOG.md`。
- **v2.0.1** (2026-06-02): 频道微信ClawBot API标准重构、6项生产缺陷修复
- **v2.0.0**: AI进化系统、知识图谱、多平台IM接入、支付体系
- **v1.x**: 基础AI聊天、知识库、用户系统
### v2.0.1 (2026-06-02)
- 微信ClawBot官方API标准重构（频道扫码绑定）
- 6项生产缺陷修复（二维码、知识库、tool-call、应用安装、时区、邮件）
- 完整项目文档（README.md）
- Gitea仓库发布