From bd3b0df4f0033c819c79084bb12e3e3ab9592c9c Mon Sep 17 00:00:00 2001 From: qyyfw Date: Thu, 2 Jul 2026 14:49:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84README.md=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增完整技术栈和核心组件说明 - 新增Mermaid风格系统架构设计图 - 新增13个后台管理模块详细介绍 - 完善Docker部署手册（前置条件/部署方式/自动化流程/端口/环境变量） - 新增管理员账号说明和常用Docker命令 - 新增完整项目文件结构说明 - 新增API接口概览 --- README.md | 664 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 462 insertions(+), 202 deletions(-) diff --git a/README.md b/README.md index 4cfdc2e..0894b9a 100644 --- a/README.md +++ b/README.md @@ -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://: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://: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仓库发布