baodan/docs/宝塔面板部署指南.md

# 保险智能客服系统 - 宝塔面板部署指南

## 一、环境准备

### 1.1 宝塔面板安装

如果还没有安装宝塔面板：

```bash
# CentOS 7/8
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh

# 安装完成后会显示：
# 外网面板地址: http://xxx.xxx.xxx.xxx:8888/xxxxx
# 内网面板地址: http://192.168.x.x:8888/xxxxx
# username: xxxx
# password: xxxx
```

### 1.2 安装 Docker（宝塔面板操作）

1. 登录宝塔面板
2. 左侧菜单 → **软件商店**
3. 搜索 **Docker管理器** → 安装
4. 等待安装完成

或者命令行安装：

```bash
# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 启动 Docker
systemctl start docker
systemctl enable docker

# 安装 Docker Compose
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# 验证
docker --version
docker-compose --version
```

### 1.3 开放端口（宝塔面板操作）

1. 左侧菜单 → **安全**
2. 放行以下端口：

| 端口 | 说明 |
|------|------|
| 80 | HTTP（Nginx） |
| 443 | HTTPS |
| 3000 | Dify 后台 |
| 5001 | API 服务 |
| 8080 | Vue 前端（开发用） |

---

## 二、上传代码

### 2.1 方式一：宝塔面板上传

1. 左侧菜单 → **文件**
2. 进入 `/www/wwwroot/` 目录
3. 点击 **上传** → 选择项目压缩包
4. 解压：`unzip baodanagent.zip`

### 2.2 方式二：Git 克隆

```bash
cd /www/wwwroot/
git clone <你的仓库地址> baodanagent
cd baodanagent
```

### 2.3 方式三：SCP 上传

```bash
# 本地执行
scp -r ./baodanagent root@服务器IP:/www/wwwroot/
```

---

## 三、配置修改

### 3.1 修改 Docker Compose 配置

```bash
cd /www/wwwroot/baodanagent
vi docker-compose.dify.yml
```

修改以下配置：

```yaml
services:
  db:
    environment:
      POSTGRES_PASSWORD: "你的强密码"  # 必须修改！

  baodan-api:
    environment:
      # 管理员账号
      ADMIN_EMAIL: "admin@yourdomain.com"
      ADMIN_PASSWORD: "你的强密码"

      # JWT 密钥（至少 32 位随机字符串）
      SECRET_KEY: "your_random_secret_key_at_least_32_chars"

      # 访客模式（true=免登录，false=需要登录）
      GUEST_MODE: "true"

      # API Key（后续配置后填入）
      BAODAN_CHAT_API_KEY: "app-placeholder"
      BAODAN_WORKFLOW_API_KEY: "app-placeholder"

    ports:
      - "5001:5001"

  baodan-web:
    ports:
      - "3000:3000"
```

### 3.2 生成随机密钥

```bash
# 生成 32 位随机字符串
openssl rand -base64 32
```

---

## 四、构建并启动

### 4.1 构建镜像

```bash
cd /www/wwwroot/baodanagent

# 构建 API 镜像（包含 insurance 模块）
docker-compose -f docker-compose.dify.yml build

# 预计耗时 3-5 分钟
```

### 4.2 启动服务

```bash
# 启动所有服务
docker-compose -f docker-compose.dify.yml up -d

# 查看状态
docker ps

# 应该看到以下容器：
# baodanagent-db-1
# baodanagent-redis-1
# baodanagent-baodan-api-1
# baodanagent-baodan-web-1
# baodanagent-baodan-worker-1
# baodanagent-sandbox-1
# baodanagent-plugin_daemon-1
```

### 4.3 初始化数据库

```bash
# 等待数据库启动（约 10 秒）
sleep 10

# 安装 pgvector 扩展
docker exec baodanagent-db-1 psql -U postgres -d baodan -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 验证
docker exec baodanagent-db-1 psql -U postgres -d baodan -c "SELECT * FROM pg_extension WHERE extname = 'vector';"
```

