[向量数据库/AI] Milvus 安装部署篇

1 概述：Milvus 向量数据库之安装部署篇

前置知识: Milvus 向量数据库

硬件要求

  • Milvus Standalone 部署模式的最低硬件要求为 4 核 CPU 和 8 GB 内存

端口占用情况

  • 端口占用情况

Milvus (Standalone / Distributed ) 支持 19530 和 9091 两个端口

  • 端口 19530 : 用于 gRPC 和 RESTful API。

这是您使用不同 Milvus SDK 或 HTTP 客户端连接到 Milvus 服务器时的默认端口。

  • 端口 9091 : 作为管理端口，用于 Kubernetes 内的指标收集、pprof 分析和运行状况探测。

部署模式

部署模式 维护状态 适用场景 数据规模
Milvus Lite ✅ 活跃维护 快速原型开发、Jupyter Notebook、边缘设备 数百万向量以内
Milvus Standalone ✅ 活跃维护 中小规模生产环境、早期产品阶段 最高可达1亿向量
Milvus Distributed ✅ 活跃维护 大规模生产、企业级部署 数亿至数百亿向量
  • Milvus Lite：作为 Python 库集成在 pymilvus 中，持续更新。最新版本可通过 pip install pymilvus 直接安装使用，无需额外启动服务端，数据持久化通过本地文件实现。
  • 仅适用于小规模原型设计（通常少于 100 万个矢量）或边缘设备。
  • 适合场景: Jupyter Notebook / 谷歌 Colab; 笔记本 电脑; 边缘设备
  • Milvus Standalone：所有组件打包在单个 Docker 镜像中，支持主备模式实现高可用，适合生产环境部署。官方文档明确说明该模式仍在持续维护，并支持扩展到1亿向量的规模。
  • Milvus Distributed：采用云原生架构，支持 Kubernetes 部署。最新版本（如 v2.5.x）仍在积极开发和维护中，社区讨论显示用户正在使用 v2.5.2-gpu 等较新版本进行部署测试

Milvus Lite

image

  • Milvus Lite 是 Milvus 的轻量级版本

Milvus 是一个高性能矢量数据库，通过矢量相似性搜索为 AI 应用程序提供支持。
该存储库包含 Milvus Lite 的核心组件。

  • 使用 Milvus Lite，您可以在几分钟内开始构建具有向量相似性搜索的 AI 应用程序！Milvus Lite 适合在以下环境中运行：
  • Jupyter Notebook / 谷歌 Colab
  • 笔记本 电脑
  • 边缘设备
  • Milvus Lite 可以导入到您的 Python 应用程序中，提供 Milvus 的核心矢量搜索功能。

Milvus Lite 已经包含在 Milvus 的 Python SDK 中。
要使用它，您只需要: pip install pymilvus

  • Milvus Lite 使用与 Milvus Standalone 和 Distributed 相同的 API，提供跨环境的一致体验。
  • 只需开发一次 GenAI 应用程序，即可在任何地方运行它们：

在笔记本电脑或 Jupyter Notebook 上使用 Milvus Lite，
在 Docker 容器中使用 Milvus Standalone，
或者在 K8s 集群上使用 Milvus Distributed 进行大规模生产。

image

  • Milvus Lite 仅适用于小规模原型设计（通常少于 100 万个矢量）或边缘设备。
  • Milvus-Lite
  • Milvus Lite 目前支持以下环境：
  • Ubuntu >= 20.04（x86_64 和 arm64）
  • MacOS >= 11.0（Apple Silicon M1/M2 和 x86_64）

注意：尚不支持 Windows。

Milvus Standalone

Milvus Distributed

Milvus Lite + Pip 安装方式 (Milvue-Lite:2.2.16) 【不推荐/未亲测成功】

Step0 安装 conda 虚拟环境管理器，并创建、启用虚拟环境

  • 安装 conda 虚拟环境管理器
  • 参考文献
  • 创建、启用虚拟环境

例如: ai-env

//添加第三方源，避免 python=3.12 及部分依赖包不支持、下载官方源的速度太慢等问题
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/bioconda/

conda create --name ai-env python=3.12

conda activate ai-env

