当前位置：首页 > news >正文

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

news 来源：原创 2025/6/9 6:08:20

本文概要

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