CentOS 部署 Milvus 向量数据库完整指南

一、环境要求与前置条件

在开始安装 Milvus 之前，请确认你的 CentOS 系统满足以下最低要求：

项目	最低要求	推荐配置
操作系统	CentOS 7 / 8 / Stream	CentOS Stream 8+
CPU	4 核	8 核以上
内存	8 GB	16 GB 以上
磁盘	50 GB SSD	100 GB NVMe SSD
Docker	20.10+	24.0+
Docker Compose	v2.0+	v2.20+

提示： Milvus Standalone 模式适合开发、测试及中小规模生产环境。如果数据量超过 1000 万向量，建议使用 Cluster 集群模式部署。

检查系统版本

bash 复制代码

# 查看 CentOS 版本
cat /etc/os-release

# 查看内核版本（建议 3.10 以上）
uname -r

# 查看内存与磁盘
free -h
df -h

二、安装 Docker 与 Docker Compose

步骤 1：卸载旧版本（如有）

bash 复制代码

sudo yum remove -y docker \
    docker-client \
    docker-client-latest \
    docker-common \
    docker-latest \
    docker-latest-logrotate \
    docker-logrotate \
    docker-engine

步骤 2：安装 Docker CE

bash 复制代码

# 安装 yum-utils（提供 yum-config-manager）
sudo yum install -y yum-utils

# 添加 Docker 官方仓库（国内可替换为阿里云镜像）
sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

# 国内用户推荐使用阿里云镜像加速
# sudo yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo

# 安装 Docker CE
sudo yum install -y docker-ce docker-ce-cli containerd.io \
    docker-buildx-plugin docker-compose-plugin

步骤 3：启动 Docker 并设置开机自启

bash 复制代码

# 启动 Docker 服务
sudo systemctl start docker

# 设置开机自启
sudo systemctl enable docker

# 验证安装
sudo docker --version
sudo docker compose version

步骤 4：配置 Docker 镜像加速（国内推荐）

bash 复制代码

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

# 重新加载配置并重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

验证： 运行 sudo docker run hello-world，如果出现 "Hello from Docker!" 说明 Docker 安装成功。

三、方式一：Docker 单容器部署

这种方式分别启动 etcd、MinIO 和 Milvus 三个容器，适合理解各组件的职责。

步骤 1：创建数据目录

bash 复制代码

sudo mkdir -p /opt/milvus/{etcd,minio,milvus}
cd /opt/milvus

步骤 2：启动 etcd

bash 复制代码

docker run -d --name milvus-etcd \
  -p 2379:2379 \
  -v /opt/milvus/etcd:/etcd \
  --restart always \
  quay.io/coreos/etcd:v3.5.5 \
  etcd -advertise-client-urls=http://127.0.0.1:2379 \
       -listen-client-urls=http://0.0.0.0:2379 \
       --data-dir=/etcd

步骤 3：启动 MinIO 对象存储

bash 复制代码

docker run -d --name milvus-minio \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ACCESS_KEY=minioadmin \
  -e MINIO_SECRET_KEY=minioadmin \
  -v /opt/milvus/minio:/minio_data \
  --restart always \
  minio/minio:RELEASE.2023-03-20T20-16-18Z \
  minio server /minio_data --console-address ":9001"

步骤 4：启动 Milvus

bash 复制代码

docker run -d --name milvus-standalone \
  -p 19530:19530 -p 9091:9091 \
  -e ETCD_ENDPOINTS=etcd:2379 \
  -e MINIO_ADDRESS=minio:9000 \
  --link milvus-etcd:etcd \
  --link milvus-minio:minio \
  -v /opt/milvus/milvus:/var/lib/milvus \
  --restart always \
  milvusdb/milvus:v2.5.4 \
  milvus run standalone

步骤 5：验证容器状态

bash 复制代码

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

正常情况下应看到三个容器均为 Up 状态：

复制代码

NAMES                STATUS         PORTS
milvus-standalone    Up 2 minutes   0.0.0.0:19530->19530/tcp, 0.0.0.0:9091->9091/tcp
milvus-etcd          Up 3 minutes   0.0.0.0:2379->2379/tcp
milvus-minio         Up 3 minutes   0.0.0.0:9000->9000/tcp, 0.0.0.0:9001->9001/tcp

四、方式二：Docker Compose 部署（推荐）

Docker Compose 方式一键管理全部组件，是最简单的部署方式。

步骤 1：下载 docker-compose.yml

bash 复制代码

cd /opt/milvus

# 下载官方配置文件
wget https://github.com/milvus-io/milvus/releases/download/v2.5.4/milvus-standalone-docker-compose.yml -O docker-compose.yml

