wanghanlin
/
RAG
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
本地 RAG 知识库
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
57 Commits
2 Branches
0 Tags
34 MiB
 
 
 
 
 
Tree: 6f854dde14
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6f854dde14'
${ noResults }
RAG/DEPLOY.md

22 KiB
Raw Blame History

AI 智能客服系统 Linux 部署详细教程

项目：AI 智能客服系统（Spring AI Alibaba + 通义千问 + PGVector） 适用服务器：Linux（CentOS 7/8、Ubuntu 20.04/22.04、Debian 等通用发行版） 部署方式：Docker 部署 PostgreSQL + PGVector 数据库，JDK 17 直接运行 Spring Boot Fat Jar 生成日期：2026-06-27

目录

  1. 部署架构与端口规划
  2. 服务器环境准备
  3. 安装 Docker 与 Docker Compose
  4. Docker 部署 PostgreSQL + PGVector 数据库
  5. 数据库初始化验证
  6. 后端项目打包
  7. 上传与生产配置
  8. 启动后端服务
  9. 配置 AI 大模型（必做）
  10. 开机自启：systemd 服务
  11. Nginx 反向代理（可选）
  12. 日常运维与排错
  13. 附：一键部署脚本

1. 部署架构与端口规划

[浏览器/客户端]
       │ :80 / :443（可选 Nginx）
       ▼
[ Linux 服务器 ]
   ├── Docker 容器: postgres-pgvector   :5432  ← 数据库
   └── JDK 17 进程: yu-ai-agent.jar     :9090  ← 后端服务（含前端静态页面）
组件 端口 说明
Spring Boot 后端 9090 API + 前端管理页面（同源）
PostgreSQL 5432 仅容器内 / 本机访问，不对公网开放

关键说明（务必先读）

  • 本项目前端页面已打包进 jar（位于 src/main/resources/static/），部署时无需单独部署前端，访问 http://服务器IP:9090/index.html 即可。
  • 数据库表（knowledge_category、knowledge_document、ai_model_config、chat_message 等）由 DatabaseInitConfig 在应用启动时自动创建，向量表 vector_store 由 PgVectorStore 自动创建（initializeSchema=true），无需手动执行 SQL。
  • application.yml 中 spring.ai.dashscope.enabled: false，DashScope 自动配置已关闭；即便没有 API Key 也能正常启动服务，AI 功能在「AI 大模型配置管理」页面填入 Key 后热切换生效。
  • 模型名称、温度、最大 Token、API Key 等参数全部在前端页面 / DB ai_model_config 表中管理，yml 仅保留可选的种子 api-key。

2. 服务器环境准备

2.1 系统要求

项目 要求
OS Linux x86_64（CentOS 7+ / Ubuntu 20.04+）
CPU/内存 建议 2 核 4G 起步（知识库向量化较耗内存）
磁盘 20G+（文档、向量数据）
网络 服务器需能访问 dashscope.aliyuncs.com（通义千问）等 AI 提供商 API

2.2 基础工具安装

# Ubuntu / Debian
sudo apt update && sudo apt install -y wget curl vim tar unzip net-tools

# CentOS / RHEL
sudo yum install -y wget curl vim tar unzip net-tools

2.3 防火墙放行端口

# Ubuntu (ufw)
sudo ufw allow 9090/tcp
sudo ufw reload

# CentOS (firewalld)
sudo firewall-cmd --permanent --add-port=9090/tcp
sudo firewall-cmd --reload

若部署在云服务器（阿里云/腾讯云等），还需在安全组中放行 9090 端口。

3. 安装 Docker 与 Docker Compose

3.1 一键安装 Docker

# 使用阿里云镜像加速安装（国内推荐）
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

# 启动并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证
docker --version
docker compose version

3.2 配置 Docker 镜像加速（国内必做）

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://docker.mirrors.ustc.edu.cn"
  ]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

4. Docker 部署 PostgreSQL + PGVector 数据库

本项目原开发机使用 PostgreSQL + PGVector 扩展，部署时保持一致。pgvector/pgvector 镜像内置了 vector 扩展，开箱即用。

4.1 创建数据目录与 compose 文件

# 创建部署目录
sudo mkdir -p /opt/support-bot/{db,data,app,logs}
cd /opt/support-bot

# 创建 compose 文件
sudo tee /opt/support-bot/docker-compose.yml <<'EOF'
version: "3.8"

