阮胜昌的博客-Linux&MySQL数据库运维

Rocky Linux release 10.1 (Red Quartz) 安装 Milvus 3.x（单机学习版）完整文档

说明：**本环境仅用于初学者学习实验，不要直接用于生产环境**。

环境：Rocky Linux release 10.1 (Red Quartz) 内存建议 ≥8G，推荐 16G；Milvus‑3.0.x，使用 Docker Compose 单机部署。

组件：milvus‑standalone、etcd（元数据）、minio（对象存储，向量数据持久化）。

## 一、系统前置准备（root 执行）

### 1.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（学习环境，避免权限报错）

#临时关闭

setenforce 0

#永久关闭

sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config

### 1.3 防火墙（两种选择）

学习内网虚拟机：直接关闭；
云服务器：只开放需要端口，不要全关。

#停止并禁止开机自启

systemctl stop firewalld

systemctl disable firewalld

如果不关闭防火墙，需要放行端口：19530 (Milvus)、9000/9001 (minio)、2379 (etcd)、3000 (Attu)

firewall-cmd --add-port=19530/tcp --permanent

firewall-cmd --add-port=9000/tcp --permanent

firewall-cmd --add-port=9001/tcp --permanent

firewall-cmd --add-port=2379/tcp --permanent

firewall-cmd --add-port=3000/tcp --permanent

firewall-cmd --reload

### 1.4 安装 Docker + docker‑compose‑plugin

#卸载旧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

1. 先清理旧的 docker 源（如果有）

rm -f /etc/yum.repos.d/docker-ce.repo

2. #配置docker yum源,添加阿里云 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

### 修改 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.baidubce.com",

"https://mirror.aliyuncs.com",

"https://docker.nju.edu.cn",

"https://docker.mirrors.ustc.edu.cn",

"https://docker.rainbond.cc"

]

}

保存退出：`vi编辑器按Esc，输入:wq回车`

systemctl daemon-reload

systemctl restart docker

## 二、下载并启动 Milvus 3.x 单机

### 2.1 创建工作目录，下载官方 compose 配置

mkdir -p /opt/milvus3

cd /opt/milvus3

#下载Milvus3.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

### 3、重启 docker 生效

systemctl daemon-reload

systemctl restart docker

#验证镜像源是否加载成功

docker info

cd /opt/milvus3

#先单独拉镜像

docker compose pull

查看镜像清单：

[root@localhost ~]# docker images

IMAGE ID DISK USAGE CONTENT SIZE EXTRA

milvusdb/milvus:v3.0.1 40c63a7a6a20 5.98GB 2.99GB

minio/minio:RELEASE.2024-12-18T13-15-44Z cd8de3bc8037 360MB 179MB

quay.io/coreos/etcd:v3.5.25 ced90a354942 135MB 66.2MB

zilliz/attu:v3.0.0 28656b9f8d2b 727MB 357MB

启动milvus前配置目录权限：

查看容器内运行 Milvus 的 UID

[root@localhost milvus3]# docker run --rm --entrypoint id milvusdb/milvus:v3.0.1

uid=999(milvus) gid=999(milvus) groups=999(milvus)

# 1. 确保目录存在

sudo mkdir -p /opt/milvus3/volumes/milvus

# 2. 递归修改属主为 999:999

sudo chown -R 999:999 /opt/milvus3/volumes/milvus

# 3. 递归修改权限为 755

sudo chmod -R 755 /opt/milvus3/volumes/milvus

# 4. 确认修改结果（重点看属主那列是不是 999 或 milvus）

ls -la /opt/milvus3/volumes/milvus

#启动

docker compose up -d

### 2.2 启动 Milvus

cd /opt/milvus3

docker compose up -d

启动三个容器：

- `milvus-etcd`：元数据存储

- `milvus-minio`：对象存储，向量原始数据

- `milvus-standalone`：Milvus 主服务Milvus

### 2.3 查看容器状态

docker compose ps

全部容器状态为`healthy`才算正常。

刚启动时 healthcheck 需要等待 30‑60 秒，刚开始会显示 starting，耐心等待。

查看日志（排查报错用）

#看milvus主日志

docker compose logs -f milvus-standalone

Milvus 默认对外端口：**19530**，SDK 连接端口；9091 是 metrics 监控端口。

### 2.4 停止 / 重启 Milvus 常用命令

#停止

docker compose stop

#启动

docker compose start

#销毁（数据会保存在volumes目录）

docker compose down

#销毁并删除所有数据（学习环境重置）

docker compose down -v

数据持久化：当前目录`volumes/`下面保存 etcd、minio、milvus 全部数据，不要随意删除。

## 三、安装 Attu 可视化管理工具（初学者强烈推荐）

Attu 是 Milvus 官方 GUI 网页工具，可以浏览器操作 Milvus，建集合、插入、查询、看索引，不用写代码调试GitHub。

新开终端执行：

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中的容器，显示如下：

[root@centos7 ~]# docker ps -a

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES

7670e49870f0 milvusdb/milvus:v3.0.1 "/tini -- milvus run…" 7 minutes ago Up 7 minutes (healthy) 0.0.0.0:9091->9091/tcp, :::9091->9091/tcp, 0.0.0.0:19530->19530/tcp, :::19530->19530/tcp milvus-standalone

c3d163fa5d21 minio/minio:RELEASE.2024-12-18T13-15-44Z "/usr/bin/docker-ent…" 7 minutes ago Up 7 minutes (healthy) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp milvus-minio

502f9d9a7fae quay.io/coreos/etcd:v3.5.25 "etcd -advertise-cli…" 7 minutes ago Up 7 minutes (healthy) 2379-2380/tcp milvus-etcd

b4483341fa95 zilliz/attu:v3.0.0 "docker-entrypoint.s…" 5 weeks ago Up About a minute 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp

浏览器访问：`http://服务器IP:3000`

 

- Milvus 地址填写： http://milvus-standalone:19530

 

- 默认没有账号密码，直接 connect 连接。

## 四、Python SDK pymilvus3.x 安装与测试连接

Milvus3.x 必须使用 pymilvus v3.x，旧版本 pymilvus2.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 端口Milvus。

## 五、初学者第一个完整 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，就理解 Milvus3.x 基础流程：建集合→插入数据→建索引→加载→向量检索。

## 六、初学者常见坑：

1. **容器一直 unhealthy**

- 内存不足：Milvus3 单机至少 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`清理测试数据。

## 七、学习路径建议（CentOS7 这套环境上练习）

1. 跑通上面 demo，理解 Collection、schema、向量维度、主键、标量字段。

2. 在 Attu 网页界面可视化操作，观察集合、索引、数据。

3. 学习不同索引：HNSW / IVF_FLAT / DiskANN，对比参数 M、efConstruction，ef_search。

4. 学习标量过滤查询，混合检索。

5. 学习官方 bootcamp Jupyter 示例项目。

## 八、官方参考文档链接

1. Milvus3.x 官方中文文档：https://milvus.io/docs/zh

2. Milvus Bootcamp 实战案例：[https://milvus.org.cn/bootcamp](https://milvus.org.cn/bootcamp)

3. pymilvus3.x API 文档：[https://milvus.io/api-reference/pymilvus/v3.0.x/About.md](https://milvus.io/api-reference/pymilvus/v3.0.x/About.md)