RAG Guide

外观

Docker 部署 ​

准备Docker环境 ​

安装Docker ​

以 Ubuntu Server 22.04 LTS 为例，设置 Docker 的 apt 源

sh
# 信任 Docker 的 GPG 公钥
sudo apt-get update && apt-get install ca-certificates curl gnupg -y
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 添加仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

安装Docker

sh
apt-get update
apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# 安装成功后查看版本
docker version

设置开机启动

sh
systemctl start docker
systemctl enable docker
systemctl status docker

设置镜像加速 ​

配置镜像源

sh
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io",
    "https://dislabaiot.xyz"
  ]
}
EOF

# 重启服务生效
sudo systemctl daemon-reload && sudo systemctl restart docker

# 查看配置结果
root@ubuntu22:/etc/docker# docker info
Client: Docker Engine - Community
 Version:    28.1.1
 Context:    default
 ...
 ...
 Registry Mirrors:
  https://docker.1ms.run/
  https://docker.xuanyuan.me/
  https://docker.m.daocloud.io/
  https://dislabaiot.xyz/
 Live Restore Enabled: false

构建后端镜像 ​

修改配置文件 ​

检查并修改项目的生产配置文件：.env.prod

重点检查：

  • 数据库配置：DB_HOST=rag-mysql # 使用docker-compose 部署时，使用 rag-mysql 容器的名称
  • 数据库密码：DB_PASSWORD=123456Abcd # 生产环境请使用强密码
  • redis 配置：REDIS_HOST=rag-redis # 使用docker-compose 部署时，使用 rag-redis 容器的名称
  • 向量存储配置：MILVUS_CONNECTION_URL=http://rag-milvus:19530 # 使用docker-compose 部署时，使用 rag-milvus 容器的名称
  • 文件存储配置：S3_ENDPOINT=http://127.0.0.1:9000 # 如果使用S3，则需要指定
  • 嵌入模型配置
  • LLM聊天模型配置
  • 重排模型配置

检查并修改文件：docker-compose.yml

重点检查：数据库配置（与文件.env.prod对应）

image-20260205171853535

上传后端文件 ​

上传方式一：

可以将自己开发的代码上传到Gitee或Gitlab等私人仓库，再从私人代码仓库中下载代码。SSH登录服务器，执行下面命令

sh
# 第一次：克隆仓库
cd /opt && git clone https://gitee.com/abc.git  # 替换为您的私人仓库地址
# 或者克隆指定分支：git clone -b develop https://gitee.com/abc.git 

# 第二次及以后：如果有代码更新，运行 git pull 拉取新代码
cd /opt/my-rag && git pull

上传方式二：

使用 WindTerm 等SSH工具登录服务器，进入/opt目录下，上传整个my-rag项目后端目录。注意：不要上传venv文件夹。

查看上传结果

shell
root@ubuntu22:~# ll /opt/my-rag
total 64
drwxr-xr-x 4 root root  4096 Jan 31 10:56 ./
drwxr-xr-x 9 root root  4096 Jan 31 11:21 ../
-rw-r--r-- 1 root root  3326 Jan 31 10:56 .env.dev
-rw-r--r-- 1 root root  3607 Jan 31 10:56 .env.prod
drwxr-xr-x 8 root root  4096 Jan 31 10:56 .git/
-rw-r--r-- 1 root root  2197 Jan 31 10:56 .gitignore
-rw-r--r-- 1 root root   497 Jan 31 10:56 Dockerfile
drwxr-xr-x 5 root root  4096 Jan 31 10:56 app/
-rw-r--r-- 1 root root   347 Jan 31 10:56 arq_worker.py
-rw-r--r-- 1 root root 11620 Jan 31 10:56 deploy.sh
-rw-r--r-- 1 root root  2157 Jan 31 10:56 docker-compose.yml
-rw-r--r-- 1 root root   850 Jan 31 10:56 entrypoint.sh
-rw-r--r-- 1 root root  1765 Jan 31 10:56 main.py
-rw-r--r-- 1 root root  1123 Jan 31 10:56 requirements.txt

构建后端镜像 ​

构建镜像所需文件（上一步已上传）

  • Dockerfile文件：/opt/my-rag/Dockerfile
  • 入口文件：/opt/my-rag/entrypoint.sh
sh
# 构建镜像
cd /opt/my-rag/ && docker build -t rag-backend .
# 如果报错，使用： cd /opt/my-rag/ && docker build --no-cache -t rag-backend .