国内加速： 如果 GitHub 下载慢，可使用代理或手动下载后上传到服务器。

步骤 2：启动服务

bash 复制代码

# 在 docker-compose.yml 所在目录执行
cd /opt/milvus
docker compose up -d

步骤 3：查看运行状态

bash 复制代码

docker compose ps

三个容器都应处于 healthy 状态：

复制代码

      Name                     Command                  State                            Ports
---------------------------------------------------------------------------------------------------------------
milvus-etcd        etcd -advertise-client-url...   Up (healthy)   2379/tcp
milvus-minio       minio server /minio_data        Up (healthy)   0.0.0.0:9000->9000/tcp, 0.0.0.0:9001->9001/tcp
milvus-standalone  milvus run standalone           Up (healthy)   0.0.0.0:19530->19530/tcp, 0.0.0.0:9091->9091/tcp

步骤 4：停止与重启

bash 复制代码

# 停止
docker compose down

# 停止并删除数据卷（谨慎！会清除所有数据）
docker compose down -v

# 重新启动
docker compose up -d

提示： Docker Compose 方式会自动管理 etcd、MinIO 和 Milvus 的依赖关系，无需手动 --link。

五、防火墙与端口配置

开放必要端口

端口	用途	是否需要对外
19530	Milvus gRPC（客户端连接）	是（仅限可信网络）
9091	Milvus HTTP API / Metrics	否（内部监控）
2379	etcd 客户端端口	否（仅内部）
9000	MinIO S3 API	否（仅内部）
9001	MinIO 管理控制台	按需

FirewallD 配置（CentOS 默认）

bash 复制代码

# 开放 Milvus 端口
sudo firewall-cmd --permanent --add-port=19530/tcp
sudo firewall-cmd --permanent --add-port=9091/tcp

# 如果需要从外部访问 MinIO 控制台
sudo firewall-cmd --permanent --add-port=9001/tcp

# 重新加载防火墙
sudo firewall-cmd --reload

# 验证规则
sudo firewall-cmd --list-ports

限制访问来源（推荐）

bash 复制代码

# 只允许特定 IP 访问 Milvus 端口
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="19530" protocol="tcp" accept'
sudo firewall-cmd --reload

安全警告： 不要将 19530 端口直接暴露到公网。生产环境应通过 VPN、内网或反向代理（Nginx + TLS）访问。

六、安装 Attu 可视化管理工具

Attu 是 Milvus 官方提供的 Web 管理界面，可以直观地查看 Collection、浏览数据、执行搜索和管理索引。

Attu 版本选择

Milvus 版本	推荐 Attu 版本	镜像标签
Milvus 2.5.x	Attu v2.4.x	`zilliz/attu:v2.4.0`
Milvus 2.4.x	Attu v2.4.x	`zilliz/attu:v2.4.0`
Milvus 2.6.x / 3.x	Attu v3.0	`zilliz/attu:v3.0.0-beta.6`

启动 Attu

bash 复制代码

docker run -d --name attu \
  -p 8000:3000 \
  --restart always \
  zilliz/attu:v2.4.0

访问与连接

浏览器打开 http://<服务器IP>:8000
在连接页面填写：
- Address ：服务器IP:19530
- Username：留空（未开启认证时）
- Password：留空
点击 Connect 即可进入管理界面

注意： 如果 Attu 和 Milvus 都在 Docker 中，且 Milvus 使用 bridge 网络，Attu 可能无法通过 localhost 访问 Milvus。解决方案：

使用 --network host 启动 Attu

或将 Address 填写服务器实际 IP 而非 localhost

开放 Attu 端口

bash 复制代码

sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

七、验证部署与基础操作

使用 pymilvus 验证连接

bash 复制代码

# 安装 pymilvus
pip install pymilvus

python 复制代码

from pymilvus import connections, utility

# 连接到 Milvus
connections.connect(
    host="192.168.1.245",
    port="19530"
)

# 查看所有 Collection
print("Collections:", utility.list_collections())

# 查看版本
print("Milvus version:", utility.get_server_version())

创建测试 Collection

python 复制代码

from pymilvus import connections, Collection, FieldSchema, CollectionSchema, DataType

connections.connect(host="192.168.1.245", port="19530")

# 定义 Schema
fields = [
    FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
    FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=128),
    FieldSchema(name="content", dtype=DataType.VARCHAR, max_length=512),
]
schema = CollectionSchema(fields=fields, description="test collection")

# 创建 Collection
collection = Collection(name="test_collection", schema=schema)

# 创建 HNSW 索引
collection.create_index(
    field_name="embedding",
    index_params={
        "index_type": "HNSW",
        "metric_type": "COSINE",
        "params": {"M": 16, "efConstruction": 200}
    }
)