services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: support-bot-postgres
    restart: always
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: supportbot123
      POSTGRES_DB: support_bot
      TZ: Asia/Shanghai
    volumes:
      - /opt/support-bot/data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d support_bot"]
      interval: 10s
      timeout: 5s
      retries: 5
EOF

参数说明

  • pgvector/pgvector:pg16：内置 PGVector 扩展的 PostgreSQL 16 镜像（与开发机 PG 12+ 兼容，建议用 16）。
  • POSTGRES_DB: support_bot：自动创建本项目所需数据库。
  • POSTGRES_PASSWORD：请修改为强密码，并同步修改后端配置。
  • 数据持久化到宿主机 /opt/support-bot/data，容器重建不丢数据。

4.2 启动数据库

cd /opt/support-bot
sudo docker compose up -d

# 查看状态（应为 healthy）
sudo docker compose ps
sudo docker logs -f support-bot-postgres

4.3 在数据库中启用 vector 扩展

进入容器执行（PGVector 扩展需在目标库中显式启用）：

sudo docker exec -it support-bot-postgres psql -U postgres -d support_bot -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 验证扩展已安装
sudo docker exec -it support-bot-postgres psql -U postgres -d support_bot -c "\dx"

输出中应看到 vector 扩展。

说明：应用启动时 PgVectorStore 会自动创建 vector_store 表，但 vector 扩展本身需提前 CREATE EXTENSION 启用（上述命令已完成）。

5. 数据库初始化验证

确认数据库与扩展就绪：

# 列出数据库
sudo docker exec -it support-bot-postgres psql -U postgres -l

# 查看 vector 扩展
sudo docker exec -it support-bot-postgres psql -U postgres -d support_bot -c "SELECT extname FROM pg_extension;"

此时业务表（knowledge_document 等）尚不存在 —— 它们会在后端首次启动时由 DatabaseInitConfig 自动创建。无需手动建表。

6. 后端项目打包

6.1 方式 A：在本机（Windows）打包后上传（推荐）

项目根目录已含 mvnw，无需本机安装 Maven。

# 在项目根目录 D:\IdeaProjects\chat-bot 执行
./mvnw clean package -DskipTests

打包成功后，jar 位于：

D:\IdeaProjects\chat-bot\target\yu-ai-agent-0.0.1-SNAPSHOT.jar

application.yml 已被 .gitignore 排除，但 jar 中会包含本地 yml。打包前请确认 yml 中数据库地址已改为生产地址（见第 7 节），或使用外部配置覆盖（推荐）。

6.2 方式 B：在 Linux 服务器上打包

# 安装 JDK 17 与 Maven
# Ubuntu
sudo apt install -y openjdk-17-jdk maven
# CentOS
sudo yum install -y java-17-openjdk-devel maven

# 验证
java -version
mvn -version

# 上传源码或 git clone 后，在项目根目录执行
mvn clean package -DskipTests
# jar 同样生成在 target/ 目录

6.3 上传 jar 到服务器

# 在本机 Windows 执行（scp 或使用 WinSCP / FinalShell 等工具）
scp target/yu-ai-agent-0.0.1-SNAPSHOT.jar user@服务器IP:/opt/support-bot/app/

7. 上传与生产配置

7.1 安装 JDK 17（运行 jar 必需）

# Ubuntu / Debian
sudo apt install -y openjdk-17-jre-headless

# CentOS / RHEL
sudo yum install -y java-17-openjdk-headless

# 验证
java -version

7.2 准备外部配置文件（推荐，避免改 jar）

在服务器上创建生产配置，覆盖 jar 内的默认 yml。Spring Boot 启动时同目录下的 application.yml 会自动覆盖 jar 内配置。

sudo tee /opt/support-bot/app/application.yml <<'EOF'
# ==================== 服务端口 ====================
server:
  port: 9090

spring:
  ai:
    dashscope:
      # 关闭 DashScope 自动配置（本项目所有模型由 Factory 按 DB 活跃配置手动构建）
      enabled: false
      # 仅用于首次启动写入种子默认值；可留空，真正生效的 Key 在前端页面配置
      api-key:

  # ==================== 数据源配置（PostgreSQL + PGVector） ====================
  datasource:
    driver-class-name: org.postgresql.Driver
    # 指向本机 Docker 部署的 PostgreSQL
    url: jdbc:postgresql://127.0.0.1:5432/support_bot
    username: postgres
    password: supportbot123
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      idle-timeout: 300000
      connection-timeout: 20000

  sql:
    init:
      mode: never
      schema-locations: classpath:support-bot.sql
      continue-on-error: true
  servlet:
    multipart:
      max-file-size: 50MB
      max-request-size: 50MB