C:\Users\xxx\.conda\envs\ai-env\python.exe

  • 环境验证
(ai-env) C:\Users\Xxx> python --version
Python 3.12.11

(ai-env) C:\Users\Xxx> pip --version
pip 25.2 from C:\Users\EDY\.conda\envs\ai-env\Lib\site-packages\pip (python 3.12)

Step1 基于 pip 安装 milvus-lite

  • 本地任意位置新建一个空文件夹作为服务器的存储位置

例如: D:\data\milvus-server\

image

  • 基于 pip 安装 milvus 服务端

其一，会默认安装较低版本的 2.2.16；其二, pip的milvus项目已被弃用(https://pypi.org/project/milvus/)，其建议使用milvus-lite项目(https://pypi.org/project/milvus-lite/)
不建议使用此命令

(ai-env) C:\Users\Xxx> pip install milvus 
Looking in indexes: https://mirrors.aliyun.com/pypi/simple
Collecting milvus
  Downloading https://mirrors.aliyun.com/pypi/packages/ab/8f/2a24d629f194c1bc83725652a9341794fbab09d0de978d5e5ec72e1f80e4/milvus-2.2.16-py3-none-win_amd64.whl (38.6 MB)
     ---------------------------------------- 38.6/38.6 MB 13.0 MB/s  0:00:03
Installing collected packages: milvus
Successfully installed milvus-2.2.16

image

【补充】卸载命令

pip uninstall milvus

image

卸载完成后，上一步创建的 milvus-server(即 milvus-lite) 的数据目录不会自动删除，需要自己手动移除。

Step2 启动 milvus-server

(ai-env) C:\Users\Xxx> milvus-server --data D:\code\serve\milvus

Milvus 数据库服务已正常启用（如图）

image

Step3 Milvus客户端(应用程序): 连接、验证

安装依赖包: pymilvus

  • 安装Python应用程序的Milvus客户端依赖包
(ai-env) C:\Users\Xxx> pip install pymilvus
查看详情 
(ai-env) C:\Users\Xxx> pip install pymilvus
Looking in indexes: https://mirrors.aliyun.com/pypi/simple
Collecting pymilvus
  Downloading https://mirrors.aliyun.com/pypi/packages/d9/78/ab628de53ae36c2a4519e8d56e09604b2ff6e8084538cb058cdbff42a564/pymilvus-2.6.2-py3-none-any.whl (258 kB)
Requirement already satisfied: setuptools>69 in c:\users\edy\.conda\envs\ai-env\lib\site-packages (from pymilvus) (80.9.0)
Collecting grpcio!=1.68.0,!=1.68.1,!=1.69.0,!=1.70.0,!=1.70.1,!=1.71.0,!=1.72.1,!=1.73.0,>=1.66.2 (from pymilvus)
  Downloading https://mirrors.aliyun.com/pypi/packages/ff/14/e1309a570b7ebdd1c8ca24c4df6b8d6690009fa8e0d997cb2c026ce850c9/grpcio-1.75.0-cp312-cp312-win_amd64.whl (4.6 MB)
     ---------------------------------------- 4.6/4.6 MB 11.2 MB/s  0:00:00
Collecting protobuf>=5.27.2 (from pymilvus)
  Downloading https://mirrors.aliyun.com/pypi/packages/8c/f3/6f58f841f6ebafe076cebeae33fc336e900619d34b1c93e4b5c97a81fdfa/protobuf-6.32.1-cp310-abi3-win_amd64.whl (435 kB)
Requirement already satisfied: python-dotenv<2.0.0,>=1.0.1 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pymilvus) (1.0.1)
Collecting ujson>=2.0.0 (from pymilvus)
  Downloading https://mirrors.aliyun.com/pypi/packages/44/1b/27c05dc8c9728f44875d74b5bfa948ce91f6c33349232619279f35c6e817/ujson-5.11.0-cp312-cp312-win_amd64.whl (43 kB)