# 加载到内存
collection.load()

print(f"Collection created: {collection.name}")
print(f"Num entities: {collection.num_entities}")

八、开机自启与数据持久化

Docker 容器自动重启

前面的命令中已通过 --restart always 实现了容器开机自启。验证：

bash 复制代码

# 检查重启策略
docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' milvus-standalone
# 应输出: always

Docker Compose 方式配置自启

编辑 docker-compose.yml，在每个服务下添加：

yaml 复制代码

services:
  milvus:
    restart: always
    # ... 其他配置
  etcd:
    restart: always
  minio:
    restart: always

数据持久化验证

组件	容器内路径	宿主机路径
Milvus	/var/lib/milvus	/opt/milvus/milvus
etcd	/etcd	/opt/milvus/etcd
MinIO	/minio_data	/opt/milvus/minio

备份建议： 定期备份 /opt/milvus/etcd 和 /opt/milvus/minio 目录。etcd 存储元数据，MinIO 存储向量数据，两者缺一不可。

九、性能调优与资源建议

系统内核参数优化

bash 复制代码

# 提升最大文件句柄数
sudo tee -a /etc/security/limits.conf <<-'EOF'
* soft nofile 65535
* hard nofile 65535
EOF

# 调整内核参数
sudo tee -a /etc/sysctl.conf <<-'EOF'
vm.max_map_count=262144
vm.swappiness=10
net.core.somaxconn=65535
EOF

sudo sysctl -p

资源分配建议

场景	配置	说明
开发 / 测试	4C 8G，50GB 磁盘	可跑 10 万级向量，适合功能验证
小型生产	8C 16G，100GB SSD	可承载 100 万级向量，适合 RAG 应用
中型生产	16C 32G，200GB NVMe	可承载 500 万级向量，适合推荐系统
大型生产	32C 64G+，500GB NVMe	建议集群部署，千万级以上向量

内存估算公式

复制代码

所需内存 ≈ 向量数量 × 维度 × 4字节 × 索引倍数 × 1.5（冗余系数）

# 示例：100万条 768 维向量 + HNSW 索引
# = 1000000 × 768 × 4 × 2 × 1.5
# ≈ 9.2 GB（仅向量数据部分）

十、常见问题排查

1. 容器启动失败

bash 复制代码

# 查看容器日志
docker logs milvus-standalone --tail 100

# 查看所有容器（包括已停止的）
docker ps -a

2. 端口被占用

bash 复制代码

# 查看端口占用
sudo netstat -tlnp | grep 19530

# 杀掉占用进程
sudo kill -9 <PID>

# 或修改 Milvus 映射端口
docker run -d --name milvus-standalone -p 19531:19530 ...

3. 内存不足导致 OOM

bash 复制代码

# 查看系统内存
free -h

# 查看 OOM 日志
sudo dmesg | grep -i "killed process"

# 解决：增加 swap 或使用 IVF_SQ8/DISKANN 减少内存占用

4. SDK 版本不兼容

高频问题： Milvus 服务端版本与 SDK 版本不一致，导致 HNSW 索引参数格式不兼容（如 efConstruction out of range）。

解决： 确保 SDK 版本与 Milvus 服务端版本匹配。Milvus 2.5.x 对应 Milvus Java SDK 2.5.x、pymilvus 2.5.x。

5. Docker Compose 下载超时

bash 复制代码

# 方案 1：使用国内代理下载
curl -L -o docker-compose.yml \
  https://ghproxy.com/https://github.com/milvus-io/milvus/releases/download/v2.5.4/milvus-standalone-docker-compose.yml

# 方案 2：手动下载后通过 scp 上传到服务器
scp docker-compose.yml user@server:/opt/milvus/

6. Milvus 健康检查未通过

bash 复制代码

# 检查健康状态
docker inspect --format '{{.State.Health.Status}}' milvus-standalone

# 手动检查 Milvus 是否响应
curl http://localhost:9091/healthz

十一、卸载与清理

停止并删除容器

bash 复制代码

# Docker Compose 方式
cd /opt/milvus
docker compose down -v

# Docker 单容器方式
docker rm -f milvus-standalone milvus-etcd milvus-minio

删除数据（谨慎操作）

bash 复制代码

# 删除持久化数据
sudo rm -rf /opt/milvus/etcd /opt/milvus/minio /opt/milvus/milvus

# 删除 docker-compose.yml
rm -f /opt/milvus/docker-compose.yml

删除 Attu

bash 复制代码

docker rm -f attu

警告： 删除数据目录会导致所有 Collection 和向量数据永久丢失，操作前请确认已备份重要数据。