# ==================== MyBatis Plus 配置 ====================
mybatis-plus:
  type-aliases-package: com.wok.supportbot.entity
  mapper-locations: classpath*:mapper/**/*.xml
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
    map-underscore-to-camel-case: true
  global-config:
    db-config:
      logic-delete-field: isDelete
      logic-delete-value: true
      logic-not-delete-value: false
      id-type: assign_id

# ==================== 知识库文档处理配置 ====================
knowledge:
  chunk:
    chunk-size: 200
    overlap: 100
    min-chunk-size-chars: 10
    max-num-chunks: 5000
    keep-separator: true
  vector:
    # 向量维度，需与 Embedding 模型输出维度一致
    # 千问 text-embedding-v2: 1024 | 豆包 doubao-embedding-text-240515: 2048
    dimension: 1024
  role:
    strict-isolation: false

# ==================== Knife4j API 文档配置 ====================
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: default
      paths-to-match: /**
      packages-to-scan: com.wok.supportbot.controller

knife4j:
  enable: true
  setting:
    language: zh_cn
    swagger-model-name: 实体类列表

logging:
  level:
    root: INFO
    com.wok.supportbot: DEBUG
    org.springframework.ai: INFO
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: /opt/support-bot/logs/support-bot.log
EOF

关键修改点

  • datasource.url 改为 127.0.0.1:5432（指向本机 Docker 容器）。
  • datasource.password 与 docker-compose 中保持一致。
  • logging.file.name 输出日志到宿主机目录。
  • 生产环境建议将 com.wok.supportbot 日志级别从 DEBUG 调为 INFO。

7.3 目录结构最终如下

/opt/support-bot/
├── docker-compose.yml      # 数据库编排
├── data/                   # PG 数据持久化
├── logs/                   # 应用日志
└── app/
    ├── yu-ai-agent-0.0.1-SNAPSHOT.jar
    └── application.yml     # 外部配置（覆盖 jar 内默认值）

8. 启动后端服务

8.1 手动前台启动（首次验证用）

cd /opt/support-bot/app
java -jar yu-ai-agent-0.0.1-SNAPSHOT.jar

观察启动日志，应看到：

数据库初始化完成
... Tomcat started on port  9090 ...
... Started SupportBotApplication in x.xxx seconds ...

启动成功后业务表会自动创建，可用以下命令核对：

sudo docker exec -it support-bot-postgres psql -U postgres -d support_bot -c "\dt"

应能看到 chat_message、knowledge_category、knowledge_document、ai_model_config、vector_store、customer_service_role、customer_account、conversation_session 等表。

8.2 后台启动（生产用）

cd /opt/support-bot/app
nohup java -jar yu-ai-agent-0.0.1-SNAPSHOT.jar \
  --spring.config.additional-location=optional:file:./ \
  > /opt/support-bot/logs/startup.out 2>&1 &

# 查看进程
ps -ef | grep yu-ai-agent

# 查看日志
tail -f /opt/support-bot/logs/startup.out

8.3 访问验证

地址 说明
http://服务器IP:9090/index.html 前端管理页面
http://服务器IP:9090/doc.html Knife4j 接口文档

能打开管理页面即部署成功。AI 对话功能需先配置模型（下一步）。

9. 配置 AI 大模型（必做）

由于 application.yml 中 api-key 留空，首次启动时 ai_model_config 表会写入空 Key 的默认配置。调用 AI 功能前必须在前端填入真实 Key。

9.1 进入配置页面

打开 http://服务器IP:9090/index.html → 进入「AI 大模型配置管理」页面。

9.2 配置各应用类型

为以下 4 类应用分别填入 API Key 并激活（同一 App 类型仅一个激活）：

App 类型 用途 默认模型
CHAT 主对话 qwen-turbo
EMBEDDING 知识库向量化 text-embedding-v2
RAG_REWRITE RAG 查询重写 qwen-turbo

9.3 通义千问（DashScope）配置示例

  • 提供商：dashscope
  • API Key：在 DashScope 控制台 获取，格式 sk-xxxx
  • Base URL：留空（DashScope 内置）
  • EMBEDDING 类型需在「向量维度」填 1024（与 knowledge.vector.dimension 一致）

配置后热切换生效，无需重启。若切换非 1024 维的 Embedding 模型，需修改 application.yml 的 knowledge.vector.dimension 并重建 vector_store 表（见运维章节）。

9.4 其他提供商（可选）

支持 OpenAI 兼容提供商：DeepSeek / 豆包 / Kimi / 智谱 / OpenAI。在配置页选择对应 provider，填入 base_url 与 api_key 即可。

10. 开机自启：systemd 服务

10.1 创建服务文件

sudo tee /etc/systemd/system/support-bot.service <<'EOF'
[Unit]
Description=AI Support Bot Spring Boot Service
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/support-bot/app
ExecStart=/usr/bin/java -jar /opt/support-bot/app/yu-ai-agent-0.0.1-SNAPSHOT.jar --spring.config.additional-location=optional:file:./
SuccessExitStatus=143
Restart=on-failure
RestartSec=10
StandardOutput=append:/opt/support-bot/logs/support-bot.log
StandardError=append:/opt/support-bot/logs/support-bot.log

[Install]
WantedBy=multi-user.target
EOF

10.2 启用服务

# 重载 systemd
sudo systemctl daemon-reload

# 设置开机自启
sudo systemctl enable support-bot

# 启动 / 停止 / 重启 / 状态
sudo systemctl start support-bot
sudo systemctl status support-bot
sudo systemctl restart support-bot
sudo systemctl stop support-bot

# 查看实时日志
sudo journalctl -u support-bot -f

数据库容器已设置 restart: always，服务器重启后会自动拉起数据库，再由 systemd 拉起后端服务（Requires=docker.service 保证顺序）。

11. Nginx 反向代理（可选）

如需用 80 端口访问或加 HTTPS，可安装 Nginx 反向代理到 9090。

# Ubuntu
sudo apt install -y nginx

sudo tee /etc/nginx/conf.d/support-bot.conf <<'EOF'
server {
    listen 80;
    server_name your-domain.com;   # 改为域名或 IP

    client_max_body_size 50m;      # 与后端上传限制一致

    location / {
        proxy_pass http://127.0.0.1:9090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # SSE 流式响应必需
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
        proxy_http_version 1.1;
    }
}
EOF

sudo nginx -t && sudo systemctl reload nginx

SSE 流式接口（AI 对话）必须设置 proxy_buffering off，否则流式输出会被缓冲导致卡顿。

12. 日常运维与排错

12.1 常用命令速查

# —— 数据库 ——
sudo docker compose -f /opt/support-bot/docker-compose.yml ps       # 状态
sudo docker compose -f /opt/support-bot/docker-compose.yml restart  # 重启
sudo docker exec -it support-bot-postgres psql -U postgres -d support_bot  # 进入 psql

# —— 应用 ——
sudo systemctl status support-bot          # 服务状态
sudo systemctl restart support-bot         # 重启
sudo journalctl -u support-bot -f          # 实时日志
tail -f /opt/support-bot/logs/support-bot.log

# —— 防火墙 ——
sudo firewall-cmd --list-ports             # CentOS 查看开放端口
sudo ufw status                            # Ubuntu 查看状态

12.2 数据库备份与恢复

# 备份（含数据）
sudo docker exec support-bot-postgres \
  pg_dump -U postgres support_bot > /opt/support-bot/backup_$(date +%F).sql

# 恢复
sudo docker exec -i support-bot-postgres \
  psql -U postgres -d support_bot < /opt/support-bot/backup_2026-06-27.sql

建议加入 crontab 定时备份：

# 每天凌晨 3 点备份，保留 30 天
echo "0 3 * * * docker exec support-bot-postgres pg_dump -U postgres support_bot > /opt/support-bot/backup_\$(date +\%F).sql && find /opt/support-bot -name 'backup_*.sql' -mtime +30 -delete" | sudo tee /etc/cron.d/support-bot-backup

12.3 切换 Embedding 模型 / 重建向量表

若更换非 1024 维的 Embedding 模型：

# 1. 修改 application.yml 中 knowledge.vector.dimension
# 2. 删除并重建 vector_store 表
sudo docker exec -it support-bot-postgres psql -U postgres -d support_bot -c "DROP TABLE IF EXISTS vector_store CASCADE;"
# 3. 重启服务（启动时自动按新维度重建表）
sudo systemctl restart support-bot
# 4. 重新上传知识库文档（重新向量化）

12.4 常见问题

现象 原因与解决
启动报 Connection refused 127.0.0.1:5432 数据库容器未启动，执行 docker compose up -d
启动报 extension "vector" does not exist 未启用 PGVector 扩展，执行第 4.3 节 CREATE EXTENSION vector
启动成功但 AI 对话报错 ai_model_config 中 API Key 为空，去前端「AI 大模型配置管理」填入并激活
上传文档失败 / 向量化报错 EMBEDDING 配置缺失或维度不匹配；核对维度与 knowledge.vector.dimension 一致
SSE 对话卡顿不输出 经 Nginx 时未关 proxy_buffering，见第 11 节
前端页面 404 访问路径应为 /index.html（不带也行，但确认端口 9090 已放行）
雪花 ID 前端精度丢失 已由 @JsonSerialize(ToStringSerializer.class) 处理，无需额外操作

12.5 升级应用

# 1. 上传新 jar 覆盖旧 jar
# 2. 重启服务
sudo systemctl restart support-bot

13. 附：一键部署脚本

将以下脚本保存为 /opt/support-bot/deploy.sh，可一键完成数据库部署 + 应用启动。

#!/bin/bash
# AI 智能客服系统 一键部署脚本
set -e

APP_DIR=/opt/support-bot
JAR_NAME=yu-ai-agent-0.0.1-SNAPSHOT.jar
DB_PASS=${DB_PASS:-supportbot123}

echo "===== 1. 创建目录 ====="
sudo mkdir -p $APP_DIR/{db,data,app,logs}

echo "===== 2. 生成 docker-compose.yml ====="
sudo tee $APP_DIR/docker-compose.yml <<EOF
version: "3.8"
services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: support-bot-postgres
    restart: always
    ports: ["5432:5432"]
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: $DB_PASS
      POSTGRES_DB: support_bot
      TZ: Asia/Shanghai
    volumes:
      - $APP_DIR/data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d support_bot"]
      interval: 10s
      timeout: 5s
      retries: 5
EOF

echo "===== 3. 启动数据库 ====="
sudo docker compose -f $APP_DIR/docker-compose.yml up -d
sleep 10

echo "===== 4. 启用 vector 扩展 ====="
sudo docker exec support-bot-postgres psql -U postgres -d support_bot -c "CREATE EXTENSION IF NOT EXISTS vector;"

echo "===== 5. 检查 jar 包 ====="
if [ ! -f $APP_DIR/app/$JAR_NAME ]; then
  echo "❌ 未找到 $APP_DIR/app/$JAR_NAME，请先上传 jar 包！"
  exit 1
fi

echo "===== 6. 创建 systemd 服务 ====="
sudo tee /etc/systemd/system/support-bot.service <<EOF
[Unit]
Description=AI Support Bot Spring Boot Service
After=network.target docker.service
Requires=docker.service
[Service]
Type=simple
User=root
WorkingDirectory=$APP_DIR/app
ExecStart=/usr/bin/java -jar $APP_DIR/app/$JAR_NAME --spring.config.additional-location=optional:file:./
SuccessExitStatus=143
Restart=on-failure
RestartSec=10
StandardOutput=append:$APP_DIR/logs/support-bot.log
StandardError=append:$APP_DIR/logs/support-bot.log
[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable support-bot
sudo systemctl restart support-bot

echo "===== 部署完成 ====="
echo "前端页面: http://$(hostname -I | awk '{print $1}'):9090/index.html"
echo "接口文档: http://$(hostname -I | awk '{print $1}'):9090/doc.html"
echo "日志: tail -f $APP_DIR/logs/support-bot.log"
echo "请前往「AI 大模型配置管理」页面填入 API Key 后再使用 AI 功能。"
EOF

使用方式：

chmod +x /opt/support-bot/deploy.sh
# 上传 jar 到 /opt/support-bot/app/ 后执行
sudo DB_PASS=your_strong_password /opt/support-bot/deploy.sh

部署 Checklist

  • Docker 与 Docker Compose 已安装，镜像加速已配置
  • PostgreSQL + PGVector 容器启动且 vector 扩展已启用
  • JDK 17 已安装
  • jar 包已上传至 /opt/support-bot/app/
  • 外部 application.yml 已配置（数据库地址、密码、日志路径）
  • 服务启动成功，业务表自动创建
  • 防火墙 / 安全组放行 9090 端口
  • 前端「AI 大模型配置管理」中 4 类应用已填入 API Key 并激活
  • 已上传知识库文档并验证 RAG 对话
  • systemd 服务已设置开机自启
  • 数据库定时备份已配置

本教程基于项目当前代码状态（Spring Boot 3.4.4 / Java 17 / Spring AI 1.0.1 / PGVector）编写。