【大模型RAG】Docker 一键部署 Milvus 完整攻略

发布于：2025-06-09 ⋅ 阅读:(15) ⋅ 点赞:(0)

本文概要

Milvus 2.5 Stand-alone 版可通过 Docker 在几分钟内完成安装；只需暴露 19530（gRPC）与 9091（HTTP/WebUI）两个端口，即可让本地电脑通过 PyMilvus 或浏览器访问远程 Linux 服务器上的 Milvus。下面从环境准备、Docker 安装、容器启动、数据持久化、防火墙与安全组配置到客户端连接与常见故障排查，一步到位地给出完整操作指引，并汇总常见陷阱及修复方案。

1 环境准备

1.1 系统与硬件要求

Milvus 2.5 官方推荐 x86-64/ARM64 的 Ubuntu、CentOS、Debian 等 64 位发行版，并至少 2 GB RAM、10 GB 磁盘；生产环境建议 ≥8 GB RAM 及 SSD 存储。

1.2 安装 Docker Engine 及常用插件 环境并配置腾讯云镜像

# 卸载旧版（可选）
sudo apt remove docker docker-engine docker.io containerd runc -y

# 1. 更新本地 apt 索引，确保使用最新的包列表  
sudo apt-get update                             #  Refresh the list of available packages and their versions  [oai_citation:0‡bbs.fit2cloud.com](https://bbs.fit2cloud.com/t/topic/5896?utm_source=chatgpt.com)  

# 2. 安装 HTTPS 传输和下载工具  
sudo apt-get install -y ca-certificates curl     #  安装 SSL 证书支持（ca-certificates）和网络下载工具（curl） [oai_citation:1‡cloud.tencent.com](https://cloud.tencent.com/developer/article/2439720?utm_source=chatgpt.com)  

# 3. 创建存放 GPG 公钥的目录  
sudo install -m 0755 -d /etc/apt/keyrings        #  创建 /etc/apt/keyrings 目录，并设置权限为 0755（用户可读写执行、组和其他可读执行） [oai_citation:2‡cloud.tencent.com](https://cloud.tencent.com/developer/article/2439720?utm_source=chatgpt.com)  

# 4. 从腾讯云镜像下载 Docker 官方 GPG 公钥  
sudo curl -fsSL https://mirrors.cloud.tencent.com/docker-ce/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc                #  -f：遇 HTTP 错误时退出；-s：静默模式；-S：显示错误；-L：跟随重定向；将公钥保存到 /etc/apt/keyrings/docker.asc  [oai_citation:3‡cloud.tencent.com](https://cloud.tencent.com/developer/article/2297462?utm_source=chatgpt.com)  

# 5. 赋予公钥文件可读权限  
sudo chmod a+r /etc/apt/keyrings/docker.asc      #  让所有用户都可读取此公钥，以便 apt 在执行安装时进行签名验证 [oai_citation:4‡cloud.tencent.com](https://cloud.tencent.com/developer/article/2297462?utm_source=chatgpt.com)  

