AI向量数据库Milvus3单机学习版部署指南
Milvus 3.x 单机学习版
Rocky Linux 10.1 下 Docker Compose 部署完整指南
仅用于初学者学习实验 · 请勿直接用于生产环境
你好,我是昌哥,进免费技术交流群或咨询加微信: rscpass
环境概览
系统：Rocky Linux release 10.1 (Red Quartz)
内存：建议 ≥8G，推荐 16G
版本：Milvus 3.0.x（Docker Compose 单机部署）
组件：milvus-standalone、etcd（元数据）、minio（对象存储，向量数据持久化）
一、系统前置准备（root 执行）
1.1 确认系统版本
确认系统为 Rocky Linux 10.1，内核版本满足要求：
[root@localhost ~]# cat /etc/redhat-release Rocky Linux release 10.1 (Red Quartz) [root@localhost ~]# uname -r 6.12.0-124.8.1.el10_1.x86_64 |
1.2 关闭 SELinux
学习环境为避免权限报错，建议关闭 SELinux：
# 临时关闭 setenforce 0
# 永久关闭 sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config |
1.3 防火墙（两种选择）
学习内网虚拟机：直接关闭；云服务器：只开放需要的端口，不要全关。
方式一：停止并禁止开机自启
systemctl stop firewalld systemctl disable firewalld |
方式二：只放行需要的端口
firewall-cmd --add-port=19530/tcp --permanent # Milvus firewall-cmd --add-port=9000/tcp --permanent # minio firewall-cmd --add-port=9001/tcp --permanent # minio firewall-cmd --add-port=2379/tcp --permanent # etcd firewall-cmd --add-port=3000/tcp --permanent # Attu firewall-cmd --reload |
1.4 安装 Docker + docker-compose-plugin
先卸载旧版本 Docker，再安装依赖与 Docker CE：
# 卸载旧 docker yum remove -y docker docker-client docker-client-latest docker-common \ docker-latest docker-latest-logrotate docker-logrotate docker-engine
# 安装依赖 yum install -y yum-utils device-mapper-persistent-data lvm2 |
配置 Docker YUM 源（阿里云镜像源，国内高速），并安装 Docker CE：
# 清理旧的 docker 源（如果有） rm -f /etc/yum.repos.d/docker-ce.repo
# 添加阿里云 Docker CE 镜像源 yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
# 安装 docker 和 compose 插件 yum install docker-ce
# 启动 docker 并开机自启 systemctl start docker && systemctl enable docker
# 验证 docker --version docker compose version |
1.5 配置镜像加速（关键步骤）
修改 daemon.json 配置多备选国内镜像源，只有按下面的源才能正常拉取镜像：
vim /etc/docker/daemon.json |
把内容替换成下面（多备选国内镜像源）：
{ "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://mirror.baidubce.com", "https://docker.m.daocloud.io", "https://hub-mirror.c.163.com", "https://mirror.aliyuncs.com", "https://docker.nju.edu.cn", "https://docker.rainbond.cc" ] } |
保存退出（vi 编辑器按 Esc，输入 :wq 回车），然后重启 Docker 生效：
systemctl daemon-reload systemctl restart docker |
提示： daemon.json 中的镜像源请按网络情况选用，部分源可能失效，可保留多个作为备选。 |
二、下载并启动 Milvus 3.x 单机
2.1 创建工作目录，下载官方 compose 配置
mkdir -p /opt/milvus3 cd /opt/milvus3
# 下载 Milvus 3.0 官方单机 docker-compose.yml wget https://github.com/milvus-io/milvus/releases/download/v3.0.1/milvus-standalone-docker-compose.yml -O docker-compose.yml |
如果 wget 下载 GitHub 慢，可以用浏览器打开链接，复制内容保存到服务器 /opt/milvus3/docker-compose.yml。
2.2 拉取镜像并配置目录权限
先单独拉取镜像：
cd /opt/milvus3 docker compose pull |
查看镜像清单：
docker images |
预期镜像清单：
milvusdb/milvus:v3.0.1
minio/minio:RELEASE.2024-12-18T13-15-44Z
quay.io/coreos/etcd:v3.5.25
zilliz/attu:v3.0.0
启动 Milvus 前，先查看容器内运行 Milvus 的 UID：
docker run --rm --entrypoint id milvusdb/milvus:v3.0.1 # 输出：uid=999(milvus) gid=999(milvus) groups=999(milvus) |
确保数据目录存在并递归修改属主为 999:999、权限为 755：
sudo mkdir -p /opt/milvus3/volumes/milvus sudo chown -R 999:999 /opt/milvus3/volumes/milvus sudo chmod -R 755 /opt/milvus3/volumes/milvus
# 确认修改结果（重点看属主那列是不是 999 或 milvus） ls -la /opt/milvus3/volumes/milvus |
2.3 启动 Milvus
cd /opt/milvus3 docker compose up -d |
启动三个容器：
milvus-etcd：元数据存储
milvus-minio：对象存储，保存向量原始数据
milvus-standalone：Milvus 主服务
2.4 查看容器状态
docker compose ps |
注意： 全部容器状态为 healthy 才算正常。刚启动时 healthcheck 需要等待 30–60 秒，刚开始会显示 starting，请耐心等待。 |
查看日志（排查报错用）：
# 看 milvus 主日志 docker compose logs -f milvus-standalone |
Milvus 默认对外端口：19530（SDK 连接端口）；9091 是 metrics 监控端口。
2.5 停止 / 重启 Milvus 常用命令
# 停止 docker compose stop
# 启动 docker compose start
# 销毁（数据会保存在 volumes 目录） docker compose down
# 销毁并删除所有数据（学习环境重置） docker compose down -v |
提示： 数据持久化在当前目录 volumes/ 下，保存 etcd、minio、milvus 全部数据，不要随意删除。 |
三、安装 Attu 可视化管理工具（初学者强烈推荐）
Attu 是 Milvus 官方 GUI 网页工具，可以浏览器操作 Milvus，建集合、插入、查询、看索引，不用写代码调试。新开终端执行：
docker run -d --name attu3 --network milvus -p 3000:3000 \ -e MILVUS_URL=http://milvus-standalone:19530 zilliz/attu:v3.0.0 |
参数说明：
--network milvus：加入 Milvus compose 自动创建的网络，Attu 容器内部可以解析 milvus-standalone 主机名。
所有依赖启动完成后，docker ps -a 应显示四个容器（milvus-standalone、milvus-minio、milvus-etcd 为 healthy，attu 已运行）。
浏览器访问：http://服务器IP:3000
Milvus 地址填写：http://milvus-standalone:19530
默认没有账号密码，直接 Connect 连接
四、Python SDK pymilvus 3.x 安装与测试连接
重要： Milvus 3.x 必须使用 pymilvus v3.x，旧版本 pymilvus 2.x 不兼容。 |
4.1 安装 pymilvus
yum install -y epel-release python3.12-pip pip3 install --user "pymilvus[model]" |
4.2 最小测试代码 test_milvus.py
from pymilvus import MilvusClient
# 服务器本机访问写 127.0.0.1；远程访问写服务器 IP client = MilvusClient(uri="http://127.0.0.1:19530")
# 检查连通性 resp = client.get_server_version() print(f"Milvus 服务版本: {resp}") print("连接 Milvus 成功！")
# 列出所有集合 colls = client.list_collections() print(f"现有集合列表：{colls}") |
运行：
python3 test_milvus.py |
预期输出：
Milvus 服务版本: 3.0-20260902-658cbd1689 连接 Milvus 成功！ 现有集合列表：[] |
注意： 如果服务器不在本机，把 uri 改成 http://服务器IP:19530，并确保防火墙放行 19530 端口。 |
五、初学者第一个完整 demo（建集合、插入向量、检索）
保存为 demo.py：
from pymilvus import MilvusClient import random
client = MilvusClient("http://127.0.0.1:19530")
collection_name = "demo_vector"
# 1. 删除旧集合（测试用） if client.has_collection(collection_name): client.drop_collection(collection_name)
# 2. 准备索引参数 index_params = client.prepare_index_params() index_params.add_index( field_name="vector", index_type="HNSW", metric_type="COSINE", params={"M": 16, "efConstruction": 100} )
# 3. 创建集合时直接带上索引参数 client.create_collection( collection_name=collection_name, dimension=8, index_params=index_params )
# 4. 构造模拟向量数据 data = [ {"id": i, "vector": [random.random() for _ in range(8)], "text": f"doc{i}"} for i in range(100) ]
# 5. 插入数据 res = client.insert(collection_name=collection_name, data=data) print(f"插入成功，插入条数：{res[\"insert_count\"]}")
# ★★★ 关键：插入后 flush，强制数据落盘 ★★★ client.flush(collection_name) print("数据已 flush 落盘")
# 6. 加载集合到内存 client.load_collection(collection_name)
# 7. 向量相似度检索 query_vector = [random.random() for _ in range(8)] search_res = client.search( collection_name=collection_name, data=[query_vector], limit=3, output_fields=["text"] )
print("检索结果：") for hit in search_res[0]: print(f"id:{hit[\"id\"]}, score:{hit[\"distance\"]}, text:{hit[\"entity\"][\"text\"]}") |
运行：
python3 demo.py |
预期输出：
插入成功，插入条数：100 数据已 flush 落盘 检索结果： id:56, score:0.986970067024231, text:doc56 id:15, score:0.9712440371513367, text:doc15 id:32, score:0.9541948437690735, text:doc32 |
小结： 完成这个 demo，就理解了 Milvus 3.x 的基础流程：建集合 → 插入数据 → 建索引 → 加载 → 向量检索。 |
六、初学者常见坑
1. 容器一直 unhealthy
内存不足：Milvus 3 单机至少 8G 内存，4G 内存环境会不断重启。
SELinux 没有关闭，导致目录权限异常。
镜像没有拉取完整：执行 docker compose pull 重新拉取镜像。
2. pymilvus 连接拒绝
Milvus 容器未 healthy，等待几分钟。
云服务器安全组没开放 19530 端口。
不要在 Attu 里写 127.0.0.1，Attu 是容器，要写 milvus-standalone:19530。
3. 注意版本匹配
Milvus Server 3.0.x ↔ pymilvus 3.x，不要混用 2.x SDK。
Attu 版本必须匹配 Milvus 主版本，这里用 attu:v3.0.0。
4. 磁盘空间
minio 会存储全部向量原始数据，学习环境可定期用 docker compose down -v 清理测试数据。
七、学习路径建议
跑通上面 demo，理解 Collection、schema、向量维度、主键、标量字段。
在 Attu 网页界面可视化操作，观察集合、索引、数据。
学习不同索引：HNSW / IVF_FLAT / DiskANN，对比参数 M、efConstruction、ef_search。
学习标量过滤查询、混合检索。
学习官方 bootcamp Jupyter 示例项目。
八、官方参考文档链接
Milvus 3.x 官方中文文档：https://milvus.io/docs/zh
Milvus Bootcamp 实战案例：https://milvus.org.cn/bootcamp
pymilvus 3.x API 文档：https://milvus.io/api-reference/pymilvus/v3.0.x/About.md
浙公网安备 33010602011771号