### 4.4 查看日志

```bash
# 查看 API 日志
docker logs baodanagent-baodan-api-1 --tail 50

# 实时查看日志
docker logs -f baodanagent-baodan-api-1
```

---

## 五、配置 Dify

### 5.1 访问 Dify 后台

打开浏览器访问：`http://服务器IP:3000`

首次访问会进入初始化页面：
- 邮箱：`admin@yourdomain.com`（docker-compose 中配置的）
- 密码：`你的强密码`
- 名称：随意填写
- 工作区名称：随意填写

### 5.2 配置模型

1. 点击右上角头像 → **设置**
2. 左侧菜单 → **模型供应商**
3. 点击 **添加模型供应商**
4. 选择 **OpenAI-API-Compatible**
5. 填入配置：
   - API Base URL：你的模型 API 地址
   - API Key：你的模型 API Key
6. 保存

### 5.3 创建对话应用

1. 左侧菜单 → **工作室**
2. 点击 **创建应用** → **聊天助手**
3. 名称：`保险智能客服`
4. 模型：选择刚才配置的模型
5. 系统提示词：

```
你是一名专业的保险智能客服助手，能够回答用户关于保险产品的各种问题。
请用专业、友好的语气回答用户的问题。
```

6. 点击 **发布**

### 5.4 创建 API Key

1. 进入刚创建的应用
2. 左侧菜单 → **访问 API**
3. 点击 **创建 API Key**
4. 复制 API Key（格式：`app-xxxxxxxxxxxx`）

### 5.5 更新配置

```bash
# 编辑 docker-compose.dify.yml
vi /www/wwwroot/baodanagent/docker-compose.dify.yml

# 将 BAODAN_CHAT_API_KEY 修改为刚才创建的 API Key

# 重启 API 服务
docker-compose -f docker-compose.dify.yml restart baodan-api
```

---

## 六、配置知识库

### 6.1 创建知识库

1. 左侧菜单 → **知识库**
2. 点击 **创建知识库**
3. 名称：`保险产品知识库`
4. 描述：`各类保险产品条款和费率信息`
5. 索引方式：**高质量**

### 6.2 上传文档

1. 点击 **上传文档**
2. 选择保险产品条款文件（支持 PDF、Word、TXT、Markdown）
3. 分段设置：自动分段
4. 等待索引完成

### 6.3 配置 Workflow

1. 左侧菜单 → **工作室**
2. 点击 **创建应用** → **导入 DSL**
3. 选择 `deploy/workflow_recommend.yml`
4. 导入后：
   - 点击 **知识库检索** 节点 → 绑定刚创建的知识库
   - 点击 **方案生成** 节点 → 选择模型
5. 点击 **发布**
6. 创建 API Key，更新 `BAODAN_WORKFLOW_API_KEY`

---

## 七、前端部署

### 7.1 方式一：Nginx 静态部署（推荐）

#### 构建前端

```bash
cd /www/wwwroot/baodanagent/frontend

# 安装 Node.js（如果没有）
curl -fsSL https://rpm.nodesource.com/setup_18.x | bash -
yum install -y nodejs

# 安装 pnpm
npm install -g pnpm

# 安装依赖
pnpm install

# 构建
pnpm build

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

#### 配置 Nginx（宝塔面板操作）

1. 左侧菜单 → **网站**
2. 点击 **添加站点**
3. 填入：
   - 域名：`your-domain.com` 或 `服务器IP`
   - 根目录：`/www/wwwroot/baodanagent/frontend/dist`
4. 点击 **提交**

#### 修改 Nginx 配置

1. 点击站点名称 → **配置**
2. 替换为以下内容：

```nginx
server {
    listen 80;
    server_name your-domain.com;  # 或服务器 IP

    root /www/wwwroot/baodanagent/frontend/dist;
    index index.html;

    # 前端路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /insurance/ {
        proxy_pass http://127.0.0.1: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://127.0.0.1:5001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Dify 后台代理
    location /console/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # WebSocket 支持
    location /v1/chat-messages {
        proxy_pass http://127.0.0.1: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;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 7d;
        add_header Cache-Control "public, immutable";
    }
}
```

3. 保存并重启 Nginx

### 7.2 方式二：PM2 部署（开发模式）

```bash
cd /www/wwwroot/baodanagent/frontend