Requirement already satisfied: pandas>=1.2.4 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pymilvus) (2.2.3)
Requirement already satisfied: typing-extensions~=4.12 in c:\users\edy\appdata\roaming\python\python312\site-packages (from grpcio!=1.68.0,!=1.68.1,!=1.69.0,!=1.70.0,!=1.70.1,!=1.71.0,!=1.72.1,!=1.73.0,>=1.66.2->pymilvus) (4.12.2)
Requirement already satisfied: numpy>=1.26.0 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pandas>=1.2.4->pymilvus) (2.2.4)
Requirement already satisfied: python-dateutil>=2.8.2 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pandas>=1.2.4->pymilvus) (2.9.0.post0)
Requirement already satisfied: pytz>=2020.1 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pandas>=1.2.4->pymilvus) (2024.2)
Requirement already satisfied: tzdata>=2022.7 in c:\users\edy\appdata\roaming\python\python312\site-packages (from pandas>=1.2.4->pymilvus) (2024.2)
Requirement already satisfied: six>=1.5 in c:\users\edy\appdata\roaming\python\python312\site-packages (from python-dateutil>=2.8.2->pandas>=1.2.4->pymilvus) (1.17.0)
Installing collected packages: ujson, protobuf, grpcio, pymilvus
Successfully installed grpcio-1.75.0 protobuf-6.32.1 pymilvus-2.6.2 ujson-5.11.0

连接与验证

  • 另开一窗口，进入 python 环境
(ai-env) C:\Users\Xxx> python
  • 代码验证
import logging
from pymilvus import connections, Collection, CollectionSchema, FieldSchema, DataType
 
# 配置日志记录
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
 
# 连接到 Milvus 服务
try:
    connections.connect(alias="default", uri="http://localhost:19530")
    logging.info("成功连接到Milvus服务")
except Exception as e:
    logging.error(f"连接Milvus服务失败: {e}")
    raise

image

出现"成功连接到Milvus服务"，即说明连接/验证成功

Milvue Lite + Pip 安装方式 (Milvue-Lite:2.5.1) 【不推荐/亲测未成功】

  • 操作系统: CENTOS 7.9 (亲测: 尚不支持 Windows)
  • Step0 安装 conda 虚拟环境管理器，并创建、启用虚拟环境

参考 : Pip 安装方式 (Milvue-Lite:2.2.16)

  • Step1 基于 pip 安装 milvus-lite
(ai-env) [root@xxx ~]# pip install milvus-lite>=2.5.1

(ai-env) [root@xxx ~]# pip list | grep "milvus"
milvus-lite 2.5.1

  • Step2 启动 milvus-server(milvus-lite) 【无需此步骤】

  • Step2 Milvus客户端(应用程序): 连接、验证

image

Milvus Standalone + Docker 容器方式 【推荐/亲测成功】

以 ubuntu 24 (阿里云ECS, 4c 8gb)为例

step1 安装 Docker 和 Docker Compose

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装必要依赖
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# 添加阿里云 Docker 镜像源
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动 Docker
sudo systemctl start docker
sudo systemctl enable docker

# 配置阿里云镜像加速（重要）
## 解释: https://<你的阿里云镜像加速器地址>.mirror.aliyuncs.com 的获取方法:
### 方法1: 登录阿里云容器镜像服务控制台获取专属镜像加速器地址
#### 访问 https://cr.console.aliyun.com/cn-hangzhou/instances/mirrors
### 方法2: 通过阿里云CLI命令获取相关信息
#### aliyun cr GetInstance endpoint=<your-region-id>

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://<你的阿里云镜像加速器地址>.mirror.aliyuncs.com",
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io"
  ]
}
EOF

# 注：这样 docker pull milvusdb/milvus:v2.5.21 会自动走华为云镜像等指定的第三方镜像仓库，而无需修改 Compose 文件或手动打标签。


sudo systemctl daemon-reload
sudo systemctl restart docker

💡 获取阿里云镜像加速器：登录阿里云控制台 → 容器镜像服务 → 镜像加速器

  • 补充: 基于国内服务器安装完成 docker 后，如何验证能够正常下载国外镜像？
# step1 直接拉取镜像
## 注: 成功标志：看到 `Status: Downloaded newer image for xxx` 或 `Status: Image is up to date for xxx`
# 拉取一个轻量级国外官方镜像进行测试
docker pull hello-world
# 或拉取 Alpine Linux（体积小，速度快）
docker pull alpine:latest
# 或拉取 Nginx 官方镜像
docker pull nginx:latest


