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

本文面向所有想在本地、虚拟机或 WSL 上快速搭建 Milvus 的开发者，尤其适合之前尝试失败、需要清理环境后重新来过的同学。

你将获得一份可直接执行的命令清单，以及应对网络、端口、防火墙等常见问题的解决方案。

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

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

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

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

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

bash 复制代码

# 停止并删除旧的 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：

bash 复制代码

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 服务：

bash 复制代码

sudo systemctl daemon-reload
sudo systemctl restart docker

验证加速器是否生效：

bash 复制代码

docker info | grep -A 5 "Registry Mirrors"

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

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

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

bash 复制代码

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 错误。

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

bash 复制代码

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

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

bash 复制代码

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 复制代码

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）

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

名称	协议	主机 IP	主机端口	子系统 IP	子系统端口
Milvus-gRPC	TCP	(空)	19530	(空/127.0.0.1)	19530
Milvus-WebUI	TCP	(空)	9091	(空/127.0.0.1)	9091

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

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

bash 复制代码

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 用户使用）

从 Attu Releases 下载 Windows 安装包并安装。
打开 Attu，连接信息填写：
- Milvus Address ：127.0.0.1:19530（若 Milvus 在远程服务器，则填服务器公网 IP）
- 数据库 ：留空（默认使用 default 数据库）
- 用户名/密码：留空
点击 Connect，即可连接成功。

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

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

bash 复制代码

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 服务：

yaml 复制代码

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：

bash 复制代码

pip install pymilvus

连接示例：

python 复制代码

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 复制代码

bash standalone_embed.sh upgrade

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

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

九、常见问题速查

现象	原因	解决方法
`Unable to find image v2.6.2`	镜像标签不存在	按前述步骤替换为存在的标签，如 `v2.6.2` 或 `v2.4.6`
拉取镜像超时	Docker 加速未生效	重新配置 `/etc/docker/daemon.json` 并重启 docker
容器反复重启或启动失败	端口冲突或权限问题	检查 `docker logs milvus-standalone` 日志，按提示处理
Attu 连不上 `127.0.0.1:19530`	网络不通或防火墙拦截	验证端口监听 `ss -tuln
WSL 2 内正常，Windows 浏览器打不开	Windows 防火墙阻拦	添加入站规则允许端口

十、结尾

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

附录：手动创建 standalone_embed.sh 脚本

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

bash 复制代码

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