从零开始：Docker 部署 Milvus 向量数据库并接入 Attu 与 pymilvus 的全流程指南

从零开始：Docker 部署 Milvus 向量数据库并接入 Attu 与 pymilvus 的全流程指南

本文面向所有想在本地、虚拟机或 WSL 上快速搭建 Milvus 的开发者，尤其适合之前尝试失败、需要清理环境后重新来过的同学。 你将获得一份可直接执行的命令清单，以及应对网络、端口、防火墙等常见问题的解决方案。

〇、为什么你需要这篇指南

Milvus 是一个高性能的开源向量数据库，广泛应用于相似性搜索、推荐系统、RAG 等 AI 场景。官方提供了 Docker 独立部署脚本，但因为国内网络环境、GitHub 访问不稳定、镜像版本标签缺失等问题，很多人在安装时反复报错。

本文将用最稳妥的方式带你完成安装，同时给出 Windows + WSL 2 下的配置建议，并教你使用图形化管理工具 Attu 和 Python SDK pymilvus。

一、动手前：彻底清理前面的失败环境（重要！）

如果你之前按照其他教程操作过，或者安装到一半报错，强烈建议先执行下面的“大扫除”，避免旧容器、错误镜像导致后续步骤异常。

# 停止并删除旧的 milvus 容器
docker stop milvus-standalone 2>/dev/null
docker rm milvus-standalone 2>/dev/null

# 删除之前拉取可能失败的镜像
docker rmi milvusdb/milvus:v2.6.2 2>/dev/null
docker rmi milvusdb/milvus:v2.4.6 2>/dev/null
# 若还有其他标签，可一并清除：
# docker images | grep milvusdb/milvus | awk '{print $3}' | xargs docker rmi -f

# 删除安装脚本和自动生成的配置文件
rm -f standalone_embed.sh embedEtcd.yaml user.yaml

# 删除持久化数据(⚠️ 这会永久删除你存入的全部数据)
rm -rf ./volumes

# 可选：清理 Docker 系统缓存
docker system prune -a

确认环境干净后，我们再开始。

二、基础准备：配置 Docker 镜像加速

国内从 Docker Hub 拉取镜像缓慢，甚至超时退出，配置加速器可以一劳永逸。

编辑或新建 /etc/docker/daemon.json：

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

重启 Docker 服务：

sudo systemctl daemon-reload
sudo systemctl restart docker

验证加速器是否生效：

docker info | grep -A 5 "Registry Mirrors"

三、获取安装脚本并启动 Milvus

3.1 下载脚本（绕过 GitHub 访问限制）

由于 raw.githubusercontent.com 经常被屏蔽，改用 CDN 地址下载：

curl -sfL https://cdn.jsdelivr.net/gh/milvus-io/milvus/scripts/standalone_embed.sh -o standalone_embed.sh
chmod +x standalone_embed.sh

若该地址不可用，可以手动创建脚本文件，内容参见文末附录。

3.2 检查并固定镜像版本

脚本默认会拉取官方最新镜像标签，但有时新标签尚未推送到 Docker Hub，导致 Unable to find image 错误。

查看脚本中写死的镜像版本：

grep -n "MILVUS_IMAGE\\|milvusdb/milvus" standalone_embed.sh

如果出现类似 v2.6.2 这样你确认可用的标签，则无需操作；若看到奇怪的版本号或 want 固定为已知稳定版，执行：

sed -i 's|milvusdb/milvus:.*|milvusdb/milvus:v2.6.2|' standalone_embed.sh

（目前 v2.6.2 已经推送成功，你也可以选择 v2.4.6、v2.5.0 等稳定版本）

3.3 启动 Milvus

bash standalone_embed.sh start

脚本会自动拉取镜像、创建容器，并等待 90 秒左右让服务初始化。看到 “Start successfully.” 即表示安装成功。

容器映射的核心端口：

• 19530：gRPC 服务（SDK 连接用）
• 9091：WebUI 管理界面
• 2379：内嵌 etcd（一般无需访问）

四、网络配置：让物理机或宿主机能访问 Milvus

很多同学在云服务器或虚拟机上安装后，发现自己的电脑浏览器打不开 WebUI。下面根据常见场景逐一说明。

4.1 场景 A：使用 WSL 2（Windows 的 Linux 子系统）

WSL 2 会自动将容器端口转发到 Windows 本机，理论上无需额外配置。直接在 Windows 浏览器中访问：

http://localhost:9091/webui/

如果无法访问，多半是 Windows 防火墙 拦截了 WSL 流量。在 Windows 防火墙中添加入站规则，放行 9091 和 19530 端口即可。