# 安装依赖
pnpm install

# 安装 PM2
npm install -g pm2

# 启动开发服务器
pm2 start pnpm --name "insurance-frontend" -- dev

# 设置开机自启
pm2 save
pm2 startup

# 查看状态
pm2 status

# 查看日志
pm2 logs insurance-frontend
```

---

## 八、创建用户

```bash
# 生成密码哈希
docker exec baodanagent-baodan-api-1 python -c "
import bcrypt
password = 'admin123456'
hashed = bcrypt.hashpw(password.encode(), bcrypt.gensalt())
print(hashed.decode())
"

# 输出类似：$2b$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 创建用户（替换哈希值）
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_admin', 'admin001', 'admin', '\$2b\$12\$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'super_admin', 'active');
"
```

---

## 九、SSL 证书配置（HTTPS）

### 9.1 宝塔面板申请证书

1. 左侧菜单 → **网站**
2. 点击站点名称 → **SSL**
3. 选择 **Let's Encrypt**
4. 勾选域名 → **申请**
5. 开启 **强制 HTTPS**

### 9.2 手动上传证书

1. 左侧菜单 → **网站**
2. 点击站点名称 → **SSL**
3. 选择 **其他证书**
4. 粘贴证书内容和私钥
5. 保存并启用

---

## 十、常见问题

### 10.1 Docker 启动失败

```bash
# 检查 Docker 状态
systemctl status docker

# 重启 Docker
systemctl restart docker

# 查看详细日志
journalctl -u docker -n 100
```

### 10.2 端口被占用

```bash
# 查看端口占用
netstat -tlnp | grep 5001

# 杀掉进程
kill -9 <PID>

# 或修改 docker-compose 使用其他端口
```

### 10.3 内存不足

```bash
# 查看内存
free -h

# 清理 Docker 缓存
docker system prune -a

# 添加 swap（如果没有）
dd if=/dev/zero of=/swapfile bs=1M count=4096
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile swap swap defaults 0 0' >> /etc/fstab
```

### 10.4 数据库连接失败

```bash
# 检查数据库容器
docker ps | grep db

# 查看数据库日志
docker logs baodanagent-db-1

# 重启数据库
docker-compose -f docker-compose.dify.yml restart db
```

### 10.5 Nginx 502 错误

```bash
# 检查 API 是否运行
docker ps | grep baodan-api

# 检查端口是否监听
netstat -tlnp | grep 5001

# 重启 API
docker-compose -f docker-compose.dify.yml restart baodan-api
```

---

## 十一、运维命令速查

```bash
# 进入项目目录
cd /www/wwwroot/baodanagent

# 启动所有服务
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 logs baodanagent-baodan-api-1 -f

# 进入容器
docker exec -it baodanagent-baodan-api-1 bash

# 查看资源使用
docker stats

# 备份数据库
docker exec baodanagent-db-1 pg_dump -U postgres baodan > /www/backup/db_$(date +%Y%m%d).sql

# 恢复数据库
docker exec -i baodanagent-db-1 psql -U postgres baodan < /www/backup/db_20260101.sql
```

---

## 十二、访问地址

部署完成后：

| 服务 | 地址 | 说明 |
|------|------|------|
| 前端页面 | http://你的域名 | 用户使用 |
| Dify 后台 | http://服务器IP:3000 | 管理后台 |
| API 接口 | http://服务器IP:5001 | 后端服务 |

---

**文档版本**：v1.0
**更新日期**：2026-06-18