# step2 验证镜像是否成功下载
docker images | grep alpine


# step3 运行测试容器验证完整性
docker run --rm alpine:latest echo "镜像运行正常"

step2 下载 Milvus 配置文件（使用国内代理）

# 创建工作目录
mkdir -p ~/milvus && cd ~/milvus

# 下载 docker-compose.yml（使用 GitHub 代理或手动下载）
# 方案A：使用 ghproxy 代理
wget https://ghproxy.com/https://github.com/milvus-io/milvus/releases/download/v2.5.21/milvus-standalone-docker-compose.yml -O docker-compose.yml

# 如果上面失败，使用方案B：手动创建
cat > docker-compose.yml << 'EOF'
version: '3.5'

services:
  etcd:
    container_name: milvus-etcd
    image: quay.io/coreos/etcd:v3.5.18
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
    command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
    healthcheck:
      test: ["CMD", "etcdctl", "endpoint", "health"]
      interval: 30s
      timeout: 20s
      retries: 3

  minio:
    container_name: milvus-minio
    image: minio/minio:RELEASE.2024-05-28T17-19-04Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    ports:
      - "9001:9001"
      - "9000:9000"
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
    command: minio server /minio_data --console-address ":9001"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  standalone:
    container_name: milvus-standalone
    image: milvusdb/milvus:v2.5.21
    command: ["milvus", "run", "standalone"]
    security_opt:
      - seccomp:unconfined
    environment:
      MINIO_REGION: us-east-1
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      start_period: 90s
      timeout: 20s
      retries: 3
    ports:
      #- "127.0.0.1:19530:19530"  # 仅本地回环接口
      #- "127.0.0.1:9091:9091"    # 仅本地回环接口
      #- "0.0.0.0:19530:19530"    # 接收所有来源IP（同下）
      #- "0.0.0.0:9091:9091"      # 接收所有来源IP（同下）
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - "etcd"
      - "minio"

networks:
  default:
    name: milvus
EOF

step3 启用 账号密码认证（可选）

编辑 docker-compose.yml

在 standalone.volumes 下编辑，新增

    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
      # 新增如下4行配置项:
      # 挂载自定义配置文件（关键步骤）
      # - ${DOCKER_VOLUME_DIRECTORY:-.}/milvus.yaml:/milvus/configs/milvus.yaml # 官方配置模板: https://raw.githubusercontent.com/milvus-io/milvus/master/configs/milvus.yaml 
      # 或使用额外的用户配置
      - ${DOCKER_VOLUME_DIRECTORY:-.}/user.yaml:/milvus/configs/user.yaml

新增并编辑user.yaml

cat > ~/milvus/user.yaml << 'EOF'
common:
  security:
    authorizationEnabled: true
EOF

重启 milvus

# 重启 Milvus 服务
docker compose restart standalone

# 或完全重新创建容器
docker compose down
docker compose up -d

image

连接方式变更

  • 启用认证后，默认账户信息为：
  • 用户名: root / 密码: Milvus
  • python sdk 示例
from pymilvus import MilvusClient

# 方式1：使用 token（推荐）
client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"  # 格式：用户名:密码
)

# 方式2：使用 user/password 参数
client = MilvusClient(
    uri="http://localhost:19530",
    user="root",
    password="Milvus"
)

密码错误时将报错: "auth check failure, please check username and password are correct"

  • 修改默认密码
from pymilvus import connections, utility

# 使用默认账户连接
connections.connect(
    alias='default',
    host='localhost',
    port='19530',
    user='root',
    password='Milvus'
)

# 修改 root 密码
utility.reset_password('root', 'Milvus', 'YourNewStrongPassword', using='default')
  • 创建新用户（可选）

以 root 身份登录后，可以创建更多用户：

# 创建新用户
client.create_user(
    user_name="user_1",
    password="P@ssw0rd",
)

# 验证用户
client.describe_user("user_1")

step4 启动 Milvus

  • 基于 docker-compose.yaml 拉取指定镜像
# 拉取镜像（国内环境可能需要多次尝试）
sudo docker compose pull