4.2 场景 B：虚拟机 NAT 模式（如 VMware、VirtualBox）

需在虚拟机软件中添加端口转发规则，将宿主机端口映射到虚拟机端口。示例：

之后在宿主机浏览器访问 http://localhost:9091/webui/。

另外，虚拟机自身防火墙（如 firewalld）也要放行这些端口：

sudo firewall-cmd –zone=public –add-port=9091/tcp –permanent
sudo firewall-cmd –zone=public –add-port=19530/tcp –permanent
sudo firewall-cmd –reload

4.3 场景 C：云服务器

请在该云控制台的安全组中，添加入方向规则，允许 TCP 协议的 19530 和 9091 端口。同时检查系统内防火墙。

五、用 Attu 图形界面管理 Milvus

Attu 是官方出品的可视化工具，可代替命令行完成建库、建集合、测搜索等操作。

5.1 桌面版 Attu（推荐 Windows 用户使用）

5.2 Docker 版 Attu（无需安装本地软件）

如果你的 Attu 也需要容器化运行，可执行：

docker run -d –name attu \\
-e MILVUS_URL=http://host.docker.internal:19530 \\
-p 8000:3000 \\
zilliz/attu:v2.6.1

然后浏览器访问 http://localhost:8000，连接时地址填 host.docker.internal:19530。

5.3 集成到 Docker Compose（与 Milvus 统一管理）

如果你使用 docker-compose.yml 部署了 Milvus，可在 services 下添加 attu 服务：

attu:
container_name: attu
image: zilliz/attu:v2.6.1
environment:
MILVUS_URL: "standalone:19530"
ports:
– "8000:3000"
depends_on:
– standalone

然后 docker compose up -d 启动。浏览器访问 http://localhost:8000，连接地址填 standalone:19530。

六、用 pymilvus 连接并操作

如果你需要编程管理 Milvus，可以安装 Python SDK：

pip install pymilvus

连接示例：

from pymilvus import connections

connections.connect(host="localhost", port="19530")
print("连接成功")

创建数据库、集合等更多操作可参考官方文档或直接在 Attu 中执行。

七、常用运维命令速查

• 查看容器状态： docker ps –filter name=milvus-standalone
• 查看日志： docker logs -f milvus-standalone
• 停止服务： bash standalone_embed.sh stop
• 重启服务： bash standalone_embed.sh restart
• 删除容器及全部数据（不可恢复）： bash standalone_embed.sh delete

数据默认保存在脚本所在目录的 volumes/milvus 中，升级或迁移时请注意保留。

八、升级到新版本

官方脚本提供了内置升级命令：

bash standalone_embed.sh upgrade

它会自动获取最新脚本和镜像，并重启容器，同时保留原有数据目录。

你也可以手动升级：停止旧容器，拉取新镜像，重新 docker run 并挂载原数据卷。跨大版本升级前建议查阅官方 Release Notes 确认兼容性。

九、常见问题速查

十、结尾

至此，你已经拥有了一套完整的本地向量数据库开发环境。无论是作为 RAG 知识库的后端，还是用于语义搜索实验，Milvus 都能提供稳定高效的向量存储与检索能力。

附录：手动创建 standalone_embed.sh 脚本 如果 CDN 下载失败，可以用下面命令直接生成一个稳定版脚本（镜像版本已固定为 v2.6.2）：

cat > standalone_embed.sh << 'EOF'
#!/bin/bash
set -e
MILVUS_IMAGE="milvusdb/milvus:v2.6.2"
CONTAINER_NAME="milvus-standalone"
DATA_DIR="./volumes/milvus"
start() {
if [ "$(docker ps -aq -f name=$CONTAINER_NAME)" ]; then
docker start $CONTAINER_NAME
else
mkdir -p $DATA_DIR && chmod -R 775 $DATA_DIR 2>/dev/null || true
docker run -d –name $CONTAINER_NAME \\
-p 19530:19530 -p 9091:9091 \\
-v $PWD/$DATA_DIR:/var/lib/milvus \\
$MILVUS_IMAGE milvus run standalone
echo "等待 Milvus 启动（约90秒）…"
sleep 90
echo "Milvus 启动成功！"
fi
}
stop() { docker stop $CONTAINER_NAME 2>/dev/null; }
delete() { docker rm -f $CONTAINER_NAME 2>/dev/null; rm -rf $DATA_DIR; }
case "${1:-}" in
start) start ;;
stop) stop ;;
delete) delete ;;
restart) stop; start ;;
*) echo "用法: $0 {start|stop|delete|restart}" ;;
esac
EOF
chmod +x standalone_embed.sh