wsb1224
b8c4e8b672
修复 PPT 异步任务无法生成的问题，包括任务变量引用错误、失败状态回写、心跳缺失任务恢复。 脱敏改为保司/产品后台统一配置，生成端不再让用户选择；任务创建时保存策略快照。 保司支持独立控制 PPT、海报 Logo 显示。 PPT 核验新增吸烟状态、币种及三个条件字段。 利益演示、退保提取调整为警告，不再阻止生成。 PPT 生成完成后可以直接返回数据核验页修改。 建立不同险种、单图/长图共六套海报字段画像。 PPT“生成场景”支持后台新增、启停和删除。 保司、产品、PPT 模板、文案模板均支持安全删除。 内置模板禁止删除，只允许停用；存在关联数据时拒绝危险删除。 补充策略变更及删除审计日志。 更新 API 文档、部署文档及修复计划实施记录。 关键交付文件： [数据库迁移 migrate_027.py](D:/work/code/python/coding/baodanagent/api/insurance/db/migrate_027.py) [海报字段画像 field_profiles.py](D:/work/code/python/coding/baodanagent/api/insurance/poster/field_profiles.py) [动态场景服务 scenarios.py](D:/work/code/python/coding/baodanagent/api/insurance/ppt/scenarios.py) [新增回归测试](D:/work/code/python/coding/baodanagent/tests/ppt_poster_optimization_test.py) [优化修复计划书](D:/work/code/python/coding/baodanagent/docs/保险智能客服系统_PPT与海报优化修复计划书_20260731.md) 验证结果： 核心链路测试：37 passed，1 skipped 扩展回归测试：140 passed PPT 渲染器测试：6 passed 前端生产构建：通过 Python 编译检查：通过 完整测试集：190 passed，1 failed 唯一失败为 tests/test_chat_save.py::test_chat_logs_query 未建立 Flask application context，与本次 PPT/海报链路无关。
584 lines
16 KiB
Markdown
584 lines
16 KiB
Markdown
# 保险智能客服系统 - 完整部署文档
|
||
|
||
## 一、系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 用户浏览器 / 企微 H5 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Nginx 反向代理（可选） │
|
||
│ 端口：80 / 443 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────────────┐ ┌──────────────────────────┐
|
||
│ Vue 前端（静态文件） │ │ Dify API 服务 │
|
||
│ 端口：8080 │ │ 端口：5001 │
|
||
│ 或 Nginx 托管 │ │ 含 insurance 模块 │
|
||
└──────────────────────────┘ └──────────────────────────┘
|
||
│
|
||
┌───────────────────┼───────────────────┐
|
||
▼ ▼ ▼
|
||
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||
│ PostgreSQL │ │ Redis │ │ Sandbox │
|
||
│ 端口：5432 │ │ 端口：6379 │ │ 端口：8194 │
|
||
│ 含 pgvector │ │ │ │ 代码执行沙箱 │
|
||
└──────────────────┘ └──────────────────┘ └──────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、环境要求
|
||
|
||
### 2.1 服务器配置
|
||
|
||
| 项目 | 最低配置 | 推荐配置 |
|
||
|------|----------|----------|
|
||
| CPU | 2 核 | 4 核 |
|
||
| 内存 | 4 GB | 8 GB |
|
||
| 硬盘 | 50 GB | 100 GB |
|
||
| 系统 | Ubuntu 20.04 / CentOS 7 | Ubuntu 22.04 |
|
||
|
||
### 2.2 软件依赖
|
||
|
||
| 软件 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Docker | >= 20.10 | 容器运行环境 |
|
||
| Docker Compose | >= 2.0 | 容器编排 |
|
||
| Node.js | >= 18（可选） | 前端开发/构建 |
|
||
| pnpm | >= 8（可选） | 前端包管理 |
|
||
|
||
### 2.3 端口规划
|
||
|
||
| 端口 | 服务 | 说明 |
|
||
|------|------|------|
|
||
| 80 | Nginx | HTTP 访问（可选） |
|
||
| 443 | Nginx | HTTPS 访问（可选） |
|
||
| 3000 | Dify Web | Dify 管理后台 |
|
||
| 5001 | Dify API | 后端 API 服务 |
|
||
| 5432 | PostgreSQL | 数据库 |
|
||
| 6379 | Redis | 缓存 |
|
||
| 8194 | Sandbox | 代码执行沙箱 |
|
||
| 8080 | Vue 前端 | 开发服务器（生产环境不需要） |
|
||
|
||
---
|
||
|
||
## 三、目录结构
|
||
|
||
```
|
||
baodanagent/
|
||
├── api/ # 后端代码
|
||
│ └── insurance/ # 自研保险模块
|
||
│ ├── auth/ # 认证模块
|
||
│ ├── chat/ # 对话模块
|
||
│ ├── recommend/ # 推荐模块
|
||
│ ├── admin/ # 管理模块
|
||
│ ├── stats/ # 统计模块
|
||
│ ├── kb/ # 知识库模块
|
||
│ ├── wecom/ # 企微模块
|
||
│ ├── middleware/ # 中间件
|
||
│ ├── models/ # 数据模型
|
||
│ └── utils/ # 工具函数
|
||
│
|
||
├── frontend/ # Vue 前端
|
||
│ ├── src/
|
||
│ │ ├── pages/ # 页面组件
|
||
│ │ ├── components/ # 通用组件
|
||
│ │ ├── composables/ # 组合函数
|
||
│ │ ├── utils/ # 工具函数
|
||
│ │ └── types/ # TypeScript 类型
|
||
│ ├── dist/ # 构建产物
|
||
│ ├── package.json
|
||
│ └── vite.config.ts
|
||
│
|
||
├── dify-main/ # Dify 源码（参考用）
|
||
│
|
||
├── deploy/ # 部署配置
|
||
│ ├── sql/
|
||
│ │ └── init.sql # 数据库初始化脚本
|
||
│ ├── nginx.conf # Nginx 配置
|
||
│ └── workflow_recommend.yml # Workflow DSL
|
||
│
|
||
├── scripts/ # 脚本
|
||
│ ├── patch_app.py # 注册路由脚本
|
||
│ ├── auto_init.py # 自动初始化脚本
|
||
│ ├── entrypoint.sh # 容器入口脚本
|
||
│ ├── import_workflow.py # Workflow 导入脚本
|
||
│ └── upload_kb_docs.py # 知识库文档上传脚本
|
||
│
|
||
├── docker-compose.dify.yml # Docker Compose 主配置
|
||
├── Dockerfile.dify-custom # API 镜像
|
||
├── Dockerfile.web-custom # Web 镜像
|
||
└── .env.example # 环境变量示例
|
||
```
|
||
|
||
---
|
||
|
||
## 四、快速部署（Docker Compose）
|
||
|
||
### 4.1 克隆代码
|
||
|
||
```bash
|
||
git clone <仓库地址> baodanagent
|
||
cd baodanagent
|
||
```
|
||
|
||
### 4.2 修改配置
|
||
|
||
编辑 `docker-compose.dify.yml`，修改以下配置：
|
||
|
||
```yaml
|
||
# 数据库密码（必须修改）
|
||
POSTGRES_PASSWORD: your_strong_password
|
||
|
||
# 管理员账号（必须修改）
|
||
ADMIN_EMAIL: admin@yourdomain.com
|
||
ADMIN_PASSWORD: your_strong_password
|
||
|
||
# JWT 密钥（必须修改）
|
||
SECRET_KEY: your_random_secret_key_at_least_32_chars
|
||
|
||
# 访客模式（true=免登录，false=需要登录）
|
||
GUEST_MODE: "true"
|
||
```
|
||
|
||
### 4.3 构建并启动
|
||
|
||
```bash
|
||
# 构建自定义镜像
|
||
docker compose -f docker-compose.dify.yml build
|
||
|
||
# 启动所有服务
|
||
docker compose -f docker-compose.dify.yml up -d
|
||
|
||
# 查看状态
|
||
docker ps
|
||
|
||
# 查看日志
|
||
docker compose -f docker-compose.dify.yml logs -f
|
||
```
|
||
|
||
### 4.4 初始化数据库
|
||
|
||
```bash
|
||
# 等待 PostgreSQL 启动完成（约 10 秒）
|
||
sleep 10
|
||
|
||
# 安装 pgvector 扩展
|
||
docker exec baodanagent-db-1 psql -U postgres -d baodan -c "CREATE EXTENSION IF NOT EXISTS vector;"
|
||
```
|
||
|
||
### 4.5 访问系统
|
||
|
||
| 服务 | 地址 | 说明 |
|
||
|------|------|------|
|
||
| Dify 后台 | http://服务器IP:3000 | 管理后台 |
|
||
| API 服务 | http://服务器IP:5001 | 后端接口 |
|
||
|
||
---
|
||
|
||
## 五、前端部署
|
||
|
||
### 5.1 开发环境
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 启动开发服务器
|
||
pnpm dev
|
||
|
||
# 访问 http://localhost:8080
|
||
```
|
||
|
||
### 5.2 生产环境构建
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 构建生产版本
|
||
pnpm build
|
||
|
||
# 构建产物在 frontend/dist/ 目录
|
||
```
|
||
|
||
### 5.3 Nginx 部署前端
|
||
|
||
将 `frontend/dist/` 目录复制到服务器，配置 Nginx：
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
|
||
# 前端静态文件
|
||
location / {
|
||
root /path/to/frontend/dist;
|
||
index index.html;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# API 代理
|
||
location /insurance/ {
|
||
proxy_pass http://localhost:5001;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
}
|
||
|
||
# Dify API 代理
|
||
location /v1/ {
|
||
proxy_pass http://localhost:5001;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
|
||
# Dify 后台代理
|
||
location /console/ {
|
||
proxy_pass http://localhost:3000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
|
||
# WebSocket 支持（对话功能需要）
|
||
location /v1/chat-messages {
|
||
proxy_pass http://localhost:5001;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
proxy_set_header Host $host;
|
||
proxy_read_timeout 300s;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.4 HTTPS 配置（推荐）
|
||
|
||
```bash
|
||
# 安装 Certbot
|
||
apt install certbot python3-certbot-nginx
|
||
|
||
# 申请证书
|
||
certbot --nginx -d your-domain.com
|
||
|
||
# 自动续期
|
||
certbot renew --dry-run
|
||
```
|
||
|
||
---
|
||
|
||
## 六、后端配置
|
||
|
||
### 6.1 环境变量说明
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `POSTGRES_PASSWORD` | 数据库密码 | taiyi1224 |
|
||
| `ADMIN_EMAIL` | 管理员邮箱 | taiyi@baodan.com |
|
||
| `ADMIN_PASSWORD` | 管理员密码 | taiyi1224 |
|
||
| `SECRET_KEY` | JWT 密钥 | baodan-secret-key-2026 |
|
||
| `GUEST_MODE` | 访客模式 | true |
|
||
| `BAODAN_CHAT_API_KEY` | 对话 API Key | 需要创建后填入 |
|
||
| `BAODAN_WORKFLOW_API_KEY` | 推荐 API Key | 需要创建后填入 |
|
||
| `BAODAN_API_URL` | API 地址 | http://baodan-api:5001 |
|
||
| `INSURANCE_STORAGE_ROOT` | 保险模块共享持久化目录，API 与 Worker 必须一致 | /app/api/storage/insurance |
|
||
| `POSTER_USER_MANUAL_UPLOAD_ENABLED` | 是否开放用户上传产品小册子和“我的资料” | true |
|
||
|
||
### 6.2 创建 API Key
|
||
|
||
#### 创建对话应用 API Key
|
||
|
||
```bash
|
||
# 登录 Dify 后台
|
||
# 进入「工作室」→「baodna」应用
|
||
# 点击「访问 API」→「创建 API Key」
|
||
# 复制 API Key，填入 docker-compose.dify.yml 的 BAODAN_CHAT_API_KEY
|
||
```
|
||
|
||
#### 创建 Workflow API Key
|
||
|
||
```bash
|
||
# 进入「工作室」→「产品推荐方案生成」应用
|
||
# 点击「访问 API」→「创建 API Key」
|
||
# 复制 API Key，填入 docker-compose.dify.yml 的 BAODAN_WORKFLOW_API_KEY
|
||
```
|
||
|
||
### 6.3 重启服务
|
||
|
||
```bash
|
||
# 修改配置后重启
|
||
docker compose -f docker-compose.dify.yml restart baodan-api baodan-worker
|
||
|
||
# 或重新构建
|
||
docker compose -f docker-compose.dify.yml up -d --build baodan-api baodan-worker
|
||
```
|
||
|
||
---
|
||
|
||
## 七、知识库配置
|
||
|
||
### 7.1 创建知识库
|
||
|
||
1. 访问 Dify 后台：http://服务器IP:3000
|
||
2. 登录（使用配置的管理员账号）
|
||
3. 点击「知识库」→「创建知识库」
|
||
4. 名称：保险产品知识库
|
||
5. 索引方式：高质量（推荐）
|
||
|
||
### 7.2 上传文档
|
||
|
||
支持格式：PDF、Word、TXT、Markdown
|
||
|
||
建议按险种分类上传：
|
||
- 重疾险产品条款
|
||
- 医疗险产品条款
|
||
- 意外险产品条款
|
||
- 寿险产品条款
|
||
- 年金险产品条款
|
||
|
||
### 7.3 绑定到 Workflow
|
||
|
||
1. 进入「工作室」→「产品推荐方案生成」
|
||
2. 点击「知识库检索」节点
|
||
3. 选择刚创建的知识库
|
||
4. 保存并发布
|
||
|
||
---
|
||
|
||
## 八、Workflow 配置
|
||
|
||
### 8.1 导入 Workflow
|
||
|
||
```bash
|
||
# 使用脚本导入
|
||
python scripts/import_workflow.py --base-url http://localhost:5001
|
||
|
||
# 或手动导入：
|
||
# 1. 访问 Dify 后台
|
||
# 2. 点击「创建应用」→「导入 DSL」
|
||
# 3. 选择 deploy/workflow_recommend.yml
|
||
```
|
||
|
||
### 8.2 配置 Workflow
|
||
|
||
导入后需要配置：
|
||
|
||
1. **知识库检索节点**：绑定知识库
|
||
2. **LLM 节点**：选择模型（如 DeepSeek）
|
||
3. **发布 Workflow**
|
||
|
||
### 8.3 创建 API Key
|
||
|
||
1. 进入「产品推荐方案生成」应用
|
||
2. 点击「访问 API」→「创建 API Key」
|
||
3. 复制 API Key，更新配置
|
||
|
||
---
|
||
|
||
## 九、数据库管理
|
||
|
||
### 9.1 连接数据库
|
||
|
||
```bash
|
||
# 进入数据库容器
|
||
docker exec -it baodanagent-db-1 psql -U postgres -d baodan
|
||
|
||
# 查看表
|
||
\dt
|
||
|
||
# 查看用户表
|
||
SELECT * FROM wecom_user_mapping;
|
||
|
||
# 退出
|
||
\q
|
||
```
|
||
|
||
### 9.2 创建用户
|
||
|
||
```bash
|
||
# 生成密码哈希
|
||
docker exec baodanagent-baodan-api-1 python -c "
|
||
import bcrypt
|
||
password = 'your_password'
|
||
hashed = bcrypt.hashpw(password.encode(), bcrypt.gensalt())
|
||
print(hashed.decode())
|
||
"
|
||
|
||
# 插入用户
|
||
docker exec baodanagent-db-1 psql -U postgres -d baodan -c "
|
||
INSERT INTO wecom_user_mapping (wecom_userid, internal_user_id, username, password_hash, role, status)
|
||
VALUES ('local_user', 'user001', 'admin', '\$2b\$12\$...', 'super_admin', 'active');
|
||
"
|
||
```
|
||
|
||
### 9.3 数据备份
|
||
|
||
```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
|
||
```
|
||
|
||
---
|
||
|
||
## 十、常见问题
|
||
|
||
### 10.1 服务无法启动
|
||
|
||
```bash
|
||
# 查看日志
|
||
docker compose -f docker-compose.dify.yml logs baodan-api
|
||
|
||
# 检查端口占用
|
||
netstat -tlnp | grep 5001
|
||
|
||
# 重启服务
|
||
docker compose -f docker-compose.dify.yml restart
|
||
```
|
||
|
||
### 10.2 数据库连接失败
|
||
|
||
```bash
|
||
# 检查数据库状态
|
||
docker exec baodanagent-db-1 pg_isready
|
||
|
||
# 检查数据库日志
|
||
docker logs baodanagent-db-1
|
||
```
|
||
|
||
### 10.3 前端无法访问 API
|
||
|
||
检查：
|
||
1. API 服务是否启动：`docker ps | grep baodan-api`
|
||
2. 端口是否开放：`netstat -tlnp | grep 5001`
|
||
3. 防火墙是否放行：`ufw allow 5001`
|
||
|
||
### 10.4 Workflow 执行失败
|
||
|
||
```bash
|
||
# 检查 Sandbox 状态
|
||
docker logs baodanagent-sandbox-1
|
||
|
||
# 检查 API 日志
|
||
docker logs baodanagent-baodan-api-1 --tail 50
|
||
```
|
||
|
||
### 10.5 知识库检索无结果
|
||
|
||
1. 确认文档已上传并索引完成
|
||
2. 确认 Workflow 已绑定知识库
|
||
3. 检查检索参数（Top-K、Score 阈值）
|
||
|
||
---
|
||
|
||
## 十一、运维命令
|
||
|
||
### 11.1 服务管理
|
||
|
||
```bash
|
||
# 启动所有服务
|
||
docker compose -f docker-compose.dify.yml up -d
|
||
|
||
# 停止所有服务
|
||
docker compose -f docker-compose.dify.yml down
|
||
|
||
# 重启所有服务
|
||
docker compose -f docker-compose.dify.yml restart
|
||
|
||
# 重启单个服务
|
||
docker compose -f docker-compose.dify.yml restart baodan-api
|
||
|
||
# 重新构建并启动
|
||
docker compose -f docker-compose.dify.yml up -d --build
|
||
|
||
# 查看服务状态
|
||
docker ps
|
||
|
||
# 查看服务日志
|
||
docker compose -f docker-compose.dify.yml logs -f baodan-api
|
||
```
|
||
|
||
### 11.2 资源监控
|
||
|
||
```bash
|
||
# 查看资源使用
|
||
docker stats
|
||
|
||
# 查看磁盘使用
|
||
docker system df
|
||
|
||
# 清理无用资源
|
||
docker system prune -a
|
||
```
|
||
|
||
### 11.3 更新代码
|
||
|
||
```bash
|
||
# 拉取最新代码
|
||
git pull
|
||
|
||
# 重新构建
|
||
docker compose -f docker-compose.dify.yml up -d --build baodan-api
|
||
|
||
# 重启前端（如果使用 pnpm dev）
|
||
cd frontend && pnpm build
|
||
```
|
||
|
||
### 11.1 2026-07-31 PPT/海报升级检查
|
||
|
||
本版本新增 `migrate_027.py`，应用启动时由 `insurance.db.run_migrations()` 自动执行。生产升级前必须先备份数据库，升级后检查：
|
||
|
||
```bash
|
||
# 查看 API 日志，确认出现 migrate_027 完成记录
|
||
docker compose -f docker-compose.dify.yml logs baodan-api | grep migrate_027
|
||
|
||
# 重启 Worker，确保加载新的 PPT/海报任务代码
|
||
docker compose -f docker-compose.dify.yml restart baodan-worker
|
||
```
|
||
|
||
迁移内容包括保司/产品脱敏开关、保司 Logo 开关、四类后台对象软删除字段，以及 `insurance_ppt_scenarios` 动态场景表和内置场景种子。回滚代码前不要删除新增列或场景表；旧版本会忽略这些字段。
|
||
|
||
---
|
||
|
||
## 十二、安全建议
|
||
|
||
### 12.1 必须修改的配置
|
||
|
||
- [ ] 数据库密码
|
||
- [ ] 管理员密码
|
||
- [ ] JWT 密钥
|
||
- [ ] API Key
|
||
|
||
### 12.2 网络安全
|
||
|
||
- [ ] 配置防火墙，只开放必要端口
|
||
- [ ] 使用 HTTPS
|
||
- [ ] 限制数据库只允许内网访问
|
||
|
||
### 12.3 数据安全
|
||
|
||
- [ ] 定期备份数据库
|
||
- [ ] 启用日志审计
|
||
- [ ] 敏感信息加密存储
|
||
|
||
---
|
||
|
||
## 十三、联系方式
|
||
|
||
如有问题，请联系开发团队。
|
||
|
||
---
|
||
|
||
**文档版本**：v1.1
|
||
**更新日期**：2026-07-31
|