baodan/docs/部署文档_完整版.md

保险智能客服系统 - 完整部署文档

一、系统架构

┌─────────────────────────────────────────────────────────────────┐
│                        用户浏览器 / 企微 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 克隆代码

git clone <仓库地址> baodanagent
cd baodanagent

4.2 修改配置

编辑 docker-compose.dify.yml，修改以下配置：

# 数据库密码（必须修改）
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 构建并启动

# 构建自定义镜像
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 初始化数据库

# 等待 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 开发环境

cd frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 访问 http://localhost:8080

5.2 生产环境构建

cd frontend

# 安装依赖
pnpm install

# 构建生产版本
pnpm build

# 构建产物在 frontend/dist/ 目录

5.3 Nginx 部署前端

将 frontend/dist/ 目录复制到服务器，配置 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 配置（推荐）

# 安装 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

# 登录 Dify 后台
# 进入「工作室」→「baodna」应用
# 点击「访问 API」→「创建 API Key」
# 复制 API Key，填入 docker-compose.dify.yml 的 BAODAN_CHAT_API_KEY

创建 Workflow API Key

# 进入「工作室」→「产品推荐方案生成」应用
# 点击「访问 API」→「创建 API Key」
# 复制 API Key，填入 docker-compose.dify.yml 的 BAODAN_WORKFLOW_API_KEY

6.3 重启服务

# 修改配置后重启
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

# 使用脚本导入
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 连接数据库

# 进入数据库容器
docker exec -it baodanagent-db-1 psql -U postgres -d baodan

# 查看表
\dt

# 查看用户表
SELECT * FROM wecom_user_mapping;

# 退出
\q

9.2 创建用户

# 生成密码哈希
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 数据备份

# 备份数据库
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 服务无法启动

# 查看日志
docker compose -f docker-compose.dify.yml logs baodan-api

# 检查端口占用
netstat -tlnp | grep 5001

# 重启服务
docker compose -f docker-compose.dify.yml restart

10.2 数据库连接失败

# 检查数据库状态
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 执行失败

# 检查 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 服务管理

# 启动所有服务
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 资源监控

# 查看资源使用
docker stats

# 查看磁盘使用
docker system df

# 清理无用资源
docker system prune -a

11.3 更新代码

# 拉取最新代码
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() 自动执行。生产升级前必须先备份数据库，升级后检查：

# 查看 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