# 6. 添加腾讯云 Docker APT 仓库  
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://mirrors.cloud.tencent.com/docker-ce/linux/ubuntu \
  $(. /etc/os-release && echo \"\$VERSION_CODENAME\") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null  
#  - arch=$(dpkg --print-architecture)：自动填入系统架构（如 amd64）  
#  - signed-by：指定使用上述下载的 GPG 公钥验证包签名  
#  - $(. /etc/os-release && echo "$VERSION_CODENAME")：读取 Ubuntu 发行代号（如 jammy） [oai_citation:5‡cloud.tencent.com](https://cloud.tencent.com/developer/article/2297462?utm_source=chatgpt.com)  

# 7. 刷新 apt 索引以加载腾讯云镜像源  
sudo apt-get update                             #  再次下载所有源的包列表，包括新添加的腾讯云源 [oai_citation:6‡bbs.fit2cloud.com](https://bbs.fit2cloud.com/t/topic/5896?utm_source=chatgpt.com)  

# 8. 安装 Docker Engine 及常用插件  
sudo apt-get install -y \
  docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin  #  一次性安装 Docker 引擎（docker-ce）、命令行工具（docker-ce-cli）、容器运行时（containerd.io）、Buildx 插件和 Compose 插件 [oai_citation:7‡docs.docker.com](https://docs.docker.com/engine/install/ubuntu/?utm_source=chatgpt.com)

官方文档对 Ubuntu 24.04/22.04/20.04 的步骤完全一致。

 

sudo systemctl start docker 启动 Docker 服务
sudo systemctl status docker  查看 Docker 是否正在运行

 验证docker:      sudo docker run hello-world

输出如下即正常

 

2 安装docker-compose

Ubuntu 和 Debian 系统执行：

sudo apt-get update
sudo apt-get install docker-compose-plugin

验证docker compose : sudo docker compose version  

 

2.2 Docker Compose安装Milvus（一键编排 ）

Docker Compose 是 Docker 官方提供的多容器编排工具，将多个服务（如 Milvus、etcd、MinIO）及其依赖通过一个 YAML 文件统一定义和管理。

官方：（可能无法访问）

wget https://github.com/milvus-io/milvus/releases/download/v2.5.1/milvus-standalone-docker-compose.yml -O docker-compose.yml
docker compose up -d

国内镜像：

# 方法一：Gitee 原始文件
wget https://gitee.com/milvus-io/milvus/raw/2.5/deployments/docker/standalone/docker-compose.yml \
  -O docker-compose.yml

 即是将官方发布的编排文件 milvus-standalone-docker-compose.yml 下载并保存为 docker-compose.yml。

验证： 有文件即可 

一键启动所有服务 

sudo docker compose up -d


	•	-d 表示后台运行，compose 将根据 docker-compose.yml 启动以下容器：
	•	milvus-etcd（2379/TCP）
	•	milvus-minio（9000/TCP、9001/TCP）
	•	milvus-standalone（19530/TCP gRPC、9091/TCP HTTP/WebUI）

  • 会以守护模式（-d）读取当前目录下的 docker-compose.yml，并一键拉起所有定义的容器实例（包括 Milvus Standalone、etcd（元数据存储）和 minio（对象存储） 等）。

 

查看运行状态

sudo docker compose ps

确认所有服务均为 Up (healthy) 状态。

 

2.3 数据持久化与备份

Milvus 的向量、索引、WAL 默认存于 /var/lib/milvus；映射到主机目录即可持久化。

生产环境可替换为 Ceph / MinIO / S3；官方文档对对象存储路径也有说明。

  • -v $HOME/milvus_data:/var/lib/milvus （启动命令已经包含了）

  • 将容器内部的 /var/lib/milvus 映射到宿主机的 $HOME/milvus_data。

  • 即默认会在当前文件下创建一个volumes 文件夹作为数据存放地址

如何修改宿主机数据存放路径：

3 远程访问与防火墙配置

3.1 开放 Linux 防火墙

UFW（Ubuntu）

sudo ufw allow 19530/tcp
sudo ufw allow 9091/tcp
sudo ufw reload
sudo ufw status
若部署在云服务器（Alibaba Cloud、AWS、GCP 等），在 安全组 打开相同端口。

我是在云平台，所以可以关闭防火墙，配置安全组就可以了 

 

3.2 客户端连通性测试

# Mac / Linux 本地
nc -vz <REMOTE_IP> 19530
nc -vz <REMOTE_IP> 9091

端口成功握手后，再使用 SDK 连接。

3.3 Python 代码示例（PyMilvus ≥ 2.5）

from pymilvus import utility, connections

# 1. 建立连接
connections.connect(
    alias="default",
    host="REMOTE_IP",  # 远程公网/内网地址
    port="19530",
    secure=False       # 如使用 nginx + TLS，可改 True
)

# 2. 查看健康
print(utility.get_server_version())   # 预期输出 v2.5.x

# 3. 查看现有集合
print(utility.list_collections())

# 4. 断连
connections.disconnect("default")

官方 Quickstart 教程同样适用，只需把 host 设为远端 IP。

 

4 常见问题与排查

现象

原因

解决

Fail connecting to server on localhost:19530

版本不匹配 / 端口未通

1) 升级 pymilvus ==2.5.* 2) 确认安全组与防火墙已开放

MilvusException(code=2)

Docker 端口未映射或被 SELinux 拦截

1) 确认 -p 参数 2) 关闭或配置 SELinux

WebUI 打不开

端口 9091 未放通 / 旧版无 WebUI

开放 9091 并确保镜像 ≥ v2.5

插入/查询慢

未启用 GPU 或索引未构建

使用 HNSW / IVF 索引，或升级硬件

5 升级与维护

  • 升级镜像：docker pull milvusdb/milvus:v2.5.12 && docker stop milvus25 && docker rm milvus25 && docker run ... （保持数据卷不变即可就地升级）。最新版变更参见 Release Notes。

  • 备份：定期打包 $HOME/milvus_data 或挂载到外置 NFS / S3。

  • 多线程连接：在 Web 服务中，每个线程使用不同的 alias 连接可避免竞争。

 

6 全文流程速查表

步骤

命令 / 操作

安装 Docker

apt install docker-ce ...

拉起 Milvus

docker run -d --name milvus25 -p 19530:19530 -p 9091:9091 -v ~/milvus_data:/var/lib/milvus milvusdb/milvus:v2.5.1

开防火墙

ufw allow 19530/tcp && ufw allow 9091/tcp

本地连接

connections.connect(host="REMOTE_IP", port="19530")

浏览 WebUI

http://REMOTE_IP:9091

参考来源

  • Run Milvus in Docker (Linux) — Milvus 官方文档 milvus.io

  • Run Milvus with Docker Compose (Linux) — Milvus 官方文档 milvus.io

  • Configure Milvus with Docker Compose — Milvus 官方文档 milvus.io

  • Ubuntu UFW 配置指南 — 腾讯云开发者社区 cloud.tencent.com

  • Docker exec 使用教程 — Docker 官方文档 docs.docker.com

  • PyMilvus 快速开始 — Milvus 博客 milvus.io

  • Milvus Standalone 容器启动失败排查 — GitHub Issue github.com

  • Docker CLI Cheat Sheet — Docker 官方文档 docs.docker.com

  • Ubuntu UFW 实战案例 — 腾讯云开发者社区 cloud.tencent.com

  • Docker Compose Exec 指南 — Docker 官方文档 docs.docker.com

尾声

按照以上步骤，你即可在任何 Linux 云主机上 3 分钟内部署 Milvus 2.5 并让本地开发机稳定访问。后续只需关注端口、版本、数据卷三要素，便能避免 99 % 常见坑，安心构建向量检索 + BM25 混合 RAG 生产环境。如有疑问，欢迎在评论区留言交流。祝各位向量搜索一路丝滑 🚀

如果本文对你有帮助，欢迎 点赞、评论 和 转发，一起交流 Milvus 部署经验！

 

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布