# 查看构建结果
root@ubuntu22:/opt/mars-mgn# docker images
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
rag-backend   latest    56c4fe403f45   4 minutes ago   8.82GB

重构后端镜像 ​

  • 当项目依赖requirements.txt发生改变（例如添加了新的依赖），需要重构后端镜像。
  • 当项目代码改变，不需要重构后端镜像。

部署后端项目 ​

目录结构设计 ​

名称目录
后端代码/opt/my-rag
数据库数据/opt/rag-deploy/mysql
Redis数据/opt/rag-deploy/redis
milvus 数据/opt/rag-deploy/milvus
后端上传文件数据/opt/rag-deploy/uploads
后端日志数据/opt/rag-deploy/logs

创建数据目录 ​

数据目录包括

  • 数据库数据：/opt/rag-deploy/mysql
  • Redis 数据：/opt/rag-deploy/redis
  • milvus 数据：/opt/rag-deploy/milvus
  • 后端上传文件数据：/opt/rag-deploy/uploads
  • 后端日志数据：/opt/rag-deploy/logs
sh
# 创建数据目录
mkdir -p /opt/rag-deploy/{mysql,redis,milvus,uploads,logs}

查看操作结果

shell
root@ubuntu22:~# ll /opt/rag-deploy/
...
drwxr-xr-x 2 root root 4096 Jan 31 11:21 logs/
drwxr-xr-x 2 root root 4096 Jan 31 11:21 milvus/
drwxr-xr-x 2 root root 4096 Jan 31 11:21 mysql/
drwxr-xr-x 2 root root 4096 Jan 31 11:21 redis/
drwxr-xr-x 2 root root 4096 Jan 31 11:21 uploads/

部署后端 ​

创建并启动所有容器，等待约1~3分钟

sh
# 复制 docker-compose.yml 文件
cp /opt/my-rag/docker-compose.yml /opt/rag-deploy/

# 启动容器
cd /opt/rag-deploy/ && docker compose up -d
# 如果报错，试试：cd /opt/rag-deploy/ && docker compose up -d --force-recreate

docker常用命令 ​

sh
# 查看容器状态
docker ps
# 查看日志
docker logs rag-backend
docker logs rag-mysql
docker logs rag-redis
docker logs rag-milvus
# 查看最后100条日志
docker logs -n 100 rag-milvus
# 查看容器内部进程
docker top rag-backend
# 进入容器
docker exec -it rag-backend /bin/bash 

# 停止容器
cd /opt/rag-deploy/ && docker compose stop
# 启动容器
cd /opt/rag-deploy/ && docker compose start
# 停止并删除所有容器（谨慎操作）
cd /opt/rag-deploy/ && docker compose down

说明：当项目代码改变，上传新代码后，运行下面命令生效

shell
# 停止容器
cd /opt/rag-deploy/ && docker compose stop
# 启动容器
cd /opt/rag-deploy/ && docker compose start

基本测试 ​

将IP地址更换为Docker宿主机地址

image-20260131154105496

image-20260131154034400

注意事项与建议 ​

注意事项与建议

  • 本文使用的是Milvus单机版本，且部署在同一台服务器。生产环境建议使用独立的服务器，部署Milvus分布式版本（或单机版本）。
  • 生产环境，定期做好数据备份。数据备份包括：数据库、向量数据库、文件存储和Redis。
  • 对生产环境的任何变更，必须先做一次备份，再进行操作。

排错 ​

下载镜像失败 ​

错误信息：pull access denied for rag-backend

解决方法：rag-backend是指后端镜像。需要按上面步骤先构建后端镜像，再启动。

后端启动失败 ​

报错信息

shell
/home/entrypoint.sh: line 5: $'\r': command not found
: invalid option nameline 7: set: pipefail

分析：/home/entrypoint.sh使用了Windows的换行符CRLF

解决方法：将文件/home/entrypoint.sh，修改为LF换行

image-20260131142350606

redis容器告警 ​

错误信息：

shell
1:M 31 Jan 2026 12:11:45.213 # WARNING Memory overcommit must be enabled!

分析：宿主机（运行Docker的机器）的 Linux 内核参数 vm.overcommit_memory设置不当。

解决方案：宿主机执行下面命令

shell
echo "vm.overcommit_memory = 1" >> /etc/sysctl.conf
sysctl -p