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 克隆代码

```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