# 注：可仅拉取指定服务，跳过 milvus 等镜像 （了解即可）
# docker compose pull etcd minio
# 注：可仅拉取指定服务，跳过 milvus 等镜像 （了解即可）
# docker compose up -d --no-deps --pull never milvus


docker images
  • 若 minio 镜像拉取失败，可尝试:
docker pull quay.io/minio/minio:RELEASE.2024-05-28T17-19-04Z

# 新增镜像标签
docker tag quay.io/minio/minio:RELEASE.2024-05-28T17-19-04Z minio/minio:RELEASE.2024-05-28T17-19-04Z

注： MinIO 官方主要将镜像发布在 Quay.io 仓库，而非 Docker Hub
根本原因：RELEASE.2024-05-28T17-19-04Z 这个特定标签在 Docker Hub 上可能已被删除或从未推送，MinIO 官方主要维护 quay.io 仓库。

image

  • 若 milvus 镜像拉取失败，可尝试:
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/milvusdb/milvus:v2.5.21

# 新增镜像标签
docker tag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/milvusdb/milvus:v2.5.21 docker.io/milvusdb/milvus:v2.5.21

从华为云等处拉取（但可能最新版镜像是缺乏的）

image

image

  • 启动服务
# 启动服务
## 启动方式1: 默认行为/本地存在目标镜像，则不再从远程仓库拉取
sudo docker compose up -d
## 启动方式2: 明确指定不从远程仓库拉取镜像
### always：总是拉取（默认行为） missing / if_not_present：本地不存在时才拉取 ⭐推荐 / never：永远不拉取，必须本地已存在 / build：优先使用本地构建的镜像
# sudo docker compose up -d --pull missing

image

  • 查看运行状态/日志等
# 查看状态
sudo docker compose ps

docker compose ls
> out:
NAME                STATUS              CONFIG FILES
milvus              running(3)          /root/milvus/docker-compose.yml

# 查看日志
sudo docker logs milvus-standalone -f

image

step5 验证/使用

  • 端口验证
curl http://127.0.0.1:19530 -v
  • 数据库服务验证 by python
# 安装 Python 客户端测试
pip3 install pymilvus

# 测试连接
python3 << 'EOF'
from pymilvus import MilvusClient, connections, utility

# 连接 Milvus
client = MilvusClient("http://localhost:19530")

# 检查版本
print(f"Milvus 版本: {client.get_server_version()}")

# 创建测试集合
client.create_collection(
    collection_name="test_collection",
    dimension=128,
    metric_type="COSINE"
)
print("集合创建成功！")

# 查看集合
print(f"集合列表: {client.list_collections()}")
EOF

Milvus Distributed + Kubernetes 安装方式（未亲测/适用于生产环境）

# 安装 kubectl 和 helm
curl -LO "https://dl.k8s/release/$(curl -L -s https://dl.k8s/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# 添加 Milvus Helm 仓库
helm repo add milvus https://zilliztech.github.io/milvus-helm/
helm repo update

# 安装 Milvus（指定国内镜像）
helm install my-milvus milvus/milvus --set cluster.enabled=false --set etcd.replicaCount=1 --set minio.mode=standalone --set image.repository=registry.cn-hangzhou.aliyuncs.com/milvusdb/milvus

2 WEB 管理工具: Attu / Milvus WEB-UI(9091)

https://github.com/zilliztech/attu/releases/download/v2.4.5/attu-docker-compose.yml -O attu-docker-compose.yml

Z FAQ for Milvus 安装部署

常见问题解决

问题 解决方案
镜像拉取失败 确认 Docker 镜像加速器配置正确，或手动 docker pull 替代镜像
端口被占用 sudo lsof -i :19530 查看占用，或修改 docker-compose.yml 端口映射
内存不足 Milvus 建议至少 8GB 内存，修改 docker-compose.yml 限制资源使用
防火墙问题 sudo ufw allow 19530/tcp 开放端口

Y 推荐文献

  • Milvus
  • 阿里云

https://your-mirror-url.mirror.aliyuncs.com

  • 华为云

X 参考文献

posted @ 2026-03-22 00:16  千千寰宇  阅读(1425)  评论(0)    收藏  举报