diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index f3be2cd..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,178 +0,0 @@ -# 保险智能客服系统 - -## 项目概述 - -基于 BaoDan 源码的保险行业智能客服系统。**直接在 BaoDan 源码上开发**，自研代码放在 `api/insurance/` 目录下，与 BaoDan 代码物理隔离，只改 BaoDan 的 `main.py` 注册路由。 - -## 架构 - -``` -用户浏览器 / 企微 H5 - │ - ▼ -┌─ BaoDan 服务（你的代码 + BaoDan 代码，同一进程）────────┐ -│ BaoDan WebApp（对话界面） │ -│ BaoDan 管理后台（知识库/Prompt/模型/日志） │ -│ 你的 Extensions： │ -│ · api/insurance/wecom/ 企微机器人 + OAuth │ -│ · api/insurance/recommend/ 产品推荐 │ -│ · api/insurance/permissions/角色权限 │ -│ └── api/insurance/stats/ 数据统计 │ -└────────────────────────────────────────────────────────┘ - │ - └── 你的前端（Vue 3，独立项目） -``` - -## 核心原则 - -1. **在 BaoDan 源码上开发**，自研代码放 `api/insurance/`，与 BaoDan 代码隔离 -2. **只改 BaoDan 的 `main.py`**（注册路由）和 `web/.env.local`（开启 iframe），其余 BaoDan 文件不动 -3. **复用 BaoDan 基础设施**：认证、数据库、Redis、日志全部用 BaoDan 现有的，不重复造轮子 -4. **BaoDan 升级安全**：你的代码在独立目录，升级时只合并 `main.py` 那几行改动 -5. **前端独立**：Vue 3 项目，对话页面 iframe 嵌入 BaoDan WebApp - -## 目录结构 - -``` -baodan-main/ -├── api/ -│ ├── core/ # BaoDan 核心（不动） -│ ├── controllers/ # BaoDan API 路由（不动） -│ ├── models/ # BaoDan 数据模型（不动） -│ ├── services/ # BaoDan 业务逻辑（不动） -│ ├── extensions/ # BaoDan 扩展（不动） -│ │ -│ ├── insurance/ # ★ 你的代码（新建目录） -│ │ ├── __init__.py -│ │ ├── wecom/ # 企微机器人 + OAuth -│ │ │ ├── wecom_bot.py # 消息回调处理 -│ │ │ ├── wecom_oauth.py # OAuth 登录 -│ │ │ └── routes.py # Blueprint 路由 -│ │ ├── recommend/ # 产品推荐 -│ │ │ ├── recommend_api.py # 推荐接口 -│ │ │ └── workflow_helper.py# Workflow 调用封装 -│ │ ├── permissions/ # 角色权限 -│ │ │ ├── models.py # 角色/权限模型 -│ │ │ ├── middleware.py # 权限校验 -│ │ │ └── routes.py # 角色管理接口 -│ │ ├── stats/ # 数据统计 -│ │ │ └── stats_api.py # 统计接口 -│ │ └── db/ # 自研数据表 -│ │ ├── wecom_user.py # 企微用户映射 -│ │ └── recommend_record.py# 推荐记录 -│ │ -│ └── main.py # ★ BaoDan 入口（只改这里：注册 insurance 路由） -│ -├── web/ -│ └── .env.local # ★ BaoDan 前端配置（只改这里：开启 iframe） -│ -├── docker/ # Docker 部署配置 -└── dev/ # 开发脚本 - -frontend/ # 你的前端（独立 Vue 3 项目） -├── src/ -│ ├── pages/ # 登录/对话/推荐/管理页面 -│ ├── components/ # 通用组件 -│ ├── composables/ # 组合函数 -│ └── utils/ # 工具函数 -├── package.json -└── vite.config.ts - -deploy/ -├── sql/init.sql # 自研表建表脚本 -└── nginx.conf # Nginx 反向代理 - -docs/ # 所有项目文档 -├── README.md # 文档索引（入口） -├── 保险智能客服系统_需求文档.md -├── 保险智能客服系统_API接口文档.md -├── 保险智能客服系统_编码规范.md -├── 保险智能客服系统_测试用例.md -├── 保险智能客服系统_文档规范.md -├── 前端开发计划.md -├── 开发计划.md -├── 开发任务清单.md -├── API_curl示例.md -└── 部署指南.md -``` - -## 修改 BaoDan 源码清单 - -| 文件 | 改动 | 改动量 | -|------|------|:---:| -| `api/main.py` | 注册 insurance Blueprint | ~5 行 | -| `web/.env.local` | 开启 iframe 嵌入 | 1 行 | -| **合计** | **只改 2 个 BaoDan 文件** | **~6 行** | - -## 开发规范 - -详见 `docs/保险智能客服系统_编码规范.md`，关键点： - -- 自研代码全部放在 `api/insurance/` 下，不往 BaoDan 其他目录写代码 -- 后端文件名/变量名：snake_case -- 前端组件名/变量名：camelCase / PascalCase -- 复用 BaoDan 的数据库连接、Redis、日志系统 -- 统一响应格式：`{"code": 0, "message": "success", "data": {...}}` -- 注释用中文，commit message 用英文 - -## 运行方式 - -```bash -# 1. 启动 BaoDan（源码模式） -cd baodan-main -./dev/setup # 安装依赖 -./dev/start-api # 后端（含你的 insurance 模块） -./dev/start-worker # Celery Worker -./dev/start-web # 前端 - -# 2. 启动你的 Vue 前端 -cd frontend -pnpm install && pnpm dev - -# 3. 验证 -curl http://localhost:5001/api/health -curl http://localhost:5001/api/wecom/callback # 企微回调 -``` - -## 开发文档 - -所有文档已整理到 `docs/` 目录，完整索引见 [docs/README.md](docs/README.md)： - -- `docs/保险智能客服系统_需求文档.md` — 完整需求 -- `docs/保险智能客服系统_API接口文档.md` — 45 个 API 接口 -- `docs/保险智能客服系统_编码规范.md` — 编码标准 -- `docs/保险智能客服系统_测试用例.md` — 测试用例 -- `docs/前端开发计划.md` — 前端开发详细计划 -- `docs/开发计划.md` — 8 阶段开发计划 -- `docs/开发任务清单.md` — 185 项可勾选任务 -- `docs/API_curl示例.md` — 接口调试 curl 示例 -- `docs/部署指南.md` — BaoDan 源码集成指南 -- `docs/保险智能客服系统_文档规范.md` — 文档编写标准 - -## BaoDan 对接要点 - -- 复用 BaoDan 的数据库连接（SQLAlchemy），自研表直接用 BaoDan 的 DB -- 复用 BaoDan 的认证系统，在上面叠加你的角色权限 -- 调 BaoDan 的 RAG 引擎：**直接 import Python 函数**，不走 HTTP -- 调 BaoDan 的 Workflow：通过 Python API 调用，不走 HTTP -- 按险种筛选：创建多个 BaoDan 应用，你的路由代码按用户选择分发 - -## BaoDan 升级流程 - -```bash -cd baodan-main -git stash # 暂存你的 insurance/ 目录改动 -git pull origin main # 拉取 BaoDan 新版本 -git stash pop # 恢复你的改动 -# 如果 main.py 有冲突 → 手动合并（只合并注册路由的 5 行） -# 如果 .env.local 有冲突 → 重新加那一行 -# insurance/ 目录永远不会冲突（新增的目录） -``` - -## 注意事项 - -- `.env` 文件不要提交到 Git -- BaoDan 的 `NEXT_PUBLIC_ALLOW_EMBED` 必须开启才能 iframe 嵌入 -- 企微回调必须在 5 秒内返回 `success`，异步处理消息 -- BaoDan WebApp 和你的前端必须**同源部署** -- 自研表的数据库迁移用 Alembic，放在 `api/insurance/db/` 下 diff --git a/BAODANAGENT_DEPLOY.md b/BAODANAGENT_DEPLOY.md deleted file mode 100644 index 3f99b89..0000000 --- a/BAODANAGENT_DEPLOY.md +++ /dev/null @@ -1,248 +0,0 @@ -# 🚀 保单智能客服系统 — 部署指南 - -## 系统架构 - -``` -┌─────────────────────────────────────────┐ -│ 保单智能客服系统 │ -├─────────────────────────────────────────┤ -│ 前端 (Vue 3) → Nginx (8080) │ -│ 后端 (Flask) → Gunicorn (5001) │ -│ 数据库 (PostgreSQL) → PostgreSQL (5433)│ -│ 缓存 (Redis) → Redis (6380) │ -└─────────────────────────────────────────┘ -``` - -## 快速部署 - -### Linux/Mac - -```bash -chmod +x deploy-baodanagent.sh -./deploy-baodanagent.sh -``` - -### Windows - -```cmd -deploy-baodanagent.bat -``` - -### 手动部署 - -```bash -# 1. 构建镜像 -docker compose -f docker-compose.baodanagent.yml build - -# 2. 启动服务 -docker compose -f docker-compose.baodanagent.yml up -d - -# 3. 查看日志 -docker compose -f docker-compose.baodanagent.yml logs -f -``` - -## 镜像大小 - -| 镜像 | 大小 | 说明 | -|------|------|------| -| baodanagent-api | ~200MB | 后端 API | -| baodanagent-web | ~50MB | 前端 Nginx | -| pgvector/pgvector:pg15 | ~300MB | 数据库 | -| redis:7-alpine | ~30MB | 缓存 | -| **总计** | **~580MB** | 比 Dify 版节省 17GB | - -## 访问地址 - -| 服务 | 地址 | 说明 | -|------|------|------| -| 前端应用 | http://localhost:8080 | Vue 3 前端 | -| 后端 API | http://localhost:5001 | Flask 后端 | -| 数据库 | localhost:5433 | PostgreSQL | -| 缓存 | localhost:6380 | Redis | - -## 数据库信息 - -- **主机**: localhost:5433 -- **数据库**: baodan -- **用户名**: postgres -- **密码**: taiyi1224 - -## API 接口 - -### 健康检查 - -```bash -curl http://localhost:5001/health -# 返回: {"status": "ok", "service": "baodanagent-api"} -``` - -### 认证接口 - -```bash -# 登录 -curl -X POST http://localhost:5001/insurance/auth/login \ - -H "Content-Type: application/json" \ - -d '{"username": "admin", "password": "admin123"}' - -# 注册 -curl -X POST http://localhost:5001/insurance/auth/register \ - -H "Content-Type: application/json" \ - -d '{"username": "test", "password": "test123", "name": "测试用户"}' -``` - -### 对话接口 - -```bash -# 发送消息 -curl -X POST http://localhost:5001/insurance/chat/send \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer " \ - -d '{"message": "我想买保险"}' -``` - -## 常用命令 - -```bash -# 查看服务状态 -docker compose -f docker-compose.baodanagent.yml ps - -# 查看日志 -docker compose -f docker-compose.baodanagent.yml logs -f - -# 查看特定服务日志 -docker compose -f docker-compose.baodanagent.yml logs -f baodanagent-api - -# 停止服务 -docker compose -f docker-compose.baodanagent.yml down - -# 重启服务 -docker compose -f docker-compose.baodanagent.yml restart - -# 停止并删除数据 -docker compose -f docker-compose.baodanagent.yml down -v - -# 进入容器 -docker compose -f docker-compose.baodanagent.yml exec baodanagent-api bash -``` - -## 配置说明 - -### 环境变量 - -在 `.env` 文件中配置： - -```bash -# JWT 密钥 -JWT_SECRET=your-jwt-secret - -# Dify 对接（可选） -DIFY_BASE_URL=http://dify-api:5001 -DIFY_CHAT_APP_API_KEY=app-xxx -DIFY_WORKFLOW_APP_API_KEY=app-xxx - -# 企微配置（可选） -WECOM_CORP_ID=your_corp_id -WECOM_SECRET=your_secret -WECOM_TOKEN=your_token -WECOM_AES_KEY=your_aes_key -``` - -### 数据库初始化 - -数据库会在首次启动时自动初始化，执行 `deploy/sql/init.sql` 中的建表语句。 - -## 故障排查 - -### 端口冲突 - -```bash -# 检查端口占用 -netstat -tulpn | grep -E ':(5001|8080|5433|6380)' - -# 修改端口映射 -# 编辑 docker-compose.baodanagent.yml -ports: - - "5002:5001" # 将 5001 改为 5002 -``` - -### 服务启动失败 - -```bash -# 查看详细日志 -docker compose -f docker-compose.baodanagent.yml logs baodanagent-api - -# 重启服务 -docker compose -f docker-compose.baodanagent.yml restart -``` - -### 数据库连接失败 - -```bash -# 检查数据库状态 -docker compose -f docker-compose.baodanagent.yml exec db pg_isready -U postgres - -# 查看数据库日志 -docker compose -f docker-compose.baodanagent.yml logs db -``` - -## 文件清单 - -``` -baodanagent/ -├── docker-compose.baodanagent.yml # Docker Compose 配置 -├── Dockerfile.backend # 后端 Dockerfile -├── Dockerfile.frontend # 前端 Dockerfile -├── nginx.conf # Nginx 配置 -├── deploy-baodanagent.sh # Linux/Mac 部署脚本 -├── deploy-baodanagent.bat # Windows 部署脚本 -├── BAODANAGENT_DEPLOY.md # 本文档 -├── api/insurance/ # 后端代码 -│ ├── app.py # Flask 应用入口 -│ ├── requirements.txt # Python 依赖 -│ ├── routes.py # 路由注册 -│ ├── db/ # 数据库模块 -│ ├── models/ # 数据模型 -│ ├── auth/ # 认证模块 -│ ├── chat/ # 对话模块 -│ ├── recommend/ # 推荐模块 -│ ├── kb/ # 知识库模块 -│ ├── admin/ # 管理模块 -│ ├── stats/ # 统计模块 -│ └── wecom/ # 企微模块 -├── frontend/ # 前端代码 -│ ├── src/ # 源码 -│ └── dist/ # 构建产物 -└── deploy/sql/ # SQL 初始化脚本 -``` - -## 环境要求 - -- Docker 20.10+ -- Docker Compose 2.0+ -- 磁盘空间：1GB+ -- 内存：2GB+ - -## 与 Dify 版本的区别 - -| 特性 | 保单容器版 | Dify 版 | -|------|-----------|---------| -| 镜像大小 | ~580MB | ~17.5GB | -| 部署时间 | 2 分钟 | 15 分钟 | -| 功能范围 | 自研功能 | 全部功能 | -| 知识库 | 需对接 Dify | 内置 | -| 模型调用 | 需对接 Dify | 内置 | -| 适用场景 | 独立部署 | 完整系统 | - -## 下一步 - -1. **访问前端**：http://localhost:8080 -2. **测试 API**：http://localhost:5001/health -3. **配置 Dify 对接**：编辑 `.env` 文件 -4. **配置企微**：编辑 `.env` 文件 -5. **上传知识库**：通过 API 或对接 Dify - ---- - -**部署时间**: ~2 分钟 -**镜像大小**: ~580MB -**推荐场景**: 独立部署、资源受限环境、微服务架构 diff --git a/CLAUDE.md b/CLAUDE.md index f3be2cd..18a6e8e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -89,11 +89,19 @@ docs/ # 所有项目文档 ├── 保险智能客服系统_编码规范.md ├── 保险智能客服系统_测试用例.md ├── 保险智能客服系统_文档规范.md -├── 前端开发计划.md -├── 开发计划.md +├── 保险智能客服系统_客户验收单.md +├── 后续开发计划.md ├── 开发任务清单.md +├── 后端开发文档.md +├── 前端开发计划.md +├── 前端移动端适配指南.md +├── 企业微信接入指南.md +├── Dify_Workflow配置指南.md ├── API_curl示例.md -└── 部署指南.md +├── 快速启动指南.md +├── 部署指南.md +├── 部署文档_完整版.md +└── 宝塔面板部署指南.md ``` ## 修改 BaoDan 源码清单 @@ -143,10 +151,10 @@ curl http://localhost:5001/api/wecom/callback # 企微回调 - `docs/保险智能客服系统_编码规范.md` — 编码标准 - `docs/保险智能客服系统_测试用例.md` — 测试用例 - `docs/前端开发计划.md` — 前端开发详细计划 -- `docs/开发计划.md` — 8 阶段开发计划 -- `docs/开发任务清单.md` — 185 项可勾选任务 +- `docs/后续开发计划.md` — 项目状态 + 未完成功能 +- `docs/开发任务清单.md` — 412 项可勾选任务 - `docs/API_curl示例.md` — 接口调试 curl 示例 -- `docs/部署指南.md` — BaoDan 源码集成指南 +- `docs/部署文档_完整版.md` — 完整部署文档 - `docs/保险智能客服系统_文档规范.md` — 文档编写标准 ## BaoDan 对接要点 diff --git a/CLOUD_DEPLOY.md b/CLOUD_DEPLOY.md deleted file mode 100644 index 5e53339..0000000 --- a/CLOUD_DEPLOY.md +++ /dev/null @@ -1,201 +0,0 @@ -# 云服务器部署指南（精简版） - -## 问题：代码太大怎么办？ - -**解决方案**：Docker 镜像部署 - -- 本地构建好 Docker 镜像（包含所有代码） -- 推送到 Docker Hub（免费） -- 服务器只需要拉取镜像运行，**无需上传源码** - -## 部署流程 - -### 第一步：本地构建并推送镜像 - -```bash -# 1. 登录 Docker Hub（没有账号先注册：https://hub.docker.com） -docker login - -# 2. 设置你的 Docker Hub 用户名 -export DOCKER_USERNAME=yourusername - -# 3. 构建并推送镜像 -./build-and-push.sh -``` - -**镜像大小参考**： -- API 镜像：约 500MB -- Web 镜像：约 200MB -- 前端镜像：约 50MB - -### 第二步：服务器部署 - -```bash -# 1. 登录服务器 -ssh user@your-server-ip - -# 2. 创建目录 -mkdir -p /opt/baodanagent && cd /opt/baodanagent - -# 3. 下载部署脚本（或从本地上传） -# 方式一：从 Git 下载 -curl -sSL https://raw.githubusercontent.com/yourusername/baodanagent/main/server-deploy.sh -o server-deploy.sh - -# 方式二：从本地上传（只需要这一个文件） -scp server-deploy.sh user@your-server-ip:/opt/baodanagent/ - -# 4. 设置执行权限 -chmod +x server-deploy.sh - -# 5. 运行部署脚本 -DOCKER_USERNAME=yourusername ./server-deploy.sh -``` - -### 第三步：配置环境变量（可选） - -```bash -# 编辑 .env 文件 -nano .env - -# 修改以下配置： -DOCKER_USERNAME=yourusername # 必须修改 -POSTGRES_PASSWORD=your_password # 建议修改 -SECRET_KEY=your_secret_key # 建议修改 -ADMIN_PASSWORD=your_password # 建议修改 -``` - -### 第四步：访问系统 - -| 服务 | 地址 | -|------|------| -| 管理后台 | http://your-server-ip:3000 | -| API 服务 | http://your-server-ip:5001 | -| 默认账号 | taiyi@baodan.com / taiyi1224 | - -## 文件清单 - -### 本地需要的文件（构建镜像时） - -``` -baodanagent/ -├── Dockerfile.dify-custom # API 镜像构建文件 -├── Dockerfile.web-custom # Web 镜像构建文件 -├── Dockerfile.frontend # 前端镜像构建文件 -├── build-and-push.sh # 构建并推送脚本 -├── api/insurance/ # 自研代码 -├── scripts/ # 启动脚本 -├── deploy/ # 部署配置 -│ ├── sql/init.sql -│ └── logo/ -└── frontend/ # 前端代码 -``` - -### 服务器需要的文件（部署时） - -``` -/opt/baodanagent/ -├── server-deploy.sh # 部署脚本（唯一必需文件） -├── docker-compose.yml # 自动生成 -├── .env # 自动生成 -└── deploy/sql/init.sql # 自动生成 -``` - -## 常用命令 - -```bash -# 查看服务状态 -docker compose ps - -# 查看日志 -docker compose logs -f baodan-api - -# 重启服务 -docker compose restart - -# 停止服务 -docker compose down - -# 更新镜像并重启 -docker compose pull && docker compose up -d - -# 备份数据库 -docker compose exec db pg_dump -U postgres baodan > backup.sql - -# 恢复数据库 -docker compose exec -T db psql -U postgres baodan < backup.sql -``` - -## 更新部署 - -```bash -# 本地重新构建并推送镜像 -./build-and-push.sh - -# 服务器拉取新镜像并重启 -docker compose pull -docker compose up -d -``` - -## 域名和 HTTPS 配置 - -如果需要配置域名和 HTTPS： - -```bash -# 安装 Nginx 和 Certbot -apt install nginx certbot python3-certbot-nginx -y - -# 配置 Nginx 反向代理 -cat > /etc/nginx/sites-available/baodanagent << 'EOF' -server { - listen 80; - server_name your-domain.com; - - location / { - proxy_pass http://127.0.0.1:3000; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } - - location /api/ { - proxy_pass http://127.0.0.1:5001/; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } -} -EOF - -# 启用配置 -ln -s /etc/nginx/sites-available/baodanagent /etc/nginx/sites-enabled/ -nginx -t && systemctl reload nginx - -# 申请 SSL 证书 -certbot --nginx -d your-domain.com -``` - -## 故障排查 - -```bash -# 查看容器日志 -docker compose logs baodan-api - -# 进入容器调试 -docker compose exec baodan-api bash - -# 检查数据库连接 -docker compose exec db psql -U postgres -d baodan - -# 检查 Redis 连接 -docker compose exec redis redis-cli ping - -# 重启所有服务 -docker compose down && docker compose up -d -``` - -## 总结 - -| 对比项 | 传统部署 | Docker 镜像部署 | -|--------|---------|----------------| -| 上传内容 | 整个项目代码（数GB） | 只需一个脚本（几KB） | -| 部署复杂度 | 需要安装各种依赖 | 一键部署 | -| 环境一致性 | 可能有差异 | 完全一致 | -| 更新方式 | 重新上传代码 | 拉取新镜像 | diff --git a/CONFIG_COMPLETE.md b/CONFIG_COMPLETE.md deleted file mode 100644 index 3362454..0000000 --- a/CONFIG_COMPLETE.md +++ /dev/null @@ -1,217 +0,0 @@ -# ✅ 配置完成总结 - -## 已完成的配置 - -### 1. 环境变量配置 ✅ - -- [x] 创建 `.env` 文件 -- [x] 生成安全的 JWT_SECRET -- [x] 配置数据库连接 -- [x] 配置 Redis 连接 -- [x] 配置 Dify/BaoDan API Key -- [x] 配置前端参数 - -### 2. 部署脚本 ✅ - -- [x] 创建 `deploy.sh` (Linux/Mac) -- [x] 创建 `deploy.bat` (Windows) -- [x] 创建 `check-env.sh` (环境检查) -- [x] 添加执行权限 - -### 3. 文档 ✅ - -- [x] 创建 `DEPLOY_README.md` (部署指南) -- [x] 创建 `CONFIG_COMPLETE.md` (本文件) - -### 4. 项目结构 ✅ - -- [x] `api/insurance/` - 自研后端代码 -- [x] `frontend/dist/` - 前端构建产物 -- [x] `deploy/sql/` - 数据库初始化脚本 -- [x] `scripts/` - 部署辅助脚本 -- [x] `Dockerfile.dify-custom` - API 镜像 -- [x] `Dockerfile.web-custom` - Web 镜像 -- [x] `docker-compose.dify.yml` - Docker Compose 配置 - -## 配置文件说明 - -### .env 文件 - -```bash -# 数据库配置 -DATABASE_URL=postgresql://postgres:taiyi1224@db:5432/baodan - -# Redis 配置 -REDIS_URL=redis://redis:6379/0 - -# JWT 认证（已生成安全密钥） -JWT_SECRET=c9ffb3f03f617d3d6eabd41da8305510badeb5762a4018c8b0d37e4131308fa5 - -# Dify/BaoDan API Key -DIFY_CHAT_APP_API_KEY=app-Q7f84VH2lopTya4CCvBGNrgk -DIFY_WORKFLOW_APP_API_KEY=app-GeFitFFzFNqxTfqmbTvQsyNA -``` - -### docker-compose.dify.yml 服务 - -| 服务 | 端口 | 说明 | -|------|------|------| -| baodan-api | 5001 | API 服务 + Insurance 模块 | -| baodan-web | 3000 | Web 管理后台 | -| baodan-worker | - | Celery 异步任务 | -| db | 5433 | PostgreSQL 数据库 | -| redis | 6380 | Redis 缓存 | -| plugin_daemon | 5002 | 插件守护进程 | -| sandbox | 8194 | 代码执行沙箱 | - -## 快速启动 - -### Windows - -```cmd -deploy.bat -``` - -### Linux/Mac - -```bash -./deploy.sh -``` - -### 手动启动 - -```bash -# 1. 检查环境 -./check-env.sh - -# 2. 构建镜像 -docker build -t baodanagent-dify-api:latest -f Dockerfile.dify-custom . -docker build -t baodanagent-dify-web:latest -f Dockerfile.web-custom . - -# 3. 启动服务 -docker compose -f docker-compose.dify.yml up -d - -# 4. 查看日志 -docker compose -f docker-compose.dify.yml logs -f -``` - -## 访问地址 - -| 服务 | 地址 | 说明 | -|------|------|------| -| 前端应用 | http://localhost:8080 | Vue 3 前端 | -| 管理后台 | http://localhost:3000 | BaoDan 后台 | -| API 服务 | http://localhost:5001 | 后端 API | - -## 默认管理员账号 - -- **邮箱**: taiyi@baodan.com -- **密码**: taiyi1224 - -## 待办事项（可选） - -### 1. 企微配置（如需对接企业微信） - -编辑 `.env` 文件，填入企微配置： - -```bash -WECOM_CORP_ID=your_corp_id -WECOM_SECRET=your_app_secret -WECOM_TOKEN=your_callback_token -WECOM_AES_KEY=your_aes_encoding_key -``` - -### 2. 修改默认密码（生产环境） - -```bash -# 编辑 docker-compose.dify.yml -ADMIN_PASSWORD=your_strong_password -JWT_SECRET=your_jwt_secret -``` - -### 3. 配置 HTTPS（生产环境） - -使用 Nginx 反向代理，参考 `deploy/nginx.conf` - -### 4. 配置域名（生产环境） - -修改 `docker-compose.dify.yml` 中的 URL 配置： - -```yaml -CONSOLE_API_URL: https://your-domain.com -CONSOLE_WEB_URL: https://your-domain.com -``` - -## 故障排查 - -### 1. 端口冲突 - -```bash -# 检查端口占用 -netstat -tulpn | grep -E ':(5001|3000|5433|6380)' - -# 修改 docker-compose.dify.yml 中的端口映射 -ports: - - "5002:5001" # 将 5001 改为 5002 -``` - -### 2. 数据库连接失败 - -```bash -# 检查 PostgreSQL 状态 -docker compose -f docker-compose.dify.yml exec db pg_isready -U postgres - -# 查看数据库日志 -docker compose -f docker-compose.dify.yml logs db -``` - -### 3. 服务启动失败 - -```bash -# 查看详细日志 -docker compose -f docker-compose.dify.yml logs baodan-api - -# 重启服务 -docker compose -f docker-compose.dify.yml restart -``` - -## 文件清单 - -``` -baodanagent/ -├── .env # ✅ 环境变量配置 -├── .env.example # 环境变量模板 -├── .gitignore # Git 忽略规则 -├── deploy.sh # ✅ Linux/Mac 部署脚本 -├── deploy.bat # ✅ Windows 部署脚本 -├── check-env.sh # ✅ 环境检查脚本 -├── DEPLOY_README.md # ✅ 部署指南 -├── CONFIG_COMPLETE.md # ✅ 配置完成总结（本文件） -├── docker-compose.dify.yml # Docker Compose 配置 -├── Dockerfile.dify-custom # API 镜像 -├── Dockerfile.web-custom # Web 镜像 -├── api/insurance/ # 自研后端代码 -├── frontend/dist/ # 前端构建产物 -├── deploy/sql/ # SQL 初始化脚本 -└── scripts/ # 部署辅助脚本 -``` - -## 下一步 - -1. **运行部署脚本**：`./deploy.sh` 或 `deploy.bat` -2. **访问系统**：http://localhost:8080 -3. **登录管理后台**：http://localhost:3000 -4. **配置模型**：在管理后台配置 LLM API Key -5. **创建知识库**：上传保险相关文档 -6. **测试对话**：验证系统功能 - -## 技术支持 - -- 项目文档：[docs/README.md](docs/README.md) -- API 文档：[docs/保险智能客服系统_API接口文档.md](docs/保险智能客服系统_API接口文档.md) -- 故障排查：[DEPLOY_README.md](DEPLOY_README.md) - ---- - -**配置完成时间**: 2026-06-19 -**配置状态**: ✅ 就绪 diff --git a/DEPLOY_README.md b/DEPLOY_README.md deleted file mode 100644 index b2440da..0000000 --- a/DEPLOY_README.md +++ /dev/null @@ -1,170 +0,0 @@ -# 保险智能客服系统 — 部署指南 - -## 🚀 快速部署 - -### Windows 用户 - -```cmd -deploy.bat -``` - -### Linux/Mac 用户 - -```bash -chmod +x deploy.sh -./deploy.sh -``` - -## 📋 手动部署步骤 - -### 1. 环境配置 - -```bash -# 复制环境变量模板 -cp .env.example .env - -# 编辑 .env 文件，填入实际配置 -# 至少需要配置： -# - JWT_SECRET（已自动生成） -# - 企微配置（如果需要企微功能） -``` - -### 2. 构建镜像 - -```bash -# 构建 API 镜像（包含 insurance 模块） -docker build -t baodanagent-dify-api:latest -f Dockerfile.dify-custom . - -# 构建 Web 镜像（自定义品牌） -docker build -t baodanagent-dify-web:latest -f Dockerfile.web-custom . -``` - -### 3. 启动服务 - -```bash -# 启动所有服务 -docker compose -f docker-compose.dify.yml up -d - -# 查看日志 -docker compose -f docker-compose.dify.yml logs -f - -# 等待初始化完成（约 1-2 分钟） -``` - -### 4. 访问系统 - -| 服务 | 地址 | 说明 | -|------|------|------| -| 前端应用 | http://localhost:8080 | Vue 3 前端 | -| 管理后台 | http://localhost:3000 | BaoDan 后台 | -| API 服务 | http://localhost:5001 | 后端 API | - -### 5. 默认管理员账号 - -- **邮箱**: taiyi@baodan.com -- **密码**: taiyi1224 - -## 🔧 配置说明 - -### 必填配置 - -| 配置项 | 说明 | 默认值 | -|--------|------|--------| -| `JWT_SECRET` | JWT 认证密钥 | 已自动生成 | -| `ADMIN_PASSWORD` | 管理员密码 | taiyi1224 | -| `DB_PASSWORD` | 数据库密码 | taiyi1224 | - -### 企微配置（可选） - -如果需要对接企业微信，需要配置以下项： - -| 配置项 | 说明 | -|--------|------| -| `WECOM_CORP_ID` | 企业 ID | -| `WECOM_SECRET` | 应用密钥 | -| `WECOM_TOKEN` | 回调 Token | -| `WECOM_AES_KEY` | 加密 Key | - -## 📦 服务组件 - -| 服务 | 端口 | 说明 | -|------|------|------| -| baodan-api | 5001 | API 服务 + Insurance 模块 | -| baodan-web | 3000 | Web 管理后台 | -| baodan-worker | - | Celery 异步任务 | -| db | 5433 | PostgreSQL 数据库 | -| redis | 6380 | Redis 缓存 | -| plugin_daemon | 5002 | 插件守护进程 | -| sandbox | 8194 | 代码执行沙箱 | - -## 🛠️ 常用命令 - -```bash -# 查看所有服务状态 -docker compose -f docker-compose.dify.yml ps - -# 查看特定服务日志 -docker compose -f docker-compose.dify.yml logs -f baodan-api - -# 重启服务 -docker compose -f docker-compose.dify.yml restart - -# 停止所有服务 -docker compose -f docker-compose.dify.yml down - -# 停止并删除数据卷 -docker compose -f docker-compose.dify.yml down -v -``` - -## 🔍 故障排查 - -### 1. 服务启动失败 - -```bash -# 查看详细日志 -docker compose -f docker-compose.dify.yml logs baodan-api - -# 检查容器状态 -docker compose -f docker-compose.dify.yml ps -``` - -### 2. 数据库连接失败 - -```bash -# 检查 PostgreSQL 是否就绪 -docker compose -f docker-compose.dify.yml exec db pg_isready -U postgres - -# 查看数据库日志 -docker compose -f docker-compose.dify.yml logs db -``` - -### 3. 端口冲突 - -如果端口被占用，可以修改 `docker-compose.dify.yml` 中的端口映射： - -```yaml -ports: - - "5002:5001" # 将 5001 改为 5002 -``` - -## 📝 注意事项 - -1. **首次启动**：数据库迁移和初始化需要 1-2 分钟 -2. **数据持久化**：数据存储在 Docker Volume 中，重启不会丢失 -3. **生产环境**：请修改默认密码和密钥 -4. **备份**：定期备份 PostgreSQL 数据和 Docker Volume - -## 🔐 安全建议 - -1. 修改默认管理员密码 -2. 使用强密码作为 JWT_SECRET -3. 配置 HTTPS（生产环境） -4. 限制数据库和 Redis 的访问权限 -5. 定期更新 Docker 镜像 - -## 📚 更多文档 - -- [项目文档](docs/README.md) -- [API 接口文档](docs/保险智能客服系统_API接口文档.md) -- [开发计划](docs/开发计划.md) -- [部署指南](docs/部署指南.md) diff --git a/DOCKER_OPTIMIZATION.md b/DOCKER_OPTIMIZATION.md deleted file mode 100644 index d1e1b7a..0000000 --- a/DOCKER_OPTIMIZATION.md +++ /dev/null @@ -1,241 +0,0 @@ -# Docker 镜像优化指南 - -## 📊 当前镜像大小分析 - -| 镜像 | 大小 | 说明 | -|------|------|------| -| `langgenius/dify-api:latest` | **4.12GB** | Dify 官方 API 镜像 | -| `baodanagent-dify-api:latest` | **4.12GB** | 自定义 API 镜像 | -| `langgenius/dify-plugin-daemon` | **2.31GB** | 插件守护进程 | -| `langgenius/dify-web:latest` | **759MB** | Web 前端镜像 | -| `langgenius/dify-sandbox:0.2.15` | **848MB** | 代码执行沙箱 | -| **总计** | **~17.5GB** | 所有镜像 | - -## 🔍 镜像大的原因 - -### 1. Dify 官方镜像本身就大 - -Dify 是一个复杂的 AI 应用平台，包含： -- Python 3.12 运行时 -- PyTorch / Transformers（ML 框架） -- 向量数据库依赖（pgvector, qdrant, weaviate） -- 多种 LLM SDK（OpenAI, Anthropic, 本地模型等） -- Celery 异步任务框架 -- 数据库 ORM 和迁移工具 - -### 2. 多服务架构 - -系统包含 6 个独立服务，每个都有自己的镜像： -- API 服务 -- Web 前端 -- Worker 异步任务 -- Plugin Daemon 插件守护进程 -- Sandbox 代码沙箱 -- 数据库和缓存 - -## ✅ 已完成的优化 - -### 1. Dockerfile 优化 - -```dockerfile -# 清理不必要的文件 -RUN apt-get clean && \ - rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \ - pip cache purge 2>/dev/null || true && \ - rm -rf /root/.cache/pip -``` - -### 2. .dockerignore 优化 - -创建了 `.dockerignore` 文件，排除： -- 文档文件（docs/） -- 前端源码（frontend/） -- 测试文件 -- 虚拟环境 -- 缓存文件 - -### 3. 构建缓存优化 - -使用 Docker BuildKit 缓存： -```bash -DOCKER_BUILDKIT=1 docker build --cache-from ... -``` - -## 🚀 进一步优化方案 - -### 方案 1：清理未使用的镜像 - -```bash -# 查看未使用的镜像 -docker images -f "dangling=true" - -# 清理悬空镜像 -docker image prune -f - -# 清理所有未使用的镜像（谨慎使用） -docker image prune -a -f -``` - -### 方案 2：使用精简基础镜像 - -如果不需要所有 Dify 功能，可以使用 Alpine 版本： - -```dockerfile -# 替换 -FROM langgenius/dify-api:latest - -# 为（如果官方提供） -FROM langgenius/dify-api:alpine -``` - -### 方案 3：多阶段构建 - -```dockerfile -# 构建阶段 -FROM python:3.12-slim as builder -COPY requirements.txt . -RUN pip install --user -r requirements.txt - -# 运行阶段 -FROM python:3.12-slim -COPY --from=builder /root/.local /root/.local -COPY api/insurance /app/api/insurance -``` - -### 方案 4：禁用不需要的服务 - -如果不需要某些功能，可以在 `docker-compose.dify.yml` 中注释掉： - -```yaml -# 如果不需要代码沙箱 -# sandbox: -# image: langgenius/dify-sandbox:0.2.15 -# ... - -# 如果不需要插件守护进程 -# plugin_daemon: -# image: langgenius/dify-plugin-daemon:0.6.1-local -# ... -``` - -## 🛠️ 磁盘清理工具 - -### 使用清理脚本 - -```bash -# 运行清理脚本 -./docker-cleanup.sh -``` - -### 手动清理命令 - -```bash -# 1. 查看 Docker 磁盘使用 -docker system df - -# 2. 清理停止的容器 -docker container prune -f - -# 3. 清理悬空镜像 -docker image prune -f - -# 4. 清理构建缓存 -docker builder prune -f - -# 5. 清理所有未使用资源（谨慎） -docker system prune -a -f - -# 6. 清理所有未使用资源包括卷（非常谨慎） -docker system prune -a -f --volumes -``` - -## 📈 优化效果对比 - -| 优化措施 | 预计节省 | 说明 | -|---------|---------|------| -| 清理构建缓存 | 8-10GB | 一次性释放 | -| 清理悬空镜像 | 300-500MB | 定期清理 | -| 禁用不需要的服务 | 2-3GB | 按需裁剪 | -| 使用 .dockerignore | 50-100MB | 每次构建 | - -## 🎯 推荐优化步骤 - -### 第一步：立即释放空间 - -```bash -# 清理构建缓存（最大收益） -docker builder prune -f --keep-storage 2GB - -# 清理悬空镜像 -docker image prune -f -``` - -### 第二步：评估服务需求 - -根据实际需求决定保留哪些服务： - -| 服务 | 必要性 | 说明 | -|------|:------:|------| -| baodan-api | ✅ 必须 | 核心 API 服务 | -| baodan-web | ✅ 必须 | 管理后台 | -| baodan-worker | ⚠️ 按需 | 异步任务（可选） | -| db | ✅ 必须 | 数据库 | -| redis | ✅ 必须 | 缓存 | -| plugin_daemon | ⚠️ 按需 | 插件功能（可选） | -| sandbox | ⚠️ 按需 | 代码执行（可选） | - -### 第三步：优化 Dockerfile - -已优化的 Dockerfile 包含： -- 清理 apt 缓存 -- 清理 pip 缓存 -- 删除临时文件 - -### 第四步：定期维护 - -```bash -# 添加到 crontab（每周清理一次） -0 2 * * 0 cd /path/to/project && docker system prune -f >> /var/log/docker-cleanup.log 2>&1 -``` - -## 📝 注意事项 - -1. **不要删除正在使用的镜像**：先停止容器再删除镜像 -2. **谨慎使用 `--volumes`**：会删除所有未挂载的数据卷 -3. **备份重要数据**：清理前确保数据已备份 -4. **保留基础镜像**：避免重复下载官方镜像 - -## 🔗 相关命令参考 - -```bash -# 查看镜像详情 -docker inspect - -# 查看镜像层 -docker history - -# 导出镜像（备份） -docker save -o baodan-api.tar baodanagent-dify-api:latest - -# 导入镜像（恢复） -docker load -i baodan-api.tar - -# 推送到私有仓库 -docker tag baodanagent-dify-api:latest your-registry.com/baodan-api:latest -docker push your-registry.com/baodan-api:latest -``` - -## 📊 最终优化效果 - -经过优化后，预计磁盘使用： - -| 项目 | 优化前 | 优化后 | 节省 | -|------|--------|--------|------| -| 镜像大小 | 17.5GB | 10-12GB | 5-7GB | -| 构建缓存 | 10.3GB | 2GB | 8GB | -| **总计** | **~28GB** | **~14GB** | **~14GB** | - ---- - -**优化完成时间**: 2026-06-19 -**优化状态**: ✅ 已完成基础优化 diff --git a/QUICK_START.md b/QUICK_START.md deleted file mode 100644 index 09b2263..0000000 --- a/QUICK_START.md +++ /dev/null @@ -1,169 +0,0 @@ -# 🚀 快速部署指南 - -## 最小化部署（推荐） - -直接拉取官方镜像，无需本地构建，5 分钟完成部署。 - -### 镜像大小 - -| 镜像 | 大小 | 说明 | -|------|------|------| -| `langgenius/dify-api` | ~900MB | API 服务 | -| `langgenius/dify-web` | ~170MB | Web 前端 | -| `pgvector/pgvector:pg15` | ~300MB | 数据库 | -| `redis:7-alpine` | ~30MB | 缓存 | -| **总计** | **~1.4GB** | 比完整版节省 16GB | - -### 一键部署 - -**Linux/Mac:** -```bash -chmod +x quick-deploy.sh -./quick-deploy.sh -``` - -**Windows:** -```cmd -quick-deploy.bat -``` - -### 手动部署 - -```bash -# 1. 拉取镜像 -docker pull pgvector/pgvector:pg15 -docker pull redis:7-alpine -docker pull langgenius/dify-api:latest -docker pull langgenius/dify-web:latest - -# 2. 启动服务 -docker compose -f docker-compose.minimal.yml up -d - -# 3. 等待初始化（约 1-2 分钟） -docker compose -f docker-compose.minimal.yml logs -f - -# 4. 访问系统 -# 浏览器打开 http://localhost:3000 -``` - -## 访问地址 - -| 服务 | 地址 | 说明 | -|------|------|------| -| 管理后台 | http://localhost:3000 | Dify 后台 | -| API 服务 | http://localhost:5001 | 后端 API | - -## 默认账号 - -- **邮箱**: taiyi@baodan.com -- **密码**: taiyi1224 - -## 服务说明 - -最小化部署包含 4 个核心服务： - -| 服务 | 必要性 | 说明 | -|------|:------:|------| -| db | ✅ | PostgreSQL 数据库 | -| redis | ✅ | Redis 缓存 | -| dify-api | ✅ | API 服务 | -| dify-worker | ✅ | 异步任务处理 | -| dify-web | ✅ | Web 前端 | - -**已移除的服务**（节省空间）： -- ❌ sandbox — 代码执行沙箱（848MB） -- ❌ plugin_daemon — 插件守护进程（2.3GB） - -## 常用命令 - -```bash -# 查看服务状态 -docker compose -f docker-compose.minimal.yml ps - -# 查看日志 -docker compose -f docker-compose.minimal.yml logs -f - -# 停止服务 -docker compose -f docker-compose.minimal.yml down - -# 重启服务 -docker compose -f docker-compose.minimal.yml restart - -# 停止并删除数据 -docker compose -f docker-compose.minimal.yml down -v -``` - -## 下一步 - -1. **访问管理后台**：http://localhost:3000 -2. **配置模型**：在后台添加 LLM API Key（如 DeepSeek、OpenAI） -3. **创建应用**：创建聊天应用或 Workflow -4. **配置知识库**：上传保险相关文档 -5. **测试对话**：验证系统功能 - -## 完整版部署 - -如需完整功能（代码沙箱、插件支持），使用完整版： - -```bash -docker compose -f docker-compose.dify.yml up -d -``` - -完整版镜像大小：~17.5GB - -## 故障排查 - -### 端口冲突 - -```bash -# 检查端口占用 -netstat -tulpn | grep -E ':(5001|3000|5433|6380)' - -# 修改端口映射 -# 编辑 docker-compose.minimal.yml -ports: - - "5002:5001" # 将 5001 改为 5002 -``` - -### 服务启动失败 - -```bash -# 查看详细日志 -docker compose -f docker-compose.minimal.yml logs dify-api - -# 重启服务 -docker compose -f docker-compose.minimal.yml restart -``` - -### 数据库连接失败 - -```bash -# 检查数据库状态 -docker compose -f docker-compose.minimal.yml exec db pg_isready -U postgres - -# 查看数据库日志 -docker compose -f docker-compose.minimal.yml logs db -``` - -## 文件清单 - -``` -baodanagent/ -├── docker-compose.minimal.yml # 最小化部署配置 -├── quick-deploy.sh # Linux/Mac 快速部署脚本 -├── quick-deploy.bat # Windows 快速部署脚本 -└── QUICK_START.md # 本文档 -``` - -## 环境要求 - -- Docker 20.10+ -- Docker Compose 2.0+ -- 磁盘空间：2GB+ -- 内存：4GB+ - ---- - -**部署时间**: ~5 分钟 -**镜像大小**: ~1.4GB -**推荐场景**: 快速体验、开发测试、资源受限环境 diff --git a/README.md b/README.md index 6aeeaba..f2a415a 100644 --- a/README.md +++ b/README.md @@ -131,15 +131,15 @@ curl http://localhost:5001/api/health | 文档 | 说明 | |------|------| -| [需求文档](docs/保险智能客服系统_需求文档.md) | 125 项功能 + 数据库设计 + 数据流转 | +| [需求文档](docs/保险智能客服系统_需求文档.md) | 137 项功能 + 数据库设计 + 数据流转 | | [API 接口文档](docs/保险智能客服系统_API接口文档.md) | 45 个接口完整设计 | -| [开发计划](docs/开发计划.md) | 8 阶段开发计划（排除 BaoDan 重复功能） | -| [开发任务清单](docs/开发任务清单.md) | 185 项可勾选任务 | +| [后续开发计划](docs/后续开发计划.md) | 项目状态（64%）+ 未完成功能 + 时间表 | +| [开发任务清单](docs/开发任务清单.md) | 412 项可勾选任务 | | [编码规范](docs/保险智能客服系统_编码规范.md) | 编码标准 + BaoDan 集成规范 | | [测试用例](docs/保险智能客服系统_测试用例.md) | 功能/边界/异常测试 + 上线 Checklist | | [前端开发计划](docs/前端开发计划.md) | Vue 3 前端完整组件代码 | | [API curl 示例](docs/API_curl示例.md) | 接口调试 curl 示例 | -| [部署指南](docs/部署指南.md) | BaoDan 源码集成指南 | +| [部署指南](docs/部署文档_完整版.md) | 完整部署文档 + 架构图 | ## BaoDan 升级流程 diff --git a/SERVER_DEPLOY.md b/SERVER_DEPLOY.md deleted file mode 100644 index 8b37f32..0000000 --- a/SERVER_DEPLOY.md +++ /dev/null @@ -1,396 +0,0 @@ -# 🚀 服务器快速部署指南 - -## 方案对比 - -| 方案 | 适用场景 | 部署时间 | 网络要求 | 复杂度 | -|------|---------|---------|---------|--------| -| **方案一：一键脚本** | 有网络环境 | 5 分钟 | 需要外网 | ⭐ | -| **方案二：预构建镜像** | 多次部署 | 2 分钟 | 需要 Docker Hub | ⭐⭐ | -| **方案三：离线部署** | 无网络环境 | 10 分钟 | 无需网络 | ⭐⭐ | -| **方案四：最简部署** | 快速测试 | 3 分钟 | 需要镜像 | ⭐ | - ---- - -## 方案一：一键部署脚本（推荐） - -**适用场景**：首次部署、有网络环境 - -**部署步骤**： - -```bash -# 1. 上传部署脚本到服务器 -scp deploy-package.sh user@server:/opt/ - -# 2. 在服务器上执行 -ssh user@server -chmod +x /opt/deploy-package.sh -./deploy-package.sh -``` - -**或者直接执行**： - -```bash -# 一键部署（需要先配置 Git 仓库） -curl -fsSL https://raw.githubusercontent.com/your-repo/deploy.sh | bash -``` - ---- - -## 方案二：预构建镜像部署 - -**适用场景**：多台服务器部署、CI/CD 流程 - -### 步骤一：构建并推送镜像 - -```bash -# 1. 登录 Docker Hub -docker login - -# 2. 修改 build-and-push.sh 中的用户名 -vim build-and-push.sh -# DOCKER_HUB_USERNAME="your-username" - -# 3. 构建并推送 -./build-and-push.sh -``` - -### 步骤二：服务器部署 - -```bash -# 1. 创建部署目录 -mkdir -p /opt/baodanagent -cd /opt/baodanagent - -# 2. 下载配置文件 -wget https://raw.githubusercontent.com/your-repo/docker-compose.production.yml -O docker-compose.yml - -# 3. 配置环境变量 -cat > .env << EOF -JWT_SECRET=$(openssl rand -hex 32) -DB_PASSWORD=your-secure-password -EOF - -# 4. 启动服务 -docker compose up -d -``` - ---- - -## 方案三：离线镜像部署 - -**适用场景**：无网络环境、内网部署 - -### 步骤一：导出镜像（有网络的机器） - -```bash -# 1. 构建镜像 -docker compose build - -# 2. 导出镜像 -./export-images.sh - -# 3. 生成的文件 -# - baodanagent-images.tar.gz（约 2-3GB） -``` - -### 步骤二：传输到服务器 - -```bash -# 方式一：SCP -scp baodanagent-images.tar.gz user@server:/opt/baodanagent/ - -# 方式二：U盘/移动硬盘 -cp baodanagent-images.tar.gz /mnt/usb/ - -# 方式三：内网文件服务器 -scp baodanagent-images.tar.gz fileserver:/data/ -``` - -### 步骤三：服务器部署 - -```bash -# 1. 进入部署目录 -cd /opt/baodanagent - -# 2. 解压镜像 -tar -xzf baodanagent-images.tar.gz - -# 3. 导入镜像 -for f in *.tar; do docker load -i $f; done - -# 4. 启动服务 -./import-and-start.sh -``` - ---- - -## 方案四：最简部署 - -**适用场景**：快速测试、开发环境 - -```bash -# 一条命令部署 -bash quick-start.sh -``` - ---- - -## 部署后配置 - -### 1. 修改默认密码 - -```bash -# 编辑环境变量 -vim .env - -# 修改以下配置 -ADMIN_PASSWORD=your-secure-password -JWT_SECRET=your-secure-jwt-secret - -# 重启服务 -docker compose restart -``` - -### 2. 配置域名和 HTTPS - -```bash -# 安装 Nginx -apt install nginx - -# 配置 Nginx -cat > /etc/nginx/sites-available/baodanagent << 'EOF' -server { - listen 80; - server_name your-domain.com; - return 301 https://$server_name$request_uri; -} - -server { - listen 443 ssl; - server_name your-domain.com; - - ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; - - location / { - proxy_pass http://localhost:8080; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } - - location /api/ { - proxy_pass http://localhost:5001/; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } -} -EOF - -# 启用配置 -ln -s /etc/nginx/sites-available/baodanagent /etc/nginx/sites-enabled/ -nginx -t && systemctl reload nginx -``` - -### 3. 配置防火墙 - -```bash -# Ubuntu/Debian -ufw allow 80/tcp -ufw allow 443/tcp -ufw allow 8080/tcp -ufw allow 5001/tcp - -# CentOS/RHEL -firewall-cmd --permanent --add-port=80/tcp -firewall-cmd --permanent --add-port=443/tcp -firewall-cmd --permanent --add-port=8080/tcp -firewall-cmd --permanent --add-port=5001/tcp -firewall-cmd --reload -``` - ---- - -## 常用运维命令 - -### 服务管理 - -```bash -# 查看服务状态 -docker compose ps - -# 查看日志 -docker compose logs -f - -# 重启服务 -docker compose restart - -# 停止服务 -docker compose down - -# 启动服务 -docker compose up -d -``` - -### 数据备份 - -```bash -# 备份数据库 -docker compose exec db pg_dump -U postgres baodan > backup_$(date +%Y%m%d).sql - -# 备份 Redis -docker compose exec redis redis-cli save -cp /var/lib/docker/volumes/baodanagent_redis_data/_data/dump.rdb backup_redis_$(date +%Y%m%d).rdb - -# 备份所有数据 -tar -czf backup_$(date +%Y%m%d).tar.gz /var/lib/docker/volumes/baodanagent_* -``` - -### 数据恢复 - -```bash -# 恢复数据库 -docker compose exec -T db psql -U postgres baodan < backup_20260619.sql - -# 恢复 Redis -docker compose exec redis redis-cli shutdown nosave -cp backup_redis_20260619.rdb /var/lib/docker/volumes/baodanagent_redis_data/_data/dump.rdb -docker compose start redis -``` - -### 更新版本 - -```bash -# 拉取最新代码 -git pull - -# 重新构建并启动 -docker compose up -d --build - -# 或者使用预构建镜像 -docker compose pull -docker compose up -d -``` - ---- - -## 故障排查 - -### 服务无法启动 - -```bash -# 查看详细日志 -docker compose logs baodanagent-api - -# 检查端口占用 -netstat -tulpn | grep -E ':(5001|8080|5433|6380)' - -# 检查磁盘空间 -df -h - -# 检查内存 -free -h -``` - -### 数据库连接失败 - -```bash -# 检查数据库状态 -docker compose exec db pg_isready -U postgres - -# 查看数据库日志 -docker compose logs db - -# 连接数据库 -docker compose exec db psql -U postgres -d baodan -``` - -### 性能优化 - -```bash -# 增加 Worker 数量 -# 编辑 docker-compose.yml -environment: - WORKERS: 4 # 根据 CPU 核心数调整 - -# 增加内存限制 -deploy: - resources: - limits: - memory: 2G -``` - ---- - -## 监控配置 - -### Docker 健康检查 - -```bash -# 查看健康状态 -docker inspect --format='{{.State.Health.Status}}' baodanagent-baodanagent-api-1 - -# 查看健康检查日志 -docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' baodanagent-baodanagent-api-1 -``` - -### 系统监控脚本 - -```bash -#!/bin/bash -# monitor.sh - 服务监控脚本 - -while true; do - if ! curl -s http://localhost:5001/health > /dev/null; then - echo "[$(date)] API 服务异常，正在重启..." - docker compose restart baodanagent-api - fi - sleep 60 -done -``` - ---- - -## 文件清单 - -``` -baodanagent/ -├── deploy-package.sh # 方案一：一键部署脚本 -├── build-and-push.sh # 方案二：构建并推送镜像 -├── docker-compose.production.yml # 方案二：生产环境配置 -├── export-images.sh # 方案三：导出镜像 -├── import-and-start.sh # 方案三：导入并启动 -├── quick-start.sh # 方案四：最简部署 -└── SERVER_DEPLOY.md # 本文档 -``` - ---- - -## 推荐部署流程 - -### 首次部署 - -1. **选择方案一**：使用一键部署脚本 -2. **配置环境变量**：修改密码和密钥 -3. **配置域名**：设置 Nginx 反向代理 -4. **配置 HTTPS**：申请 SSL 证书 -5. **配置备份**：设置定时备份任务 - -### 多服务器部署 - -1. **选择方案二**：使用预构建镜像 -2. **构建并推送镜像**：执行 build-and-push.sh -3. **服务器部署**：使用 docker-compose.production.yml -4. **配置负载均衡**：使用 Nginx 或 HAProxy - -### 无网络环境 - -1. **选择方案三**：使用离线镜像 -2. **导出镜像**：执行 export-images.sh -3. **传输镜像**：使用 U盘或内网传输 -4. **导入并启动**：执行 import-and-start.sh - ---- - -**部署时间**: 2-10 分钟 -**适用环境**: Linux (Ubuntu/CentOS/Debian) -**推荐方案**: 方案一（首次部署）或 方案二（多服务器） diff --git a/WECOM_CONFIG_GUIDE.md b/WECOM_CONFIG_GUIDE.md deleted file mode 100644 index f1a94bf..0000000 --- a/WECOM_CONFIG_GUIDE.md +++ /dev/null @@ -1,181 +0,0 @@ -# 企业微信配置指南 - -## 📋 配置前准备 - -在配置企业微信之前，你需要： - -1. **注册企业微信账号**：访问 https://work.weixin.qq.com/ 注册 -2. **创建自建应用**：在管理后台 -> 应用管理 -> 自建 -> 创建应用 -3. **获取配置信息**：按照以下步骤获取各项参数 - ---- - -## 🔑 配置参数说明 - -### 1. Corp ID（企业ID） - -**获取方式**： -1. 登录企业微信管理后台 -2. 进入 **我的企业** -> **企业信息** -3. 找到 **企业ID**（格式：`ww` 开头的字符串） - -**示例**：`ww1234567890abcdef` - ---- - -### 2. Secret（应用Secret） - -**获取方式**： -1. 登录企业微信管理后台 -2. 进入 **应用管理** -> **自建** -> 选择你的应用 -3. 找到 **Secret**（点击获取，需要管理员权限） - -**示例**：`abcdef1234567890abcdef1234567890` - ---- - -### 3. Token（回调配置Token） - -**获取方式**： -1. 在应用配置页面，找到 **接收消息** -> **设置API接收** -2. 自定义一个 Token（用于验证回调请求） - -**示例**：`my_callback_token_123456` - ---- - -### 4. AES Key（消息加解密密钥） - -**获取方式**： -1. 在应用配置页面，找到 **接收消息** -> **设置API接收** -2. 点击 **随机获取** 生成一个 EncodingAESKey - -**示例**：`abcdefghijklmnopqrstuvwxyz1234567890ABCDEFG` - ---- - -### 5. Webhook URL（机器人消息推送） - -**获取方式**： -1. 在企业微信中添加一个群机器人 -2. 获取机器人的 Webhook URL - -**示例**：`https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` - ---- - -## 🛠️ 配置步骤 - -### 方法一：修改 docker-compose.dify.yml（推荐） - -编辑 `docker-compose.dify.yml` 文件，找到以下配置： - -```yaml -# 企微配置（需填入真实值） -WECOM_CORP_ID: "" -WECOM_SECRET: "" -WECOM_TOKEN: "" -WECOM_AES_KEY: "" -WECOM_WEBHOOK_URL: "" -``` - -替换为你的真实值： - -```yaml -# 企微配置（已配置） -WECOM_CORP_ID: "ww1234567890abcdef" -WECOM_SECRET: "abcdef1234567890abcdef1234567890" -WECOM_TOKEN: "my_callback_token_123456" -WECOM_AES_KEY: "abcdefghijklmnopqrstuvwxyz1234567890ABCDEFG" -WECOM_WEBHOOK_URL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -``` - -### 方法二：使用 .env 文件 - -1. 复制 `.env.example` 为 `.env` -2. 编辑 `.env` 文件，填入企微配置 - ---- - -## 🔄 应用配置 - -配置完成后，需要重启服务： - -```bash -# 重启 API 服务 -docker compose -f docker-compose.dify.yml up -d baodan-api - -# 重启 Worker 服务（如果需要） -docker compose -f docker-compose.dify.yml up -d baodan-worker -``` - ---- - -## 🧪 测试配置 - -### 1. 测试登录接口 - -```bash -# 测试企微登录（需要真实企微环境） -curl -X POST http://localhost:5001/insurance/auth/wework-login \ - -H "Content-Type: application/json" \ - -d '{"code": "test_code", "state": ""}' -``` - -### 2. 测试 Webhook - -```bash -# 测试机器人消息推送 -curl -X POST http://localhost:5001/insurance/wecom/webhook/test \ - -H "Content-Type: application/json" \ - -d '{"message": "测试消息"}' -``` - ---- - -## 📝 配置示例 - -### 完整配置示例 - -```yaml -# 企微配置 -WECOM_CORP_ID: "ww1234567890abcdef" -WECOM_SECRET: "abcdef1234567890abcdef1234567890" -WECOM_TOKEN: "my_callback_token_123456" -WECOM_AES_KEY: "abcdefghijklmnopqrstuvwxyz1234567890ABCDEFG" -WECOM_WEBHOOK_URL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -``` - ---- - -## ⚠️ 注意事项 - -1. **安全第一**：Secret 和 AES Key 是敏感信息，不要提交到 Git -2. **回调地址**：确保企微后台配置的回调地址可访问 -3. **域名配置**：生产环境需要配置域名和 HTTPS -4. **权限申请**：部分接口需要在企微后台申请权限 - ---- - -## 🔍 常见问题 - -### Q1: 登录提示"企业ID无效" -- 检查 Corp ID 是否正确（`ww` 开头） -- 确认企业微信已激活 - -### Q2: 回调验证失败 -- 检查 Token 和 AES Key 是否匹配 -- 确认回调地址可访问 - -### Q3: Webhook 消息发送失败 -- 检查 Webhook URL 是否正确 -- 确认机器人未被移除 - ---- - -## 📞 获取帮助 - -如果遇到问题，可以： -1. 查看后端日志：`docker logs baodanagent-baodan-api-1` -2. 检查企微管理后台的配置 -3. 参考企微官方文档：https://work.weixin.qq.com/api/doc diff --git a/WECOM_GROUP_CONFIG.md b/WECOM_GROUP_CONFIG.md deleted file mode 100644 index 8e626b5..0000000 --- a/WECOM_GROUP_CONFIG.md +++ /dev/null @@ -1,56 +0,0 @@ -# 企微群聊消息配置说明 - -## 问题原因 - -企微的应用群聊接口 `/cgi-bin/appchat/send` 发送群聊消息需要在企微后台配置"群聊会话"功能。 - -## 解决方案 - -### 方案1：使用群机器人 Webhook（单群/指定群） - -1. **在企微群里添加群机器人** - - 打开企业微信，进入目标群聊 - - 点击右上角 `...` -> 群机器人 -> 添加机器人 - - 复制 Webhook 地址 - -2. **配置环境变量** - ```bash - # 历史配置：只适合无 chatid 的兜底场景，不适合多群动态回复 - WECOM_GROUP_WEBHOOK=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_WEBHOOK_KEY - ``` - - 如果必须按不同群使用不同 Webhook，可以配置 `chatid` 到 Webhook 的映射： - ```bash - WECOM_GROUP_WEBHOOKS={"CHAT_ID_A":"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=KEY_A","CHAT_ID_B":"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=KEY_B"} - ``` - -> 多个群不能共用一个 `WECOM_GROUP_WEBHOOK`，否则 B 群的问题也会被发送到 A 群。 -> 多群请优先使用下面的"群聊会话"方案，按当前回调消息里的 `chatid` 发送。 - -### 方案2：配置"群聊会话"功能 - -1. **在企微管理后台配置** - - 登录 https://work.weixin.qq.com/wework_admin/frame - - 应用管理 -> 选择你的应用 - - 开启"群聊会话"功能 - - 配置允许接收消息的群聊 - -2. **确保应用在群里** - - 将应用机器人添加到目标群聊 - - 或者手动创建群聊会话并邀请机器人 - -## 验证方法 - -1. 重启服务后，在群里 @机器人 发送消息 -2. 查看日志，确认不再出现 `82001` 错误 -3. 机器人应该能正常回复消息 - -## 错误码说明 - -| 错误码 | 含义 | 解决方案 | -|--------|------|----------| -| 82001 | touser/toparty/totag/ticket 无效 | 使用群机器人 Webhook 或配置"群聊会话"功能 | -| 40009 | 不合法的文件类型 | 检查消息格式 | -| 40014 | 不合法的 access_token | 检查 WECOM_SECRET 配置 | -| 41001 | 缺少 access_token | 检查企微配置 | -| 45009 | 接口调用超过限制 | 降低调用频率 | diff --git a/docs/README.md b/docs/README.md index 9cf5803..f7ec8a7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,25 +1,54 @@ # 保险智能客服系统 — 文档索引 -> **最后更新**：2026-06-08 -> **项目状态**：后端 8 模块完成 + 前端 12 页面完成，进度 43% +> **最后更新**：2026-07-23 +> **项目状态**：后端框架完成 + 核心功能完成 64%，产品推荐功能待实现 --- ## 文档总览 -| 文档 | 位置 | 内容摘要 | -|------|------|---------| -| [需求文档](../保险智能客服系统_需求文档.md) | 根目录 | 完整需求：125 项功能 + 5 角色 + 数据库设计 | -| [API 接口文档](../保险智能客服系统_API接口文档.md) | 根目录 | 45 个接口完整设计 | -| [编码规范](../保险智能客服系统_编码规范.md) | 根目录 | 命名规范 + 项目结构 + BaoDan 集成规范 | -| [测试用例](../保险智能客服系统_测试用例.md) | 根目录 | 功能测试 + 边界测试 + 上线 Checklist | -| [开发计划](../开发计划.md) | 根目录 | 8 阶段开发计划 | -| [开发任务清单](../开发任务清单.md) | 根目录 | 412 项可勾选任务（已完成 182 项） | -| [**快速启动指南**](快速启动指南.md) | docs/ | **一键启动 + 配置流程** | -| [**BaoDan Workflow 配置指南**](BaoDan_Workflow配置指南.md) | docs/ | **产品推荐 Workflow 详细配置步骤** | -| [**企业微信接入指南**](企业微信接入指南.md) | docs/ | **企微自建应用、机器人消息、OAuth 登录完整配置** | -| [部署指南](../部署指南.md) | 根目录 | BaoDan 源码集成指南 | -| [API curl 示例](../API_curl示例.md) | 根目录 | 接口调试 curl 示例 | +### 核心规范文档 + +| 文档 | 内容摘要 | +|------|---------| +| [保险智能客服系统_需求文档.md](保险智能客服系统_需求文档.md) | 完整需求：137 项功能 + 5 角色 + 数据库设计 | +| [保险智能客服系统_API接口文档.md](保险智能客服系统_API接口文档.md) | 45 个接口完整设计 | +| [保险智能客服系统_编码规范.md](保险智能客服系统_编码规范.md) | 命名规范 + 项目结构 + BaoDan 集成规范 | +| [保险智能客服系统_测试用例.md](保险智能客服系统_测试用例.md) | 347 个功能测试 + 边界测试 + 上线 Checklist | +| [保险智能客服系统_文档规范.md](保险智能客服系统_文档规范.md) | 文档编写标准和模板 | + +### 开发计划与任务 + +| 文档 | 内容摘要 | +|------|---------| +| [后续开发计划.md](后续开发计划.md) | 当前项目状态（64%）、未完成功能、开发时间表 | +| [开发任务清单.md](开发任务清单.md) | 412 项可勾选任务（已完成 182 项） | +| [后端开发文档.md](后端开发文档.md) | 后端项目结构、待开发功能、API 接口清单 | +| [前端开发计划.md](前端开发计划.md) | 前端组件代码、页面结构、开发规范 | + +### 部署与运维 + +| 文档 | 内容摘要 | +|------|---------| +| [快速启动指南.md](快速启动指南.md) | 本地开发一键启动 + Docker 环境 | +| [部署指南.md](部署指南.md) | BaoDan 源码集成指南（修改 main.py） | +| [部署文档_完整版.md](部署文档_完整版.md) | 完整部署文档 + 架构图 + 环境变量配置 | +| [宝塔面板部署指南.md](宝塔面板部署指南.md) | 宝塔面板 Docker 部署详解 | +| [前端移动端适配指南.md](前端移动端适配指南.md) | 移动端响应式适配审计（68% 未适配） | + +### 企微与集成 + +| 文档 | 内容摘要 | +|------|---------| +| [企业微信接入指南.md](企业微信接入指南.md) | 自建应用 + 机器人消息 + OAuth 登录 + 回调排查 | +| [Dify_Workflow配置指南.md](Dify_Workflow配置指南.md) | 产品推荐 Workflow 配置步骤 | + +### 参考与交付 + +| 文档 | 内容摘要 | +|------|---------| +| [API_curl示例.md](API_curl示例.md) | 接口调试 curl 示例（可直接复制） | +| [保险智能客服系统_客户验收单.md](保险智能客服系统_客户验收单.md) | 项目验收/交付清单 | --- @@ -27,28 +56,36 @@ ### 开始开发前必读 -1. **[README.md](../README.md)** — 5 分钟了解项目全貌 -2. **[需求文档](../保险智能客服系统_需求文档.md)** — 需求细节（特别是第六章数据库、第九章 BaoDan 集成、第十二章数据流转图） -3. **[开发计划](../开发计划.md)** — 哪些做、哪些不做（BaoDan 原生功能清单） -4. **[开发任务清单](../开发任务清单.md)** — 每天干什么、完成后打勾 +1. **[需求文档](保险智能客服系统_需求文档.md)** — 需求细节（特别是数据库设计、BaoDan 集成、数据流转图） +2. **[后续开发计划.md](后续开发计划.md)** — 哪些已完成、哪些待开发 +3. **[开发任务清单](开发任务清单.md)** — 每天干什么、完成后打勾 ### 写代码时参考 -5. **[编码规范](../保险智能客服系统_编码规范.md)** — 命名、注释、格式化、错误处理、日志、Git 规范 -6. **[API 接口文档](../保险智能客服系统_API接口文档.md)** — 接口设计的权威来源 -7. **[API curl 示例](../API_curl示例.md)** — 调试接口时直接复制 +4. **[编码规范](保险智能客服系统_编码规范.md)** — 命名、注释、格式化、错误处理、日志、Git 规范 +5. **[API 接口文档](保险智能客服系统_API接口文档.md)** — 接口设计的权威来源 +6. **[API curl 示例](API_curl示例.md)** — 调试接口时直接复制 ### 前端开发 -8. **[前端开发计划](../前端开发计划.md)** — 完整组件代码（可以直接参考/复制） +7. **[前端开发计划](前端开发计划.md)** — 完整组件代码（可以直接参考/复制） +8. **[前端移动端适配指南](前端移动端适配指南.md)** — 移动端适配现状和修复方案 ### 测试验收 -9. **[测试用例](../保险智能客服系统_测试用例.md)** — 347 个测试用例 + 上线 Checklist +9. **[测试用例](保险智能客服系统_测试用例.md)** — 347 个测试用例 + 上线 Checklist +10. **[客户验收单](保险智能客服系统_客户验收单.md)** — 项目交付验收 ### 部署上线 -10. **[部署指南](../部署指南.md)** — BaoDan 集成步骤 + API Key 配置 +11. **[快速启动指南](快速启动指南.md)** — 本地开发一键启动 +12. **[部署指南](部署指南.md)** — BaoDan 源码集成步骤 +13. **[部署文档_完整版](部署文档_完整版.md)** — 生产环境完整部署 +14. **[宝塔面板部署](宝塔面板部署指南.md)** — 宝塔面板部署 + +### 企微对接 + +15. **[企业微信接入指南](企业微信接入指南.md)** — 完整接入流程 + 故障排查 --- diff --git a/docs/企业微信接入指南.md b/docs/企业微信接入指南.md index cd8748a..232c635 100644 --- a/docs/企业微信接入指南.md +++ b/docs/企业微信接入指南.md @@ -305,6 +305,49 @@ curl -v "https://your-domain.com/insurance/wecom/callback?msg_signature=xxx&time 3. 确认防火墙已开放 443 端口 4. 使用在线工具检测 SSL：https://www.ssllabs.com/ssltest/ +### 问题 6: 企微后台提示「回调地址请求不通过」 + +**现象**: 保存配置时提示 `openapi回调地址请求不通过` + +**常见原因**: +1. AES 解密未正确实现 — 回调验证需要解密 echostr，代码只返回了原始密文 +2. 环境变量未配置 — Docker 容器中缺少企微配置 +3. Token/AES Key 不一致 — 企微后台配置与 `.env` 中的值不匹配 +4. SSL 证书问题 — 自签名证书不被企微信任 + +**排查步骤**: +1. 手动测试回调接口： + ```bash + curl "https://your-domain.com/insurance/wecom/callback?msg_signature=test×tamp=1234567890&nonce=test&echostr=test" + # 应返回：Invalid signature（说明服务正常，只是参数不对） + ``` +2. 检查 Docker 日志：`docker compose logs baodanagent-api | grep -i wecom` +3. 确认 Token 和 AES Key 与企微后台完全一致 +4. 确认 SSL 证书有效（非自签名） + +### 问题 7: 5 秒内未返回 success + +**现象**: 企微日志显示超时 + +**原因**: 服务器响应太慢 + +**解决**: 检查服务器性能、网络延迟，确保回调处理在 5 秒内完成 + +### 开发环境调试（内网穿透） + +本地开发时，企微无法访问 localhost，需要使用内网穿透工具： + +```bash +# 使用 ngrok +ngrok http 8080 +# 获取公网地址，如：https://xxxx.ngrok.io + +# 使用 frp（自建服务器） +# 配置 frpc.ini 指向本地 8080 端口 +``` + +将获取到的公网地址配置到企微后台的回调 URL 中。 + --- ## 接口说明 diff --git a/docs/企微回调配置指南.md b/docs/企微回调配置指南.md deleted file mode 100644 index b3fddd9..0000000 --- a/docs/企微回调配置指南.md +++ /dev/null @@ -1,213 +0,0 @@ -# 企微回调服务器配置指南 - -## 一、问题现象 - -在企微后台设置接收消息服务器时，保存配置提示： -> "openapi回调地址请求不通过" - -## 二、问题原因 - -1. **AES解密未实现** - 回调验证需要解密echostr，原代码只返回了原始密文 -2. **环境变量未配置** - Docker容器中缺少企微配置 -3. **回调地址不可访问** - 服务器无法访问配置的URL - -## 三、配置步骤 - -### 步骤1：获取企微配置信息 - -登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)，进入： - -**应用管理 → 接收消息 → 设置接收消息服务器** - -你需要获取以下信息： - -| 配置项 | 说明 | 示例 | -|--------|------|------| -| 企业ID (CorpID) | 企业微信后台 → 我的企业 → 企业信息 | `ww1234567890abcdef` | -| 应用Secret | 应用管理 → 自建应用 → Secret | `a1b2c3d4e5f6...` | -| 回调Token | 自定义，用于验证请求 | `my_callback_token_123456` | -| 消息加密密钥 | 43位字符，系统自动生成 | `abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG` | - -### 步骤2：配置Docker环境变量 - -在服务器上创建 `.env` 文件： - -```bash -cd /path/to/baodanagent/deploy-package/baodanagent -cp .env.example .env -``` - -编辑 `.env` 文件，填入真实配置： - -```bash -# 企微配置 -WECOM_CORP_ID=ww1234567890abcdef -WECOM_SECRET=a1b2c3d4e5f6... -WECOM_TOKEN=my_callback_token_123456 -WECOM_AES_KEY=abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG -``` - -### 步骤3：确保回调地址可访问 - -#### 方案A：使用HTTPS（推荐，生产环境） - -1. 配置域名和SSL证书 -2. 设置Nginx反向代理 - -```nginx -server { - listen 443 ssl; - server_name your-domain.com; - - ssl_certificate /path/to/cert.pem; - ssl_certificate_key /path/to/key.pem; - - location / { - proxy_pass http://127.0.0.1:8080; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } - - location /api/ { - proxy_pass http://127.0.0.1:5001/api/; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } -} -``` - -#### 方案B：使用内网穿透（开发测试环境） - -使用 ngrok、frp 等工具： - -```bash -# 使用 ngrok -ngrok http 8080 - -# 获取公网地址，如：https://xxxx.ngrok.io -``` - -### 步骤4：重启Docker服务 - -```bash -cd /path/to/baodanagent/deploy-package/baodanagent - -# 停止服务 -docker compose down - -# 重新构建（代码有改动时需要） -docker compose build baodanagent-api - -# 启动服务 -docker compose up -d - -# 查看日志，确认启动成功 -docker compose logs -f baodanagent-api -``` - -### 步骤5：在企微后台配置回调地址 - -1. 进入 **企业微信管理后台 → 应用管理 → 接收消息** -2. 点击 **设置接收消息服务器** -3. 填写配置： - - | 配置项 | 值 | - |--------|-----| - | URL | `https://your-domain.com/api/wecom/callback` | - | Token | 你在 `.env` 中设置的 `WECOM_TOKEN` | - | EncodingAESKey | 你在 `.env` 中设置的 `WECOM_AES_KEY` | - -4. 点击 **保存** - -## 四、验证配置 - -### 1. 检查服务是否正常运行 - -```bash -# 检查API服务 -curl http://localhost:5001/api/health - -# 检查前端 -curl http://localhost:8080 -``` - -### 2. 手动测试回调接口 - -```bash -# 测试GET验证接口 -curl "https://your-domain.com/api/wecom/callback?msg_signature=test×tamp=1234567890&nonce=test&echostr=test" - -# 应该返回：Invalid signature（说明服务正常，只是参数不对） -``` - -### 3. 查看Docker日志 - -```bash -docker compose logs -f baodanagent-api | grep -i wecom -``` - -## 五、常见问题 - -### 问题1：仍然提示"回调地址请求不通过" - -**排查步骤：** - -1. 检查URL是否正确（注意路径是 `/api/wecom/callback`，不是 `/wecom/callback`） -2. 检查防火墙是否开放了443端口 -3. 检查SSL证书是否有效 -4. 查看Docker日志：`docker compose logs baodanagent-api` - -### 问题2：返回"Invalid signature" - -**原因：** Token配置不一致 - -**解决：** 确保企微后台配置的Token与 `.env` 中的 `WECOM_TOKEN` 完全一致 - -### 问题3：返回"Invalid echostr" - -**原因：** AES密钥配置不一致 - -**解决：** 确保企微后台配置的EncodingAESKey与 `.env` 中的 `WECOM_AES_KEY` 完全一致 - -### 问题4：5秒内未返回success - -**原因：** 服务器响应太慢 - -**解决：** 检查服务器性能，优化网络延迟 - -## 六、完整配置示例 - -### .env 文件 - -```bash -# 数据库 -DB_PASSWORD=your_secure_password - -# JWT -JWT_SECRET=your_jwt_secret_key - -# 企微配置 -WECOM_CORP_ID=ww1234567890abcdef -WECOM_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 -WECOM_TOKEN=my_callback_token_2024 -WECOM_AES_KEY=abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG -``` - -### 企微后台配置 - -| 配置项 | 值 | -|--------|-----| -| URL | `https://example.com/api/wecom/callback` | -| Token | `my_callback_token_2024` | -| EncodingAESKey | `abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG` | - -## 七、安全建议 - -1. **Token和AES密钥**：使用随机生成的强字符串 -2. **HTTPS**：生产环境必须使用HTTPS -3. **IP白名单**：在企微后台配置IP白名单 -4. **日志监控**：定期检查回调日志，发现异常及时处理 diff --git a/docs/保险智能客服系统_客户验收单.md b/docs/保险智能客服系统_客户验收单.md index 90f1e2b..38b6397 100644 --- a/docs/保险智能客服系统_客户验收单.md +++ b/docs/保险智能客服系统_客户验收单.md @@ -303,10 +303,10 @@ | 2 | 需求文档 | `docs/保险智能客服系统_需求文档.md` | □ 是 □ 否 | | | 3 | API 接口文档 | `docs/保险智能客服系统_API接口文档.md` | □ 是 □ 否 | | | 4 | 测试用例 | `docs/保险智能客服系统_测试用例.md` | □ 是 □ 否 | | -| 5 | 部署指南 | `docs/部署指南.md`、`docs/快速部署指南.md`、`docs/服务器部署指南.md` | □ 是 □ 否 | | -| 6 | 企业微信接入指南 | `docs/企业微信接入指南.md`、`WECOM_CONFIG_GUIDE.md` | □ 是 □ 否 | | +| 5 | 部署指南 | `docs/部署指南.md`、`docs/部署文档_完整版.md`、`docs/宝塔面板部署指南.md` | □ 是 □ 否 | | +| 6 | 企业微信接入指南 | `docs/企业微信接入指南.md` | □ 是 □ 否 | | | 7 | API 调试示例 | `docs/API_curl示例.md` | □ 是 □ 否 | | -| 8 | 数据同步指南 | `docs/数据同步指南.md` | □ 是 □ 否 | | +| 8 | 快速启动指南 | `docs/快速启动指南.md` | □ 是 □ 否 | | | 9 | 源码交付包 | 后端、前端、部署脚本、文档 | □ 是 □ 否 | | | 10 | 部署账号/运维交接信息 | 另行线下交接 | □ 是 □ 否 □ 不适用 | 注意脱敏与权限回收 | diff --git a/docs/保险智能客服系统_文档规范.md b/docs/保险智能客服系统_文档规范.md index 5e50e84..b951f59 100644 --- a/docs/保险智能客服系统_文档规范.md +++ b/docs/保险智能客服系统_文档规范.md @@ -6,10 +6,10 @@ | 文档 | 位置 | 什么时候写 | 什么时候更新 | |------|------|-----------|-------------| -| 需求文档 | `docs/需求文档.md` | 开发前写完 | 需求变更时 | -| 接口文档 | `docs/接口文档.md` | 写后端接口前 | 接口变更时 | -| 数据库设计 | `docs/数据库设计.md` | 写后端前 | 表结构变更时 | -| 部署文档 | `docs/部署文档.md` | 第一次部署时 | 部署流程变化时 | +| 需求文档 | `docs/保险智能客服系统_需求文档.md` | 开发前写完 | 需求变更时 | +| 接口文档 | `docs/保险智能客服系统_API接口文档.md` | 写后端接口前 | 接口变更时 | +| 数据库设计 | `docs/保险智能客服系统_需求文档.md`（第六章） | 写后端前 | 表结构变更时 | +| 部署文档 | `docs/部署文档_完整版.md` | 第一次部署时 | 部署流程变化时 | | 变更日志 | `CHANGELOG.md` | 每次发版 | 每次发版 | --- @@ -47,17 +47,17 @@ | XXX 失败 | 提示用户 XXX | ``` -### 2.2 本项目的需求文档结构 +### 2.2 本项目的需求文档 -``` -docs/需求文档/ -├── M1-智能问答.md # 对话交互、回复展示、检索范围、反馈纠错 -├── M2-产品推荐方案.md # 信息录入、AI匹配、方案展示 -├── M3-知识库管理.md # 文档上传、状态监控、检索测试 -├── M4-企微机器人.md # 单聊、群聊 @触发、消息回调 -├── M5-用户与权限.md # 企微OAuth、角色权限 -└── M6-系统配置.md # LLM模型、Prompt管理 -``` +所有需求集中在 `docs/保险智能客服系统_需求文档.md` 一个文件中，按模块章节组织： + +- 第一章：智能问答（对话交互、回复展示、检索范围、反馈纠错） +- 第二章：产品推荐方案（信息录入、AI匹配、方案展示） +- 第三章：知识库管理（文档上传、状态监控、检索测试） +- 第四章：企微机器人（单聊、群聊 @触发、消息回调） +- 第五章：用户与权限（企微OAuth、角色权限） +- 第六章：数据库设计 +- 第七章：系统配置（LLM模型、Prompt管理） --- @@ -120,7 +120,7 @@ docs/需求文档/ ### 3.2 本项目的接口列表 -你的后端（FastAPI）只写这几个接口，不多不少： +你的后端（Flask）只写这几个接口，不多不少： | 编号 | 接口 | 说明 | |------|------|------| @@ -233,13 +233,13 @@ A: 原因是 XXX，解决方法是 XXX。 ### 5.2 需要写哪些部署文档 ``` -docs/部署文档/ -├── baodan-源码部署.md # BaoDan 源码部署全流程 -├── baodan-docker部署.md # Docker 部署全流程 -├── 后端部署.md # BaoDan Flask 后端部署 -├── 前端部署.md # Vue 前端构建与部署 -├── nginx配置.md # Nginx 反向代理配置 -└── 企微应用配置.md # 企微后台配置步骤 +docs/ +├── 快速启动指南.md # 本地开发一键启动 +├── 部署指南.md # BaoDan 源码集成指南 +├── 部署文档_完整版.md # 完整部署 + 架构图 + 环境变量 +├── 宝塔面板部署指南.md # 宝塔面板 Docker 部署 +├── 企业微信接入指南.md # 企微后台配置步骤 +└── 前端移动端适配指南.md # 移动端适配方案 ``` --- diff --git a/docs/前端开发文档.md b/docs/前端开发文档.md deleted file mode 100644 index 350cca5..0000000 --- a/docs/前端开发文档.md +++ /dev/null @@ -1,401 +0,0 @@ -# 保险智能客服系统 — 前端开发文档 - -> **文档版本**：V1.0 -> **更新日期**：2026-06-25 -> **技术栈**：Vue 3 + TypeScript + Element Plus + Vite - ---- - -## 一、项目结构 - -``` -frontend/ -├── src/ -│ ├── assets/ # 静态资源 -│ ├── components/ # 公共组件 -│ │ ├── ChatEmbed.vue # BaoDan 对话 iframe -│ │ ├── ChatFilters.vue # 险种/保司筛选器 -│ │ ├── ChatCopyButton.vue # 复制按钮 -│ │ ├── RecommendForm.vue # 推荐表单 -│ │ └── RecommendResult.vue # 推荐结果 -│ ├── composables/ # 组合式函数 -│ │ ├── useAuth.ts # 认证逻辑 -│ │ └── useDraft.ts # 草稿保存 -│ ├── constants/ # 常量定义 -│ │ └── index.ts # 访客页面白名单等 -│ ├── pages/ # 页面视图 -│ │ ├── admin/ # 管理后台页面 -│ │ ├── ChatPage.vue # 对话页面 -│ │ ├── LoginPage.vue # 登录页面 -│ │ ├── RecommendPage.vue # 推荐页面 -│ │ └── RecommendHistory.vue # 历史方案 -│ ├── router/ # 路由配置 -│ │ └── index.ts -│ ├── types/ # TypeScript 类型 -│ │ └── index.ts -│ ├── utils/ # 工具函数 -│ │ └── api.ts # axios 封装 -│ ├── App.vue # 主布局 -│ └── main.ts # 入口文件 -├── package.json -└── vite.config.ts -``` - ---- - -## 二、待开发功能 - -### 2.1 产品推荐联调 - -**目标**：联调 RecommendPage 与后端 API - -**修改文件**：`src/pages/RecommendPage.vue` - -**当前代码**： -```typescript -async function onSubmit(formData: RecommendRequest) { - loading.value = true - try { - const submitRes = await api.post('/recommend/generate', formData) - const taskId = submitRes.data.task_id - // ... 轮询逻辑 - } catch { - // 错误已由 api 拦截器处理 - } -} -``` - -**需要修改**： -1. 确认后端返回格式 -2. 适配轮询逻辑 -3. 处理超时情况 - ---- - -### 2.2 推荐结果适配 - -**目标**：适配后端返回的方案格式 - -**修改文件**：`src/components/RecommendResult.vue` - -**后端返回格式**： -```json -{ - "status": "done", - "proposal": { - "customer_name": "张三", - "plans": [ - { - "name": "基础方案", - "total_premium": 12000, - "items": [ - { - "product_name": "XX重疾险", - "coverage_amount": 300000, - "annual_premium": 8000, - "recommend_reason": "性价比高" - } - ], - "summary": "适合预算有限的客户" - } - ], - "disclaimer": "以上方案仅供参考" - } -} -``` - -**需要修改**： -1. 适配 plans 数组结构 -2. 渲染产品表格 -3. 显示总保费 - ---- - -### 2.3 用户批量导入 - -**目标**：添加 Excel 批量导入功能 - -**修改文件**：`src/pages/admin/UsersPage.vue` - -**添加内容**： -```vue - - - 批量导入 - -``` - -**添加逻辑**： -```typescript -const uploadHeaders = { - Authorization: `Bearer ${localStorage.getItem('token')}` -} - -function onImportSuccess(response: any) { - if (response.code === 0) { - ElMessage.success('导入成功') - loadData() - } else { - ElMessage.error(response.message || '导入失败') - } -} - -function onImportError() { - ElMessage.error('导入失败') -} -``` - ---- - -## 三、类型定义 - -### 3.1 推荐相关类型 - -**文件**：`src/types/index.ts` - -```typescript -/** 推荐请求参数 */ -export interface RecommendRequest { - customer_name: string - customer_age: number - customer_gender: 'male' | 'female' - health_status: '健康' | '有既往病史' | '慢性病' | '重大疾病史' - occupation: string - annual_income: number - monthly_budget: number - insurance_types: string[] - coverage_amount: number - coverage_period: string - existing_policies?: ExistingPolicy[] -} - -/** 已有保单 */ -export interface ExistingPolicy { - product_name: string - insurance_type: string - coverage_amount: number - annual_premium: number -} - -/** 推荐方案 */ -export interface RecommendProposal { - customer_name: string - plans: InsurancePlan[] - disclaimer: string -} - -/** 保险方案 */ -export interface InsurancePlan { - name: string - total_premium: number - items: InsuranceItem[] - summary: string -} - -/** 保险产品 */ -export interface InsuranceItem { - product_name: string - coverage_amount: number - annual_premium: number - recommend_reason: string -} - -/** 推荐记录 */ -export interface RecommendRecord { - id: string - customer_name: string - insurance_types: string[] - status: 'pending' | 'processing' | 'done' | 'failed' - created_at: string - completed_at?: string -} -``` - ---- - -## 四、API 调用规范 - -### 4.1 请求格式 - -```typescript -import api from '@/utils/api' - -// GET 请求 -const res = await api.get('/admin/users', { params: { page: 1 } }) - -// POST 请求 -const res = await api.post('/recommend/generate', formData) - -// PUT 请求 -const res = await api.put(`/admin/users/${id}`, userData) - -// DELETE 请求 -const res = await api.delete(`/admin/users/${id}`) -``` - -### 4.2 响应处理 - -```typescript -// axios 拦截器已处理 code !== 0 的情况 -// 这里只需要处理成功情况 -try { - const res = await api.get('/admin/users') - // res.data = { items: [...], total: 100 } - users.value = res.data?.items || [] -} catch (error) { - // 错误已由拦截器显示 ElMessage -} -``` - -### 4.3 访客页面 - -```typescript -import { isGuestPage } from '@/constants' - -// 访客页面不发送 token -if (!isGuestPage(window.location.pathname)) { - const token = localStorage.getItem('token') - if (token) { - config.headers.Authorization = `Bearer ${token}` - } -} -``` - ---- - -## 五、组件开发规范 - -### 5.1 页面组件 - -```vue - - - - - -``` - -### 5.2 表单组件 - -```vue - - - -``` - ---- - -## 六、样式规范 - -### 6.1 页面容器 - -```css -.page-container { - padding: 20px; - height: 100%; - overflow: auto; - box-sizing: border-box; -} -``` - -### 6.2 卡片样式 - -```css -.page-card { - border-radius: 12px; - box-shadow: 0 2px 12px rgba(0, 0, 0, 0.05); -} -``` - -### 6.3 表格样式 - -```css -:deep(.el-table th) { - background: #fafafa !important; - color: #606266; - font-weight: 600; -} -``` - ---- - -## 七、测试清单 - -| # | 页面 | 测试项 | 验证标准 | -|---|------|--------|----------| -| 1 | LoginPage | 账密登录 | 输入正确账密 → 跳转 /chat | -| 2 | LoginPage | 表单校验 | 空表单提交 → 显示错误提示 | -| 3 | ChatPage | 对话功能 | 发送消息 → 收到 AI 回答 | -| 4 | ChatPage | 险种筛选 | 切换险种 → 对话正常 | -| 5 | RecommendPage | 生成方案 | 填写表单 → 显示 3 套方案 | -| 6 | RecommendPage | 导出 | 点击导出 → 下载文件 | -| 7 | UsersPage | 用户列表 | 显示用户数据 | -| 8 | UsersPage | 新增用户 | 填写表单 → 用户增加 | -| 9 | UsersPage | 批量导入 | 上传 Excel → 用户增加 | -| 10 | StatsPage | 统计数据 | 显示图表和数据 | diff --git a/docs/开发指南.md b/docs/开发指南.md deleted file mode 100644 index a66e267..0000000 --- a/docs/开发指南.md +++ /dev/null @@ -1,255 +0,0 @@ -# 保险智能客服系统 — 开发指南 - -> **文档版本**：V1.0 -> **更新日期**：2026-06-25 -> **项目状态**：完成 64%，产品推荐功能待实现 - ---- - -## 一、文档索引 - -| 文档 | 说明 | 链接 | -|------|------|------| -| 后续开发计划 | 完整的开发计划和时间表 | [后续开发计划.md](后续开发计划.md) | -| 前端开发文档 | 前端开发规范和待开发功能 | [前端开发文档.md](前端开发文档.md) | -| 后端开发文档 | 后端开发规范和待开发功能 | [后端开发文档.md](后端开发文档.md) | -| 需求文档 | 完整的需求规格说明 | [保险智能客服系统_需求文档.md](保险智能客服系统_需求文档.md) | -| API 接口文档 | 所有 API 接口定义 | [保险智能客服系统_API接口文档.md](保险智能客服系统_API接口文档.md) | -| 编码规范 | 编码标准和规范 | [保险智能客服系统_编码规范.md](保险智能客服系统_编码规范.md) | -| 测试用例 | 功能测试用例 | [保险智能客服系统_测试用例.md](保险智能客服系统_测试用例.md) | - ---- - -## 二、当前状态 - -### 2.1 已完成功能（64%） - -``` -✅ 认证系统（企微 OAuth + 账密登录） -✅ 对话功能（iframe 嵌入 BaoDan） -✅ 用户管理（CRUD + 角色权限） -✅ 知识库管理（文档上传/列表/删除） -✅ 数据统计（概览/趋势/知识库健康度） -✅ 系统管理（模板/通知/分组/Prompt/日志） -✅ 导出功能（PDF/Word） -``` - -### 2.2 未完成功能（36%） - -``` -❌ 产品推荐（Workflow 配置 + API 联调） -❌ 批量导入用户 -❌ 数据权限过滤 -❌ 文档编号自动生成 -❌ 功能测试 -``` - ---- - -## 三、快速开始 - -### 3.1 环境要求 - -- Docker Desktop -- Node.js 18+ (前端开发) -- Python 3.12 (后端开发) - -### 3.2 启动服务 - -```bash -# 1. 进入项目目录 -cd D:\work\code\python\coding\baodanagent - -# 2. 启动后端服务 -docker compose -f docker-compose.dify.yml up -d - -# 3. 启动前端服务（开发模式） -cd frontend -pnpm install -pnpm dev - -# 4. 访问系统 -# 前端：http://localhost:9080 -# 后端：http://localhost:5001 -# Dify：http://localhost:3000 -``` - -### 3.3 默认账户 - -| 账户 | 密码 | 角色 | -|------|------|------| -| admin | admin123456 | 超级管理员 | - ---- - -## 四、开发流程 - -### 4.1 后端开发 - -1. **修改代码**：编辑 `api/insurance/` 下的文件 -2. **重新构建**： - ```bash - docker compose -f docker-compose.dify.yml build baodan-api - docker compose -f docker-compose.dify.yml up -d baodan-api - ``` -3. **测试 API**：使用 curl 或 Postman 测试 - -### 4.2 前端开发 - -1. **修改代码**：编辑 `frontend/src/` 下的文件 -2. **开发模式**： - ```bash - cd frontend - pnpm dev - ``` -3. **构建部署**： - ```bash - pnpm build - docker compose -f docker-compose.frontend.yml build - docker compose -f docker-compose.frontend.yml up -d - ``` - -### 4.3 数据库变更 - -1. **编写 SQL**：在 `deploy/sql/` 下创建迁移文件 -2. **执行迁移**： - ```bash - docker exec -i baodanagent-db-1 psql -U postgres -d baodan < deploy/sql/migration.sql - ``` - ---- - -## 五、核心任务 - -### 5.1 产品推荐功能（优先级最高） - -**目标**：实现客户信息 → 生成 3 套推荐方案 - -**步骤**： - -1. **配置 Workflow**（0.5 天） - - 在 Dify 后台创建 Workflow 应用 - - 配置 6 个节点 - - 获取 API Key - -2. **实现后端 API**（0.5 天） - - 完善 generate/status/export/share API - - 封装 Workflow 调用 - -3. **前端联调**（0.5 天） - - 适配后端返回格式 - - 测试完整流程 - -**详细内容**：见 [后续开发计划.md](后续开发计划.md) Phase 2.5 和 Phase 3 - ---- - -### 5.2 批量导入用户（优先级中等） - -**目标**：支持 Excel 批量导入用户 - -**步骤**： - -1. **后端 API**（0.2 天） - - 实现 POST /admin/users/batch-import - - 解析 Excel 文件 - -2. **前端页面**（0.1 天） - - UsersPage 添加导入按钮 - - 上传组件 - -**详细内容**：见 [后端开发文档.md](后端开发文档.md) 2.3 节 - ---- - -### 5.3 数据权限过滤（优先级中等） - -**目标**：销售只看自己的数据，主管看本组数据 - -**步骤**： - -1. **实现过滤逻辑**（0.3 天） - - 在查询接口中注入权限条件 - - 使用 get_data_scope() - -2. **测试验证**（0.2 天） - - 测试不同角色的数据范围 - -**详细内容**：见 [后端开发文档.md](后端开发文档.md) 2.4 节 - ---- - -## 六、常见问题 - -### Q1: 如何配置 Workflow？ - -A: 在 Dify 后台（http://localhost:3000）创建 Workflow 应用，参考 [后续开发计划.md](后续开发计划.md) Phase 2.5 的节点设计。 - -### Q2: 如何更新 Workflow API Key？ - -A: 修改 `docker-compose.dify.yml` 中的 `BAODAN_WORKFLOW_API_KEY`，然后重启服务： -```bash -docker compose -f docker-compose.dify.yml up -d baodan-api -``` - -### Q3: 如何添加新的 API 接口？ - -A: 在对应的 `routes.py` 中添加路由，参考 [后端开发文档.md](后端开发文档.md) 的 API 接口清单。 - -### Q4: 如何添加新的前端页面？ - -A: 在 `frontend/src/pages/` 下创建页面组件，在 `router/index.ts` 中添加路由，参考 [前端开发文档.md](前端开发文档.md) 的组件开发规范。 - -### Q5: 如何执行数据库迁移？ - -A: 在 `deploy/sql/` 下创建迁移文件，执行： -```bash -docker exec -i baodanagent-db-1 psql -U postgres -d baodan < deploy/sql/migration.sql -``` - ---- - -## 七、技术栈 - -### 后端 - -| 技术 | 版本 | 用途 | -|------|------|------| -| Python | 3.12 | 编程语言 | -| Flask | 3.x | Web 框架 | -| SQLAlchemy | 2.x | ORM | -| PostgreSQL | 15 | 数据库 | -| Redis | 7.x | 缓存 | -| JWT | - | 认证 | -| bcrypt | 4.x | 密码哈希 | - -### 前端 - -| 技术 | 版本 | 用途 | -|------|------|------| -| Vue | 3.x | 前端框架 | -| TypeScript | 5.x | 类型系统 | -| Vite | 5.x | 构建工具 | -| Element Plus | 2.x | UI 组件库 | -| Axios | 1.x | HTTP 客户端 | -| Vue Router | 4.x | 路由管理 | - -### 基础设施 - -| 技术 | 版本 | 用途 | -|------|------|------| -| Docker | - | 容器化 | -| Docker Compose | - | 服务编排 | -| Nginx | - | 反向代理 | -| Dify/BaoDan | 1.14.2 | AI 平台 | - ---- - -## 八、联系方式 - -如有问题，请联系项目负责人或查阅项目文档。 - ---- - -**最后更新**：2026-06-25 -**文档维护**：开发团队 diff --git a/docs/开发计划.md b/docs/开发计划.md deleted file mode 100644 index c0524e0..0000000 --- a/docs/开发计划.md +++ /dev/null @@ -1,1110 +0,0 @@ -# 保险智能客服系统 — 完整开发计划 - -> **基于**：需求文档 V1.0 + API 文档 V1.1 + 前端开发计划 + BaoDan 源码分析 -> **当前状态**：后端空壳（49 行注释）+ 前端骨架（743 行）+ SQL 建表（112 行） -> **预计工期**：10 个工作日（一人全栈） -> **核心原则**：BaoDan 已有的绝不重复造轮子 - ---- - -## 零、已确认不需要自研的功能（用 BaoDan 原生） - -| 功能 | BaoDan 提供的 | 对应需求编号 | -|------|-----------|:---:| -| LLM 模型配置 CRUD | `ModelProviderCredentialApi` 后台可视化配置 | 6.1 / A6.1.1-A6.1.2 | -| Prompt 编辑/版本/测试 | App 配置页 + Annotation 系统 | 6.2 / A6.1.3-A6.1.4 | -| 对话日志查看/筛选 | BaoDan 后台 /logs 页面 | 4.1.1-4.1.2 | -| 负反馈管理 | `MessageFeedbackExportApi` + Annotation | 4.1.4 | -| 点赞/点踩 | BaoDan WebApp 内置 | 1.4.1 | -| 推荐追问 | `MessageSuggestedQuestionApi` | 1.2.4 / A2.2.2 | -| 来源引用标注 | BaoDan RAG 自动返回 sources | 1.2.3 | -| 会话标题自动命名 | BaoDan 自动命名 | 1.1.5 | -| 知识库测试入口（hit testing） | `HitTestingApi` | 3.4.1 | -| FAQ 手动条目 | BaoDan Annotation Reply = FAQ | 3.4.3 | -| 文档上传/列表/删除/重试 | BaoDan `/datasets` 后台 | 3.1.1-3.1.2 / 3.1.5 / 3.2.x | -| Markdown 渲染 | BaoDan WebApp 内置 | 1.2.1 | -| 多轮对话上下文 | BaoDan conversation 机制 | 1.1.3 | -| 流式输出 | BaoDan WebApp iframe | 1.1.2 | - -**以上功能不需要写后端接口，不需要写前端页面。** - ---- - -## 一、后端自研接口清单（25 个，对齐 API 文档 V1.1） - -### 1.1 认证鉴权（4 个） - -| # | 方法 | URL | 说明 | -|:---:|:---:|-----|------| -| 1 | POST | /api/auth/wework-login | 企微 OAuth 登录 → JWT | -| 2 | POST | /api/auth/password-login | 账密登录 → JWT | -| 3 | POST | /api/auth/refresh-token | 刷新 Token | -| 4 | POST | /api/auth/logout | 退出（Token 黑名单） | - -### 1.2 智能问答（5 个） - -| # | 方法 | URL | 说明 | -|:---:|:---:|-----|------| -| 5 | POST | /api/chat/message | 发送消息（SSE 流式，调 BaoDan Chat API） | -| 6 | GET | /api/chat/sessions | 会话列表（封装 BaoDan API） | -| 7 | POST | /api/chat/sessions | 创建会话 | -| 8 | DELETE | /api/chat/sessions/{id} | 删除会话 | -| 9 | GET | /api/chat/sessions/{id}/messages | 消息记录（含来源引用） | - -### 1.3 反馈 + 检索（2 个） - -| # | 方法 | URL | 说明 | -|:---:|:---:|-----|------| -| 10 | POST | /api/chat/messages/{id}/feedback | 提交反馈（封装 BaoDan API） | -| 11 | POST | /api/retrieval/search | 向量检索（封装 BaoDan API） | - -### 1.4 产品推荐（4 个） - -| # | 方法 | URL | 说明 | -|:---:|:---:|-----|------| -| 12 | POST | /api/recommend/generate | 生成方案（调 BaoDan Workflow） | -| 13 | GET | /api/recommend/generate/{task_id} | 查询任务状态 | -| 14 | POST | /api/recommend/{id}/export | 导出 PDF/PPT/Word | -| 15 | POST | /api/recommend/{id}/share | 生成分享链接 | - -### 1.5 知识库增强（6 个） - -| # | 方法 | URL | 说明 | -|:---:|:---:|-----|------| -| 16 | POST | /api/kb/documents/upload | 上传文档（附标签，调 BaoDan API） | -| 17 | GET | /api/kb/documents | 文档列表（带自定义标签） | -| 18 | GET | /api/kb/documents/{id}/status | 文档处理状态 | -| 19 | PATCH | /api/kb/documents/{id} | 更新元数据（编号/标签） | -| 20 | DELETE | /api/kb/documents/{id} | 删除文档 | -| 21-24 | * | /api/kb/datasources/* | 保司数据源 CRUD + 同步 + 日志（4 个） | - -### 1.6 用户权限（3 个） - -| # | 方法 | URL | 说明 | -|:---:|:---:|-----|------| -| 25 | CRUD | /api/admin/users | 用户管理（含停用吊销 Token） | -| 26 | POST | /api/admin/users/batch-import | 批量导入 | -| 27 | CRUD | /api/admin/roles | 角色管理 | - -### 1.7 系统日志 + 统计（4 个） - -| # | 方法 | URL | 说明 | -|:---:|:---:|-----|------| -| 28 | GET | /api/admin/logs/system | 系统操作日志 | -| 29 | GET | /api/stats/overview | 使用概览 | -| 30 | GET | /api/stats/trend | 趋势数据 | -| 31 | GET | /api/stats/kb-health | 知识库健康度 | - -### 1.8 企微回调（4 个） - -| # | 方法 | URL | 说明 | -|:---:|:---:|-----|------| -| 32 | GET | /api/wecom/callback | 企微 URL 验证 | -| 33 | POST | /api/wecom/callback | 企微消息接收 | -| 34 | GET | /api/wecom/oauth | OAuth 入口 | -| 35 | GET | /api/wecom/oauth/callback | OAuth 回调 | - ---- - -## 二、前端自研页面清单 - -### 2.1 用户端（5 个页面 + 5 个组件） - -| 页面 | 路径 | 说明 | 对应需求 | -|------|------|------|---------| -| LoginPage.vue | /login | 企微 OAuth + 账密登录 | 无（全新） | -| ChatPage.vue | /chat | iframe 嵌入 BaoDan WebApp | M1 | -| ChatFilters.vue | — | 险种/保司筛选器组件 | 1.3.1-1.3.3 | -| ChatCopyButton.vue | — | 复制回答按钮组件 | 1.2.5 | -| RecommendPage.vue | /recommend | 推荐方案表单 + 结果 | M2.1-M2.2 | -| RecommendForm.vue | — | 客户信息表单组件 | 2.1.1-2.1.6 | -| RecommendResult.vue | — | 方案展示组件 | 2.2-2.3 | -| RecommendHistory.vue | /recommend/history | 历史方案列表 | 2.5.1-2.5.4 | -| RecommendDetail.vue | /recommend/detail/:id | 方案详情 + 导出 | 2.3-2.4 | - -### 2.2 管理端（6 个页面） - -| 页面 | 路径 | 说明 | 对应需求 | -|------|------|------|---------| -| DashboardPage.vue | /admin | 管理后台首页（跳转入口） | — | -| UsersPage.vue | /admin/users | 用户 CRUD + 批量导入 | 5.1-5.2 | -| PermissionsPage.vue | /admin/roles | 角色权限配置 | 5.2 | -| StatsPage.vue | /admin/stats | 数据统计仪表盘 | M7 | -| KBManagePage.vue | /admin/kb | 文档管理 + 标签 + 编号 | 3.1.3-3.1.4 | -| DataSourcePage.vue | /admin/datasource | 保司数据源配置 | 3.3 | - -> 注：知识库主界面、对话日志、Prompt 管理、模型配置 → 跳转 BaoDan 后台，不自研。 - ---- - -## 三、数据库表（3 张自研表，已建好） - -| 表名 | 用途 | 当前状态 | -|------|------|:---:| -| wecom_user_mapping | 企微用户 ↔ BaoDan 用户映射 | 已建 | -| recommendation_records | 推荐方案记录 | 已建 | -| system_operation_logs | 系统操作审计日志 | 已建 | - -可能需要追加的表： - -| 表名 | 用途 | 何时建 | -|------|------|--------| -| document_metadata | 文档编号/标签/险种/保司 | Phase 7 KB 增强时 | -| datasource_configs | 保司 API 数据源配置 | Phase 7 KB 增强时 | -| datasource_sync_logs | 同步日志 | Phase 7 KB 增强时 | -| share_tokens | 方案分享链接 Token | Phase 3 产品推荐时 | -| token_blacklist | JWT 黑名单（或用 Redis） | Phase 1 认证时 | - ---- - -## 四、分阶段开发计划 - ---- - -### Phase 0：项目脚手架（0.5 天） - -**目标**：BaoDan + 自研代码能跑起来，路由能通。 - -#### 后端任务 - -**0.1 创建 insurance/ 模块骨架** - -``` -api/insurance/ -├── __init__.py # 空 -├── config.py # 配置常量（JWT Secret、企微配置等） -├── utils/ -│ ├── __init__.py -│ ├── response.py # 统一响应封装：success_response() / error_response() -│ ├── auth.py # JWT 签发/校验/装饰器 -│ └── db.py # 复用 BaoDan 的 db：from extensions.ext_database import db -├── wecom/ -│ ├── __init__.py -│ ├── routes.py # Blueprint: wecom_bp -│ ├── wecom_bot.py # 消息回调处理 -│ ├── wecom_oauth.py # OAuth 登录 -│ └── wecom_api.py # 企微 API 封装（发消息/获取 Token） -├── recommend/ -│ ├── __init__.py -│ ├── routes.py # Blueprint: recommend_bp -│ └── workflow_helper.py # BaoDan Workflow 调用封装 -├── permissions/ -│ ├── __init__.py -│ ├── routes.py # Blueprint: permissions_bp -│ └── middleware.py # 权限校验中间件 -├── stats/ -│ ├── __init__.py -│ └── routes.py # Blueprint: stats_bp -└── db/ - ├── __init__.py - ├── models.py # SQLAlchemy 模型（3 张自研表） - └── init.sql # 建表脚本（已有） -``` - -每个 `routes.py` 先放一个 health check 占位接口。 - -**0.2 注册路由到 BaoDan** - -修改 `baodan-main/api/app_factory.py`（或 `main.py`），在 app 创建后加： - -```python -try: - from insurance.utils.response import InsuranceResponse - from insurance.wecom.routes import wecom_bp - from insurance.recommend.routes import recommend_bp - from insurance.permissions.routes import permissions_bp - from insurance.stats.routes import stats_bp - app.register_blueprint(wecom_bp, url_prefix='/api/wecom') - app.register_blueprint(recommend_bp, url_prefix='/api/recommend') - app.register_blueprint(permissions_bp, url_prefix='/api/admin') - app.register_blueprint(stats_bp, url_prefix='/api/stats') -except ImportError: - pass -``` - -**0.3 修改 BaoDan 前端 iframe 配置** - -`web/.env.local` 添加： -``` -NEXT_PUBLIC_ALLOW_EMBED=true -``` - -#### 前端任务 - -**0.4 确认前端项目能启动** - -已有 `package.json`、`router`、`App.vue`。安装依赖后 `pnpm dev` 验证。 - -**0.5 统一响应拦截器** - -确保 `src/utils/api.ts` 的 axios 拦截器处理 `code !== 0` 的情况。 - -#### 验证标准 - -```bash -# 后端 -curl http://localhost:5001/api/health # 返回 {"status":"ok"} -curl http://localhost:5001/api/auth/password-login # 返回参数错误（不是 404） - -# 前端 -pnpm dev → 浏览器打开 localhost:3000 → 显示登录页 -``` - ---- - -### Phase 1：认证系统（1 天） - -**目标**：能登录、能鉴权、Token 能刷新。 - -#### 后端（0.5 天） - -**1.1 config.py — 配置项** - -```python -JWT_SECRET = os.getenv('JWT_SECRET', 'your-secret-key') -JWT_EXPIRE_HOURS = 2 -REDIS_TOKEN_PREFIX = 'token:blacklist:' -WECOM_CORP_ID = os.getenv('WECOM_CORP_ID', '') -WECOM_AGENT_SECRET = os.getenv('WECOM_AGENT_SECRET', '') -WECOM_TOKEN = os.getenv('WECOM_TOKEN', '') -WECOM_AES_KEY = os.getenv('WECOM_AES_KEY', '') -``` - -**1.2 utils/auth.py — JWT 工具** - -- `generate_token(user_id, username, role, department)` → 签发 JWT -- `decode_token(token)` → 解码 + 校验有效期 -- `login_required` 装饰器 → 从 Header 提取 JWT → 解码 → 注入 current_user -- `admin_required` 装饰器 → 额外校验 role in [super_admin, admin] - -**1.3 utils/response.py — 统一响应** - -```python -def success(data=None, message="success"): - return {"code": 0, "message": message, "data": data} - -def error(code, message): - return {"code": code, "message": message, "data": None} -``` - -**1.4 POST /api/auth/password-login** - -``` -输入：{ username, password } -处理： - 1. 参数校验（3-64字符，8-128字符） - 2. 查 wecom_user_mapping 表找用户 - 3. bcrypt 校验密码（需在用户表加 password_hash 字段） - 4. 签发 JWT - 5. 记录 system_operation_logs（action=login） -输出：{ token, expires_in, user } -``` - -> 注意：wecom_user_mapping 表需要加 `password_hash` 字段（ALTER TABLE）。 - -**1.5 POST /api/auth/refresh-token** - -``` -处理： - 1. 校验旧 Token 有效性（未过期、未在黑名单） - 2. 签发新 Token - 3. 旧 Token 加入 Redis 黑名单（EX 7200） -输出：{ token, expires_in } -``` - -**1.6 POST /api/auth/logout** - -``` -处理： - 1. 当前 Token 加入 Redis 黑名单 - 2. 记录操作日志 -输出：{ code: 0 } -``` - -**1.7 POST /api/auth/wework-login** - -``` -输入：{ code, state } -处理： - 1. 用 code 调企微 gettoken API → 拿 access_token - 2. 用 access_token + code 调企微 auth/get_user_info → 拿 userid/name/department - 3. 查/建 wecom_user_mapping 记录 - 4. 签发 JWT -输出：{ token, expires_in, user } -``` - -#### 前端（0.5 天） - -**1.8 LoginPage.vue** - -- 企微登录按钮 → `window.location.href = '/api/wecom/oauth'` -- 账密登录表单 → POST /api/auth/password-login → 存 token → 跳 /chat -- 表单校验：用户名必填，密码必填 - -**1.9 路由守卫** - -- `router.beforeEach` 检查 `localStorage.token` -- 无 token → 跳 /login - -**1.10 Token 自动刷新** - -- api.ts 拦截器：响应 401 → 尝试 refresh-token → 成功则重试原请求 → 失败跳登录页 - -#### 验证标准 - -```bash -# 后端 -curl -X POST http://localhost:5001/api/auth/password-login \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"test1234"}' -# → 返回 JWT token - -curl -H "Authorization: Bearer " http://localhost:5001/api/auth/refresh-token -# → 返回新 token - -curl -H "Authorization: Bearer " http://localhost:5001/api/auth/refresh-token -# → 旧 token 已失效 -``` - ---- - -### Phase 2：对话页面（1 天） - -**目标**：用户能在 iframe 中跟 BaoDan 对话，筛选器可用。 - -#### 后端（0.5 天） - -**2.1 POST /api/chat/message（SSE 流式）** - -这是核心接口，封装 BaoDan Chat API： - -``` -输入：{ session_id, message, filters } -处理： - 1. JWT 鉴权 - 2. 参数校验 - 3. 根据 filters.险种 选择对应的 BaoDan App（不同险种不同知识库） - - 无险种 → 全库 App - - 重疾险 → 重疾险专用 App - - 以此类推 - 4. 调 BaoDan Chat API（blocking 模式）： - POST http://localhost:5001/v1/chat-messages - Headers: Authorization: Bearer app-xxxxxxxx - Body: { query, user, conversation_id, response_mode: "blocking" } - 5. 解析 BaoDan 响应 → 提取 answer + retriever_resources - 6. 返回 SSE 流式数据 -输出（SSE）： - data: {"type":"source","data":{...}} - data: {"type":"delta","data":"根据"} - data: {"type":"done","data":{"message_id":"...","conversation_id":"..."}} -``` - -> 关键点：BaoDan 本身已有 SSE，我们可以直接用 blocking 模式拿到完整回答后转 SSE，或用 streaming 模式透传。先做 blocking 模式（简单），后续优化为 streaming。 - -**2.2 GET /api/chat/sessions** - -``` -处理： - 1. 调 BaoDan API: GET /v1/conversations?user={user_id}&page=1&limit=20 - 2. 转换格式为 API 文档定义的结构 -输出：{ total, items: [{ id, title, created_at, updated_at, message_count }] } -``` - -**2.3 POST /api/chat/sessions** - -``` -处理：调 BaoDan API 创建空会话（或前端直接新建） -``` - -**2.4 DELETE /api/chat/sessions/{id}** - -``` -处理：调 BaoDan API 删除会话 -``` - -**2.5 GET /api/chat/sessions/{id}/messages** - -``` -处理：调 BaoDan API 获取消息列表 → 转换格式 -``` - -#### 前端（0.5 天） - -**2.6 ChatPage.vue** - -``` -结构： - ┌─────────────────────────────┐ - │ ChatFilters（筛选器） │ - ├─────────────────────────────┤ - │ │ - │ iframe（BaoDan WebApp） │ - │ src="/baodan/chat/{app_id}" │ - │ │ - ├─────────────────────────────┤ - │ ChatCopyButton + Suggestions │ - └─────────────────────────────┘ -``` - -- ChatEmbed 组件：iframe 加载 BaoDan WebApp -- ChatFilters：险种下拉（7 种）+ 保司下拉（动态加载） -- 选择险种后切换 iframe src 到对应 BaoDan App - -**2.7 App.vue 侧边栏** - -``` -左侧导航： - 智能问答 → /chat - 产品推荐 → /recommend - 历史方案 → /recommend/history - ────────（管理员以下才显示） - 管理后台 → /admin - ──────── -``` - -- 根据用户 role 控制显示哪些菜单 -- 顶部栏：页面标题 + 用户名 + 退出 - -#### 验证标准 - -```bash -# 浏览器 -1. 登录 → 自动跳 /chat -2. iframe 加载出 BaoDan 对话界面 -3. 筛选器下拉选择"重疾险" -4. 在 iframe 中提问 → BaoDan 回答 -5. 侧边栏点击"产品推荐" → 跳转正常 -``` - ---- - -### Phase 3：产品推荐（2 天）— 最大自研模块 - -**目标**：填写客户信息 → 生成方案 → 查看结果 → 导出。 - -#### 后端（1 天） - -**3.1 数据模型扩展 — recommendation_records** - -确认表结构满足需求，补充 `share_token` 和 `share_expire_at` 字段。 - -**3.2 POST /api/recommend/generate** - -``` -输入：{ customer, insurance_types, coverage_amount, coverage_period, existing_policies } -处理： - 1. JWT 鉴权 - 2. 参数校验（年龄 1-150、性别 male/female、险种至少 1 项等，见需求文档 13.3 节） - 3. INSERT recommendation_records（status=pending） - 4. 异步调 BaoDan Workflow API： - POST http://localhost:5001/v1/workflows/run - Headers: Authorization: Bearer app-yyyyyyyyyyyy - Body: { inputs: { age, gender, insurance_types, ... }, response_mode: "blocking", user } - 5. 解析 Workflow 输出 → JSON 格式化为 3 套方案（基础/均衡/全面） - 6. UPDATE recommendation_records（status=done, generated_plan=...） - 7. 记录操作日志 -输出：{ task_id, status } -``` - -> 关键：Workflow 返回的是 Markdown 格式的方案文本，需要在 workflow_helper.py 中解析为结构化 JSON。 - -**3.3 workflow_helper.py — BaoDan Workflow 调用封装** - -```python -def call_recommendation_workflow(customer_info, insurance_types, coverage_amount, coverage_period): - """ - 调 BaoDan Workflow API 生成推荐方案 - 返回: { plans: [{ name, total_premium, items: [...], summary }] } - """ - # 1. 构造 inputs - # 2. POST /v1/workflows/run - # 3. 解析 Markdown 输出 → 结构化 JSON - # 4. 失败处理（超时 120s、Workflow 错误） -``` - -**3.4 GET /api/recommend/generate/{task_id}** - -``` -处理：查 recommendation_records 表，返回 status + proposal -``` - -**3.5 POST /api/recommend/{id}/export** - -``` -输入：{ format: "pdf" | "pptx" | "docx" } -处理： - 1. 查推荐记录 - 2. 根据 format 调对应生成器： - - docx: python-docx（先做，最简单） - - pdf: reportlab 或 weasyprint - - pptx: python-pptx - 3. 生成文件 → 保存到 /tmp/exports/ 或 OSS - 4. 返回下载链接（带临时 token，30 分钟有效） -输出：{ download_url, expire_at } -``` - -**3.6 POST /api/recommend/{id}/share** - -``` -处理： - 1. 生成随机 token - 2. 存 share_tokens 表（含过期时间） -输出：{ share_url, expire_at } -``` - -#### 前端（1 天） - -**3.7 RecommendForm.vue — 表单组件** - -```vue -结构： - 基础信息：姓名 / 年龄 / 性别（radio）/ 健康状况（select）/ 职业 - 收入预算：年收入（万）/ 月预算（元） - 关注险种：checkbox group（寿险/重疾险/医疗险/意外险/年金险/储蓄险） - 保障需求：保额（slider + input）/ 保障期限（select） - 已有保单：可选折叠区域，动态添加 - [生成方案] 按钮 - -验证规则（见需求文档 13.3 节 + 14 节）： - - 年龄：必填，整数 1-150 - - 性别：必选 - - 职业：必填，1-64 字符 - - 月预算：必填，>0 - - 险种：至少选 1 项 - - 保额：>=1 万 - - 保障期限：必选 - -草稿保存： - - useDraft composable → 自动存 localStorage - - 提交成功后清除草稿 -``` - -**3.8 RecommendPage.vue — 主页面** - -``` -结构： - RecommendForm（表单） - ↓ 提交后 - loading 状态（轮询中...） - ↓ 完成后 - RecommendResult（结果展示） -``` - -轮询逻辑： -```javascript -// 提交表单 → 拿到 task_id -// setInterval(2s) 轮询 GET /api/recommend/generate/{task_id} -// status=processing → 继续 -// status=done → 展示方案 -// status=failed → 显示错误 -// 超过 60 次轮询 → 超时提示 -``` - -**3.9 RecommendResult.vue — 结果展示** - -``` -结构： - 三套方案（Collapse 折叠面板）： - 基础方案 | 均衡方案 | 全面方案 - 每套方案内： - 产品表格（产品名/保额/年保费/推荐理由） - 总保费 - 方案总结 - 操作栏：[浏览器打印] [重新生成] [导出 PDF] [分享] - 免责声明 -``` - -**3.10 RecommendHistory.vue — 历史方案列表** - -``` -功能： - 分页表格：方案名称 / 客户姓名 / 险种 / 状态 / 创建时间 / 操作 - 筛选：客户姓名 / 险种 / 时间范围 - 操作：查看详情 / 导出 / 删除 -``` - -**3.11 RecommendDetail.vue — 方案详情** - -``` -功能： - 展示完整方案内容 - 导出按钮（PDF / Word / PPT） - 分享按钮 → 生成链接 → 复制 -``` - -#### 验证标准 - -```bash -# 端到端 -1. /recommend → 填写客户信息 → 点击"生成方案" -2. 页面显示 loading → 轮询中... -3. ~15 秒后显示 3 套方案 -4. 点击"导出 PDF" → 浏览器下载 PDF -5. /recommend/history → 看到刚才生成的方案 -``` - ---- - -### Phase 4：企微集成（1.5 天） - -**目标**：企微私聊/群聊能问 BaoDan 问题。 - -#### 后端 - -**4.1 wecom_api.py — 企微 API 封装** - -```python -class WeComAPI: - def get_access_token(self): - """获取企微 access_token，缓存到 Redis（提前 5 分钟刷新）""" - - def send_text_message(self, user_id, content): - """单聊发消息""" - - def send_group_message(self, chat_id, content): - """群聊发消息""" - - def send_long_message(self, user_id, content): - """长消息自动分段发送（>2048字节时分段，间隔500ms）""" -``` - -**4.2 wecom_bot.py — 消息回调处理** - -``` -GET /api/wecom/callback（URL 验证） - 1. SHA1(sort([Token, timestamp, nonce, echostr])) - 2. 与 msg_signature 比对 - 3. 验证通过 → 返回解密后的 echostr - -POST /api/wecom/callback（消息接收） - 1. 立即返回 "success"（5 秒内） - 2. 异步处理： - a. 验证签名 + 解密 XML - b. 判断 MsgType： - - text → 继续处理 - - image/voice/video/file → 回复"暂不支持该消息类型" - - event → 忽略 - c. 群聊消息 → 去掉"@机器人"前缀 - d. 查 wecom_user_mapping 获取用户 - e. 调 BaoDan Chat API（blocking） - f. 通过企微 API 回复 -``` - -> 关键：5 秒内必须返回 success。所以用 Flask 的异步机制（threading/queue），先返回再处理。 - -**4.3 wecom_oauth.py — OAuth 登录** - -``` -GET /api/wecom/oauth - 构造企微授权 URL → 302 重定向 - -GET /api/wecom/oauth/callback - 1. 用 code 调企微 API → 获取用户信息 - 2. 查/建 wecom_user_mapping - 3. 签发 JWT - 4. 302 重定向到前端（URL 带 token） -``` - -**4.4 XML 加解密** - -```python -# 企微消息加解密（AES-CBC） -# 参考企微官方 SDK 或自行实现 -# 核心：decrypt_msg(encrypted_msg) → 明文 XML -``` - -#### 验证标准 - -```bash -# 模拟企微回调 -curl "http://localhost:5001/api/wecom/callback?msg_signature=xxx×tamp=xxx&nonce=xxx&echostr=encrypted_echostr" -# → 返回解密后的 echostr - -# 模拟消息推送（用企微调试工具） -# → 机器人回复 AI 回答 -``` - ---- - -### Phase 5：用户权限管理（1 天） - -**目标**：管理员能管用户、配角色、数据隔离。 - -#### 后端 - -**5.1 用户 CRUD — /api/admin/users** - -``` -GET /api/admin/users → 分页列表（支持 role/department/keyword 筛选） -POST /api/admin/users → 新增用户（插入 wecom_user_mapping） -PUT /api/admin/users/{id} → 编辑（改角色/部门/状态） -DELETE /api/admin/users/{id} → 停用（status=disabled + 吊销所有 Token） -``` - -**5.2 批量导入 — /api/admin/users/batch-import** - -``` -POST（multipart/form-data） → 解析 Excel → 批量插入 -``` - -**5.3 角色管理 — /api/admin/roles** - -``` -GET /api/admin/roles → 5 个内置角色 + 自定义角色 -POST /api/admin/roles → 新建角色（name + permissions 数组） -PUT /api/admin/roles/{id} → 更新权限 -DELETE /api/admin/roles/{id} → 删除（内置角色不可删） -``` - -**5.4 权限校验中间件 — middleware.py** - -```python -# 在需要权限的路由上加装饰器： -@require_permission('kb_manage') -def upload_document(): - ... - -# 权限列表： -# chat, proposal, kb_manage, kb_view, log_view, user_manage, -# config_manage, team_stats, system_log -``` - -**5.5 数据权限（5.2.3）** - -这是 BaoDan 不具备的核心能力： -``` -- 销售(sales) → 只能看自己的数据（推荐记录、对话） -- 主管(manager) → 看本组数据（同 department） -- 管理员(admin) / 超级管理员(super_admin) → 看全部 -``` - -实现方式：在查询接口中自动注入 `WHERE user_id = ?` 或 `WHERE department = ?` 条件。 - -#### 前端 - -**5.6 UsersPage.vue** - -``` -功能： - 用户表格（分页）：用户名/企微ID/角色/部门/状态/操作 - 新增用户弹窗 - 编辑用户弹窗 - 停用确认弹窗 - 批量导入按钮（上传 Excel） -``` - -**5.7 PermissionsPage.vue** - -``` -功能： - 左侧：角色列表（可选中） - 右侧：权限配置面板（checkbox 分组） - 对话：智能问答 / 产品推荐 - 管理：知识库管理 / 对话日志 / 用户管理 / 数据统计 / 系统日志 - [保存权限] 按钮 -``` - -#### 验证标准 - -```bash -# 管理员操作 -1. 登录 admin → /admin/users → 看到用户列表 -2. 新增一个 sales 角色用户 -3. 用新用户登录 → 只能看到 /chat、/recommend -4. 访问 /admin/users → 返回 403 -``` - ---- - -### Phase 6：数据统计（1 天） - -**目标**：管理员能看到系统使用数据。 - -#### 后端 - -**6.1 GET /api/stats/overview** - -``` -处理： - 今日问答数 → 查 BaoDan 对话记录（或自建统计表） - 活跃用户数 → 查 wecom_user_mapping 中 last_active_at 在今天内的 - 知识库命中率 → 查 BaoDan 日志中有 retriever_resources 的比例 - 文档总数 → 查 BaoDan datasets/documents 数量 -输出：{ today_chats, active_users, kb_hit_rate, total_documents } -``` - -**6.2 GET /api/stats/trend** - -``` -输入：?metric=chat_count&start_date=2026-05-01&end_date=2026-05-31&granularity=day -处理：按天聚合数据 -输出：{ metric, granularity, data: [{ date, value }] } -``` - -**6.3 GET /api/stats/kb-health** - -``` -输入：?days=30 -处理： - 热门问题 TOP20 → 按 query 文本分组计数 - 未命中问题 → 检索结果 score < 0.5 的问题 - 文档覆盖率 → 各险种文档数量统计 -输出：{ hot_questions, missed_questions, coverage } -``` - -> 注：热门问题和未命中问题需要在问答接口中记录日志到自研表（或从 BaoDan 日志中聚合）。 - -#### 前端 - -**6.4 StatsPage.vue** - -``` -结构： - 顶栏：4 个指标卡片（今日问答/活跃用户/命中率/文档数） - 中间：趋势折线图（ECharts，7天/30天切换） - 底部左：险种分布饼图 - 底部右：热门问题 TOP20 表格 -``` - -#### 验证标准 - -```bash -浏览器打开 /admin/stats → 看到指标卡片 + 图表 -（数据量少时可能为空，但页面不报错） -``` - ---- - -### Phase 7：知识库增强（1 天） - -**目标**：BaoDan 后台不支持的 KB 功能（编号/标签/数据源）。 - -#### 后端 - -**7.1 数据库追加表** - -```sql --- 文档元数据（编号、标签、险种、保司） -CREATE TABLE document_metadata ( - id SERIAL PRIMARY KEY, - baodan_document_id VARCHAR(64) NOT NULL, - dataset_id VARCHAR(64) NOT NULL, - doc_number VARCHAR(32), -- 编号，如 CJ-XX-001 - insurance_type VARCHAR(32), -- 险种 - company VARCHAR(64), -- 保司 - tags JSONB DEFAULT '[]', -- 自定义标签 - created_at TIMESTAMP DEFAULT NOW(), - updated_at TIMESTAMP DEFAULT NOW() -); - --- 保司 API 数据源配置 -CREATE TABLE datasource_configs ( - id SERIAL PRIMARY KEY, - name VARCHAR(128) NOT NULL, - api_url VARCHAR(512) NOT NULL, - api_key_encrypted TEXT, -- AES 加密存储 - sync_frequency VARCHAR(32), -- CRON 表达式 - 险种 VARCHAR(32), - last_sync_at TIMESTAMP, - last_sync_status VARCHAR(16), - last_sync_count INTEGER, - status VARCHAR(16) DEFAULT 'active', - created_at TIMESTAMP DEFAULT NOW() -); - --- 同步日志 -CREATE TABLE datasource_sync_logs ( - id SERIAL PRIMARY KEY, - datasource_id INTEGER REFERENCES datasource_configs(id), - status VARCHAR(16), -- success/failed - items_added INTEGER DEFAULT 0, - items_updated INTEGER DEFAULT 0, - items_deleted INTEGER DEFAULT 0, - error_message TEXT, - started_at TIMESTAMP DEFAULT NOW(), - completed_at TIMESTAMP -); -``` - -**7.2 文档管理增强接口** - -``` -POST /api/kb/documents/upload → 上传文档（同时写 document_metadata） -GET /api/kb/documents → 文档列表（JOIN document_metadata 拿编号/标签） -PATCH /api/kb/documents/{id} → 更新编号/标签 -GET /api/kb/documents/{id}/status → 处理状态 -DELETE /api/kb/documents/{id} → 删除文档 -POST /api/kb/documents/{id}/retry → 重试 -``` - -**7.3 保司数据源接口** - -``` -GET /api/kb/datasources → 数据源列表 -POST /api/kb/datasources → 新建数据源 -POST /api/kb/datasources/{id}/sync → 手动同步（异步） -GET /api/kb/datasources/{id}/logs → 同步日志 -``` - -**7.4 编号自动生成规则** - -```python -def generate_doc_number(insurance_type, company): - """ - 规则：险种代码-保司代码-序号 - 例：CJ-XX-001（重疾险-XX人寿-第1个文档） - 险种代码：CJ=重疾, RS=寿险, YL=医疗, YW=意外, CX=车险, NJ=年金, CX=储蓄 - """ -``` - -#### 前端 - -**7.5 KBManagePage.vue** - -``` -功能： - 文档列表表格（分页）：编号/文件名/险种/保司/标签/状态/操作 - 上传文档弹窗（多文件 + 选择险种 + 填写保司） - 编辑元数据弹窗（修改编号、标签） - 删除确认 -``` - -**7.6 DataSourcePage.vue** - -``` -功能： - 数据源列表表格：名称/URL/同步频率/上次同步/状态/操作 - 新建数据源弹窗 - [立即同步] 按钮 → 显示同步进度 - 同步日志查看 -``` - -#### 验证标准 - -```bash -1. /admin/kb → 上传一个 MD 文件 → 选择险种 → 看到文档在列表中 -2. 点编辑 → 修改编号为 CJ-XX-001 → 保存成功 -3. /admin/datasource → 新建一个数据源 → 点击"立即同步" -``` - ---- - -### Phase 8：导出 + 日志 + 收尾（0.5 天） - -#### 导出功能 - -**8.1 PDF 导出** - -```python -# 使用 reportlab 或 weasyprint -# 按模板渲染推荐方案 → 生成 PDF -# 需要客户提供 PDF 模板（或先用简单模板） -``` - -**8.2 Word 导出** - -```python -# 使用 python-docx -# 最简单的导出方式，优先实现 -``` - -**8.3 PPT 导出** - -```python -# 使用 python-pptx -# 按模板生成 PPT（需要客户提供模板） -``` - -#### 系统日志 - -**8.4 system_operation_logs 记录** - -在以下操作时自动写入： -- 登录/登出 -- 文档上传/删除 -- 角色权限变更 -- 推荐方案生成 - -#### 通知告警（可选） - -**8.5 企微 Webhook 通知** - -```python -def send_alert(message): - """通过企微机器人 Webhook 发送告警""" - webhook_url = config.WECOM_WEBHOOK_URL - requests.post(webhook_url, json={"msgtype": "text", "text": {"content": message}}) -``` - -告警场景： -- 数据源同步失败 -- Token 月消耗超预算 - ---- - -## 五、依赖安装清单 - -### 后端（Python） - -``` -PyJWT==2.* # JWT 签发 -bcrypt==4.* # 密码哈希 -python-docx==1.* # Word 导出 -reportlab==4.* # PDF 导出（可选） -python-pptx==1.* # PPT 导出（可选） -openpyxl==3.* # Excel 批量导入 -lxml==5.* # XML 解析（企微消息） -cryptography==43.* # AES 加解密（企微消息 + API Key） -celery==5.* # 异步任务（企微消息处理、文档同步） -``` - -> 大部分依赖 BaoDan 已有（Flask、SQLAlchemy、Redis），不需要重复安装。 - -### 前端（Node） - -``` -vue@3 -vue-router@4 -element-plus -axios -marked # Markdown 渲染 -echarts # 统计图表 -``` - ---- - -## 六、风险与应对 - -| 风险 | 影响 | 应对 | -|------|------|------| -| BaoDan Workflow 输出格式不稳定 | 推荐方案解析失败 | 在 workflow_helper.py 中加容错解析 + fallback | -| 企微消息加解密实现复杂 | 回调不通 | 参考企微官方 Python SDK（wxwork-sdk） | -| 9GB 知识库上传慢 | 首次导入耗时长 | 分批上传 + 异步处理 + 进度反馈 | -| BaoDan 版本升级破坏接口 | 自研代码不可用 | 只改 main.py + app_factory.py，insurance/ 独立 | -| 一人开发工期紧 | 10 天可能不够 | Phase 7-8 可推后，Phase 0-5 是 MVP | - ---- - -## 七、MVP 交付标准 - -Phase 0-5 完成后即可进入测试： - -``` -✅ 能登录（企微 + 账密） -✅ 能在 iframe 中跟 BaoDan 对话 -✅ 能筛选险种 -✅ 能填写客户信息生成推荐方案 -✅ 能查看历史方案 -✅ 企微私聊能问答 -✅ 管理员能管用户和角色 -``` - -Phase 6-8 为增强功能，可并行测试： - -``` -⏳ 数据统计仪表盘 -⏳ 知识库编号/标签管理 -⏳ 保司数据源同步 -⏳ PDF/Word 导出 -⏳ 系统操作日志 -``` diff --git a/docs/快速部署指南.md b/docs/快速部署指南.md deleted file mode 100644 index 8010367..0000000 --- a/docs/快速部署指南.md +++ /dev/null @@ -1,366 +0,0 @@ -# 保险智能客服系统 — 快速部署指南 - -> 本文档指导你将本地开发环境的项目和数据完整部署到服务器。 - ---- - -## 📋 前置条件 - -| 项目 | 要求 | -|------|------| -| 本地环境 | Docker 已运行，项目正常 | -| 服务器 | Linux（Ubuntu/CentOS），可 SSH 登录 | -| 服务器配置 | 2核4G 以上，开放 3000/5001/9080 端口 | - ---- - -## 🚀 一键部署（3 步完成） - -### 第一步：本地导出数据 - -**Windows 用户（推荐）：** -```bash -# 方式一：双击运行 export-data.bat -# 方式二：右键 export-data.ps1 -> 使用 PowerShell 运行 - -# 方式三：在 Git Bash 中执行 -cd D:\work\code\python\coding\baodanagent -bash migrate.sh export -``` - -**Linux/Mac 用户：** -```bash -cd /path/to/baodanagent -bash migrate.sh export -``` - -**导出完成后会生成：** -``` -migrate-package.tar.gz ← 上传这个文件到服务器 -``` - ---- - -### 第二步：上传到服务器 - -```bash -# 上传迁移包（约 1-2MB） -scp migrate-package.tar.gz root@你的服务器IP:/opt/ -``` - ---- - -### 第三步：服务器执行部署 - -```bash -# SSH 登录服务器 -ssh root@你的服务器IP - -# 解压迁移包 -cd /opt -tar xzf migrate-package.tar.gz - -# 执行部署脚本（自动安装 Docker + 导入数据 + 启动所有服务） -bash server-deploy.sh -``` - -**等待约 10-15 分钟，部署完成！** - ---- - -## ✅ 验证部署 - -部署完成后，访问： - -| 服务 | 地址 | 说明 | -|------|------|------| -| **BaoDan 管理后台** | `http://服务器IP:3000` | 知识库、模型、应用管理 | -| **保险前端** | `http://服务器IP:9080` | 保险智能客服界面 | -| **API 接口** | `http://服务器IP:5001` | 后端接口 | - -**默认账号：** -- BaoDan 管理后台：`taiyi@baodan.com` / `taiyi1224` -- 保险系统：`admin` / `taiyi1224` - ---- - -## 📝 详细步骤说明 - -### 1. 本地导出详解 - -```bash -cd D:\work\code\python\coding\baodanagent -bash migrate.sh export -``` - -**导出内容：** -| 文件 | 说明 | -|------|------| -| `baodan.sql` | 业务数据库（用户、对话、知识库等） | -| `dify_plugin.sql` | 插件数据库 | -| `api-insurance/` | 保险模块代码 | -| `frontend-dist/` | 前端编译产物 | -| `scripts/` | 启动脚本 | -| `deploy/` | 配置文件、Logo | - -**打包后大小：** 约 1-2MB - ---- - -### 2. 上传文件 - -```bash -# 方式一：scp 命令 -scp migrate-package.tar.gz root@服务器IP:/opt/ - -# 方式二：使用 SFTP 工具（如 WinSCP、FileZilla） -# 直接拖拽 migrate-package.tar.gz 到服务器 /opt/ 目录 -``` - ---- - -### 3. 服务器部署详解 - -```bash -# SSH 登录 -ssh root@服务器IP - -# 进入目录 -cd /opt - -# 解压 -tar xzf migrate-package.tar.gz - -# 进入解压后的目录 -cd migrate-package - -# 执行部署 -bash ../server-deploy.sh -``` - -**server-deploy.sh 会自动执行：** -1. ✅ 检查/安装 Docker 和 Docker Compose -2. ✅ 生成环境配置文件（.env） -3. ✅ 启动 PostgreSQL 和 Redis -4. ✅ 导入数据库（baodan.sql + dify_plugin.sql） -5. ✅ 构建自定义镜像（约 10 分钟） -6. ✅ 启动所有服务（API、Web、Worker、前端） -7. ✅ 等待服务就绪并显示访问地址 - ---- - -## 🔧 常用运维命令 - -### 查看服务状态 -```bash -docker ps -``` - -### 查看日志 -```bash -# 查看 API 日志 -docker logs -f baodanagent-baodan-api-1 - -# 查看所有日志 -docker compose -f docker-compose.dify.yml logs -f -``` - -### 重启服务 -```bash -# 重启所有服务 -docker compose -f docker-compose.dify.yml restart - -# 重启单个服务 -docker compose -f docker-compose.dify.yml restart baodan-api -``` - -### 停止服务 -```bash -docker compose -f docker-compose.dify.yml down -``` - -### 更新代码（不丢失数据） -```bash -# 1. 本地重新打包 -cd D:\work\code\python\coding\baodanagent -bash migrate.sh export - -# 2. 上传到服务器 -scp migrate-package.tar.gz root@服务器IP:/opt/ - -# 3. 服务器上更新 -ssh root@服务器IP -cd /opt -tar xzf migrate-package.tar.gz -cd migrate-package - -# 4. 重新构建并启动（数据库数据保留） -docker compose -f docker-compose.dify.yml up -d --build -``` - ---- - -## ⚠️ 部署后必做 - -### 1. 修改默认密码 - -```bash -# 编辑 .env 文件 -vim /opt/baodanagent/.env - -# 修改以下内容： -POSTGRES_PASSWORD=你的数据库密码 -ADMIN_PASSWORD=你的管理员密码 - -# 重启服务使配置生效 -docker compose -f docker-compose.dify.yml restart -``` - -### 2. 配置防火墙 - -```bash -# Ubuntu/Debian -ufw allow 3000/tcp # BaoDan Web -ufw allow 5001/tcp # API -ufw allow 9080/tcp # 保险前端 -ufw enable - -# CentOS/RHEL -firewall-cmd --permanent --add-port=3000/tcp -firewall-cmd --permanent --add-port=5001/tcp -firewall-cmd --permanent --add-port=9080/tcp -firewall-cmd --reload -``` - -### 3. 配置域名（可选） - -如果有域名，建议使用 Nginx 反向代理： - -```nginx -# /etc/nginx/conf.d/baodanagent.conf -server { - listen 80; - server_name your-domain.com; - - # BaoDan Web - location / { - proxy_pass http://localhost:3000; - proxy_set_header Host $host; - } - - # API - location /api/ { - proxy_pass http://localhost:5001; - proxy_set_header Host $host; - } - - # 保险前端 - location /insurance/ { - proxy_pass http://localhost:9080; - proxy_set_header Host $host; - } -} -``` - ---- - -## ❓ 常见问题 - -### Q1: 部署后无法访问？ - -```bash -# 检查容器是否运行 -docker ps - -# 检查端口是否监听 -netstat -tlnp | grep -E '3000|5001|9080' - -# 检查防火墙 -ufw status -``` - -### Q2: 数据库导入失败？ - -```bash -# 检查数据库状态 -docker exec baodanagent-db-1 pg_isready -U postgres - -# 手动导入 -docker exec -i baodanagent-db-1 psql -U postgres -d baodan < baodan.sql -``` - -### Q3: 登录失败？ - -```bash -# 检查用户数据 -docker exec baodanagent-db-1 psql -U postgres -d baodan -c "SELECT id, username, role FROM wecom_user_mapping;" - -# 如需重置密码 -docker exec baodanagent-db-1 psql -U postgres -d baodan -c "UPDATE wecom_user_mapping SET password_hash = '\$2b\$12\$lTC5V3v7HSAgLY.PwPZNLOb9AeXYZG4WJ4SAzHraV81LzcZfBpwrm' WHERE username = 'admin';" -``` - -### Q4: 前端无法访问？ - -```bash -# 检查前端容器 -docker ps | grep frontend - -# 启动前端 -docker compose -f docker-compose.frontend.yml up -d -``` - ---- - -## 📊 部署架构 - -``` -┌─────────────────────────────────────────────────────────┐ -│ 服务器 │ -│ │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ PostgreSQL │ │ Redis │ │ Sandbox │ │ -│ │ :5433 │ │ :6380 │ │ (内部) │ │ -│ └──────┬───────┘ └──────┬──────┘ └──────┬──────┘ │ -│ │ │ │ │ -│ └────────┬────────┴────────┬────────┘ │ -│ │ │ │ -│ ┌────────▼────────┐ ┌─────▼──────┐ │ -│ │ BaoDan API │ │ Worker │ │ -│ │ :5001 │ │ (Celery) │ │ -│ └────────┬────────┘ └────────────┘ │ -│ │ │ -│ ┌────────▼────────┐ ┌─────────────┐ │ -│ │ BaoDan Web │ │ 保险前端 │ │ -│ │ :3000 │ │ :9080 │ │ -│ └─────────────────┘ └─────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────┘ - │ │ - ▼ ▼ - 管理后台 客服界面 -``` - ---- - -## 📞 获取帮助 - -```bash -# 查看容器日志 -docker logs baodanagent-baodan-api-1 --tail 100 - -# 检查数据库连接 -docker exec baodanagent-db-1 psql -U postgres -d baodan -c "SELECT 1;" - -# 检查 Redis 连接 -docker exec baodanagent-redis-1 redis-cli ping - -# 查看磁盘空间 -df -h - -# 查看内存使用 -free -h -``` - ---- - -**最后更新：2026-06-30** diff --git a/docs/数据同步指南.md b/docs/数据同步指南.md deleted file mode 100644 index 16a8917..0000000 --- a/docs/数据同步指南.md +++ /dev/null @@ -1,329 +0,0 @@ -# 保险智能客服系统 — 数据同步指南 - -## 一、数据类型说明 - -| 数据类型 | 存储位置 | 同步方式 | -|---------|---------|---------| -| 用户数据 | PostgreSQL `wecom_user_mapping` 表 | 数据库导出/导入 | -| 知识库文档 | PostgreSQL + 文件存储 | 数据库 + 文件打包 | -| 对话记录 | PostgreSQL | 数据库导出/导入 | -| 应用配置 | PostgreSQL | 数据库导出/导入 | -| 上传文件 | Docker Volume `api_storage` | 文件拷贝 | - ---- - -## 二、方式一：使用 migrate.sh（推荐） - -### 2.1 导出本地数据 - -```bash -# 在本地开发机执行 -cd D:\work\code\python\coding\baodanagent - -# 导出迁移包（包含数据库 + 项目文件） -bash migrate.sh export -``` - -生成文件：`migrate-package.tar.gz`（包含完整数据库） - -### 2.2 上传到服务器 - -```bash -# 上传迁移包 -scp migrate-package.tar.gz root@服务器IP:/opt/ - -# SSH 登录服务器 -ssh root@服务器IP -cd /opt -tar xzf migrate-package.tar.gz -``` - -### 2.3 在服务器导入 - -```bash -cd /opt/migrate-package - -# 导入数据并启动服务 -bash ../migrate.sh import -``` - ---- - -## 三、方式二：手动数据库同步 - -### 3.1 导出数据库（本地） - -```bash -# 导出 baodan 数据库 -docker exec baodanagent-db-1 pg_dump -U postgres baodan > baodan_backup.sql - -# 导出插件数据库 -docker exec baodanagent-db-1 pg_dump -U postgres dify_plugin > dify_plugin_backup.sql - -# 查看导出文件大小 -ls -lh baodan_backup.sql dify_plugin_backup.sql -``` - -### 3.2 上传到服务器 - -```bash -# 上传 SQL 文件 -scp baodan_backup.sql dify_plugin_backup.sql root@服务器IP:/opt/baodanagent/ -``` - -### 3.3 导入到服务器 - -```bash -# SSH 登录服务器 -ssh root@服务器IP -cd /opt/baodanagent - -# 启动数据库（如未启动） -docker compose -f docker-compose.dify.yml up -d db redis -sleep 10 - -# 创建插件数据库（如不存在） -docker exec baodanagent-db-1 psql -U postgres -c "CREATE DATABASE dify_plugin;" 2>/dev/null || true - -# 导入数据 -docker exec -i baodanagent-db-1 psql -U postgres -d baodan < baodan_backup.sql -docker exec -i baodanagent-db-1 psql -U postgres -d dify_plugin < dify_plugin_backup.sql - -# 重启所有服务 -docker compose -f docker-compose.dify.yml restart -``` - ---- - -## 四、方式三：仅同步部分数据 - -### 4.1 只同步用户数据 - -```bash -# 导出用户表 -docker exec baodanagent-db-1 pg_dump -U postgres -d baodan -t wecom_user_mapping > users.sql - -# 导入用户表 -docker exec -i baodanagent-db-1 psql -U postgres -d baodan < users.sql -``` - -### 4.2 只同步知识库 - -```bash -# 导出知识库相关表 -docker exec baodanagent-db-1 pg_dump -U postgres -d baodan \ - -t datasets \ - -t dataset_documents \ - -t document_segments \ - > knowledge_base.sql - -# 导入 -docker exec -i baodanagent-db-1 psql -U postgres -d baodan < knowledge_base.sql -``` - -### 4.3 只同步应用配置 - -```bash -# 导出应用配置 -docker exec baodanagent-db-1 pg_dump -U postgres -d baodan \ - -t apps \ - -t app_model_configs \ - -t conversations \ - > apps.sql - -# 导入 -docker exec -i baodanagent-db-1 psql -U postgres -d baodan < apps.sql -``` - ---- - -## 五、同步文件存储 - -### 5.1 导出上传文件 - -```bash -# 本地导出 -docker cp baodanagent-baodan-api-1:/app/api/storage ./api_storage_backup - -# 打包 -tar czf api_storage.tar.gz api_storage_backup/ -``` - -### 5.2 上传并恢复 - -```bash -# 上传 -scp api_storage.tar.gz root@服务器IP:/opt/baodanagent/ - -# 服务器上恢复 -tar xzf api_storage.tar.gz -docker cp api_storage_backup baodanagent-baodan-api-1:/app/api/storage -``` - ---- - -## 六、完整同步流程 - -### 场景：从本地开发环境同步到生产服务器 - -```bash -# ========== 本地操作 ========== - -# 1. 停止本地服务（可选，避免数据不一致） -docker compose -f docker-compose.dify.yml stop baodan-api baodan-worker - -# 2. 导出完整数据 -bash migrate.sh export - -# 3. 重启本地服务 -docker compose -f docker-compose.dify.yml start - -# 4. 上传迁移包 -scp migrate-package.tar.gz root@服务器IP:/opt/ - -# ========== 服务器操作 ========== - -# 5. SSH 登录 -ssh root@服务器IP - -# 6. 解压 -cd /opt -tar xzf migrate-package.tar.gz - -# 7. 导入并启动 -cd migrate-package -bash ../migrate.sh import -``` - ---- - -## 七、数据同步脚本 - -### 7.1 快速同步脚本（本地） - -```bash -#!/bin/bash -# quick-sync.sh - 快速同步数据到服务器 - -SERVER_IP=$1 -if [ -z "$SERVER_IP" ]; then - echo "用法: bash quick-sync.sh <服务器IP>" - exit 1 -fi - -echo "正在导出数据库..." -docker exec baodanagent-db-1 pg_dump -U postgres baodan > /tmp/baodan_sync.sql -docker exec baodanagent-db-1 pg_dump -U postgres dify_plugin > /tmp/dify_plugin_sync.sql - -echo "正在上传到服务器..." -scp /tmp/baodan_sync.sql /tmp/dify_plugin_sync.sql root@$SERVER_IP:/tmp/ - -echo "正在服务器上导入..." -ssh root@$SERVER_IP << 'EOF' -docker exec -i baodanagent-db-1 psql -U postgres -d baodan < /tmp/baodan_sync.sql -docker exec -i baodanagent-db-1 psql -U postgres -d dify_plugin < /tmp/dify_plugin_sync.sql -docker compose -f /opt/baodanagent/docker-compose.dify.yml restart baodan-api baodan-worker -EOF - -echo "同步完成！" -rm -f /tmp/baodan_sync.sql /tmp/dify_plugin_sync.sql -``` - -### 7.2 使用方法 - -```bash -# 保存为 quick-sync.sh -chmod +x quick-sync.sh - -# 执行同步 -bash quick-sync.sh 192.168.1.100 -``` - ---- - -## 八、验证同步结果 - -### 8.1 检查用户数据 - -```bash -# 服务器上执行 -docker exec baodanagent-db-1 psql -U postgres -d baodan -c "SELECT id, username, role FROM wecom_user_mapping;" -``` - -### 8.2 检查知识库 - -```bash -docker exec baodanagent-db-1 psql -U postgres -d baodan -c "SELECT id, name FROM datasets;" -``` - -### 8.3 检查 API 服务 - -```bash -curl http://localhost:5001/health -# 预期返回：{"status":"ok","service":"baodanagent-api"} -``` - -### 8.4 检查前端登录 - -```bash -curl -X POST http://localhost:9080/insurance/auth/password-login \ - -H "Content-Type: application/json" \ - -d '{"username":"admin","password":"taiyi1224"}' -``` - ---- - -## 九、常见问题 - -### Q1: 数据库导入报错 "relation already exists" - -```bash -# 使用 -c 选项先清理再导入 -docker exec -i baodanagent-db-1 psql -U postgres -d baodan -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;" -docker exec -i baodanagent-db-1 psql -U postgres -d baodan < baodan_backup.sql -``` - -### Q2: 导入后用户无法登录 - -检查密码哈希是否正确： -```bash -docker exec baodanagent-db-1 psql -U postgres -d baodan -c "SELECT username, password_hash IS NOT NULL FROM wecom_user_mapping;" -``` - -### Q3: 知识库文档丢失 - -知识库文档存储在 Docker Volume 中，需要额外同步： -```bash -# 导出 -docker cp baodanagent-baodan-api-1:/app/api/storage ./storage_backup - -# 导入 -docker cp storage_backup baodanagent-baodan-api-1:/app/api/storage -``` - -### Q4: 同步后 API 返回 500 错误 - -检查数据库连接： -```bash -docker exec baodanagent-baodan-api-1 python -c " -from insurance.app import create_app -from insurance.db.compat import db -app = create_app() -with app.app_context(): - print(db.session.execute(db.text('SELECT 1')).scalar()) -" -``` - ---- - -## 十、定时同步（可选） - -如果需要定期同步数据，可以设置 cron 任务： - -```bash -# 编辑 crontab -crontab -e - -# 每天凌晨 3 点同步数据 -0 3 * * * /opt/baodanagent/scripts/sync-data.sh >> /var/log/sync.log 2>&1 -``` diff --git a/docs/服务器部署指南.md b/docs/服务器部署指南.md deleted file mode 100644 index 5cbfeaf..0000000 --- a/docs/服务器部署指南.md +++ /dev/null @@ -1,353 +0,0 @@ -# 保险智能客服系统 — 服务器部署指南 - -## 一、部署前准备 - -### 1.1 服务器要求 - -| 项目 | 最低要求 | 推荐配置 | -|------|---------|---------| -| CPU | 2 核 | 4 核+ | -| 内存 | 4GB | 8GB+ | -| 磁盘 | 40GB | 100GB+ SSD | -| 系统 | Ubuntu 20.04+ / CentOS 7+ | Ubuntu 22.04 | -| Docker | 20.10+ | 最新版 | -| Docker Compose | v2.0+ | 最新版 | - -### 1.2 网络要求 - -- 开放端口：`3000`（Web 管理后台）、`5001`（API）、`9080`（前端） -- 服务器需能访问外网（拉取 Docker 镜像） - -### 1.3 本地打包 - -```bash -# 在开发机执行，生成部署包（约 1-2MB） -bash package.sh -``` - -生成文件：`baodanagent-YYYYMMDD_HHMMSS.tar.gz` - ---- - -## 二、快速部署（推荐） - -### 方式 A：一键部署脚本（Linux 服务器） - -```bash -# 1. 上传部署包到服务器 -scp baodanagent-*.tar.gz root@服务器IP:/opt/ - -# 2. SSH 登录服务器 -ssh root@服务器IP - -# 3. 解压并进入目录 -cd /opt -tar xzf baodanagent-*.tar.gz -cd baodanagent-* - -# 4. 执行一键部署 -bash server-deploy.sh -``` - -脚本会自动： -- ✅ 安装 Docker 和 Docker Compose（如未安装） -- ✅ 拉取官方镜像 -- ✅ 构建自定义 API 镜像 -- ✅ 生成 docker-compose.yml -- ✅ 初始化数据库 -- ✅ 启动所有服务 - -### 方式 B：手动部署 - -```bash -# 1. 安装 Docker（如未安装） -curl -fsSL https://get.docker.com | sh -systemctl enable docker && systemctl start docker - -# 2. 安装 Docker Compose 插件 -apt-get update && apt-get install -y docker-compose-plugin - -# 3. 上传并解压部署包 -scp baodanagent-*.tar.gz root@服务器IP:/opt/ -ssh root@服务器IP -cd /opt && tar xzf baodanagent-*.tar.gz && cd baodanagent-* - -# 4. 启动所有服务 -docker compose -f docker-compose.dify.yml up -d - -# 5. 检查状态 -docker compose -f docker-compose.dify.yml ps -``` - ---- - -## 三、访问系统 - -部署完成后，通过浏览器访问： - -| 服务 | 地址 | 说明 | -|------|------|------| -| BaoDan 管理后台 | `http://服务器IP:3000` | 知识库、模型、应用管理 | -| 保险前端 | `http://服务器IP:9080` | 保险智能客服界面 | -| API 服务 | `http://服务器IP:5001` | 后端接口 | - -### 默认账号 - -| 系统 | 用户名 | 密码 | -|------|--------|------| -| BaoDan 管理后台 | `taiyi@baodan.com` | `taiyi1224` | -| 保险系统 | `admin` | `taiyi1224` | - ---- - -## 四、配置修改 - -### 4.1 修改密码（重要！） - -部署后务必修改默认密码： - -```bash -# 编辑环境配置 -vim .env - -# 修改以下配置： -POSTGRES_PASSWORD=你的数据库密码 -ADMIN_PASSWORD=你的管理员密码 -SECRET_KEY=你的密钥（可用 openssl rand -hex 32 生成） -``` - -修改后重启服务： -```bash -docker compose -f docker-compose.dify.yml restart -``` - -### 4.2 配置域名（可选） - -如果有域名，需要： - -1. 配置 DNS 解析到服务器 IP -2. 修改 docker-compose.yml 中的 URL： - -```yaml -CONSOLE_API_URL: https://your-domain.com -CONSOLE_WEB_URL: https://your-domain.com -``` - -3. 建议使用 Nginx 反向代理 + SSL 证书 - -### 4.3 配置 HTTPS（推荐） - -使用 Let's Encrypt 免费 SSL 证书： - -```bash -# 安装 Certbot -apt-get install -y certbot - -# 获取证书 -certbot certonly --standalone -d your-domain.com - -# 证书路径 -# /etc/letsencrypt/live/your-domain.com/fullchain.pem -# /etc/letsencrypt/live/your-domain.com/privkey.pem -``` - -然后配置 Nginx 反向代理（参考 `deploy/nginx.conf`）。 - ---- - -## 五、常用运维命令 - -### 5.1 查看状态 - -```bash -# 查看容器状态 -docker compose -f docker-compose.dify.yml ps - -# 查看所有容器（包括停止的） -docker ps -a -``` - -### 5.2 查看日志 - -```bash -# 查看 API 日志 -docker compose -f docker-compose.dify.yml logs -f baodan-api - -# 查看所有日志 -docker compose -f docker-compose.dify.yml logs -f - -# 查看最近 100 行日志 -docker compose -f docker-compose.dify.yml logs --tail 100 baodan-api -``` - -### 5.3 重启服务 - -```bash -# 重启所有服务 -docker compose -f docker-compose.dify.yml restart - -# 重启单个服务 -docker compose -f docker-compose.dify.yml restart baodan-api -``` - -### 5.4 停止/启动 - -```bash -# 停止所有服务 -docker compose -f docker-compose.dify.yml down - -# 启动所有服务 -docker compose -f docker-compose.dify.yml up -d -``` - -### 5.5 更新代码 - -```bash -# 1. 在本地重新打包 -bash package.sh - -# 2. 上传到服务器 -scp baodanagent-*.tar.gz root@服务器IP:/opt/ - -# 3. 在服务器上更新 -ssh root@服务器IP -cd /opt -tar xzf baodanagent-*.tar.gz -cd baodanagent-* - -# 4. 重新构建并启动 -docker compose -f docker-compose.dify.yml up -d --build - -# 5. 清理旧镜像 -docker image prune -f -``` - -### 5.6 数据备份 - -```bash -# 备份数据库 -docker exec baodanagent-db-1 pg_dump -U postgres baodan > backup_$(date +%Y%m%d).sql - -# 恢复数据库 -docker exec -i baodanagent-db-1 psql -U postgres baodan < backup_20260101.sql -``` - ---- - -## 六、故障排查 - -### 6.1 容器无法启动 - -```bash -# 查看容器日志 -docker compose -f docker-compose.dify.yml logs baodan-api - -# 查看容器详细信息 -docker inspect baodanagent-baodan-api-1 -``` - -### 6.2 数据库连接失败 - -```bash -# 检查数据库状态 -docker exec baodanagent-db-1 pg_isready -U postgres - -# 进入数据库检查 -docker exec -it baodanagent-db-1 psql -U postgres -d baodan -``` - -### 6.3 Redis 连接失败 - -```bash -# 检查 Redis 状态 -docker exec baodanagent-redis-1 redis-cli ping - -# 测试 Redis 连接 -docker exec baodanagent-redis-1 redis-cli set test 1 -docker exec baodanagent-redis-1 redis-cli get test -``` - -### 6.4 端口被占用 - -```bash -# 查看端口占用 -netstat -tlnp | grep -E '3000|5001|9080|5433|6380' - -# 停止占用端口的进程 -kill -9 -``` - -### 6.5 磁盘空间不足 - -```bash -# 查看磁盘使用 -df -h - -# 清理 Docker 缓存 -docker system prune -a -f - -# 查看 Docker 占用空间 -docker system df -``` - ---- - -## 七、生产环境建议 - -### 7.1 安全加固 - -1. **修改所有默认密码** -2. **限制数据库端口访问**：只允许应用访问 -3. **启用防火墙**：只开放必要端口 -4. **定期备份数据库** -5. **使用非 root 用户运行 Docker** - -### 7.2 性能优化 - -1. **增加 Worker 数量**：修改 docker-compose.yml 中的 Celery 并发数 -2. **配置 Redis 持久化**：确保数据不丢失 -3. **使用 SSD 存储**：提升数据库性能 -4. **配置日志轮转**：避免日志占满磁盘 - -### 7.3 监控 - -```bash -# 查看容器资源使用 -docker stats - -# 查看容器进程 -docker top baodanagent-baodan-api-1 -``` - ---- - -## 八、卸载 - -```bash -# 停止所有服务 -docker compose -f docker-compose.dify.yml down -v - -# 删除数据卷 -docker volume rm baodanagent_baodan_pg_data baodanagent_baodan_redis_data - -# 删除镜像 -docker image rm baodanagent-baodan-api:latest - -# 删除部署文件 -rm -rf /opt/baodanagent-* -``` - ---- - -## 附录：端口清单 - -| 端口 | 服务 | 说明 | -|------|------|------| -| 3000 | BaoDan Web | 管理后台 | -| 5001 | BaoDan API | 后端接口 | -| 5002 | Plugin Daemon | 插件服务 | -| 5003 | Plugin Install | 插件安装 | -| 5433 | PostgreSQL | 数据库 | -| 6380 | Redis | 缓存 | -| 8194 | Sandbox | 代码沙箱 | -| 9080 | 保险前端 | 客服界面 |