Milvus向量数据库部署实战：Operator集群与Docker Compose单机教程

这两天给开发搭了一套 Milvus 组件的基础环境，顺手把部署配置过程整理出来。因为篇幅比较长，拆成两篇来写，这一篇先聊部署。

一、简介

Milvus 是由 Zilliz 发起、捐赠给 LF AI & Data 基金会的开源云原生向量数据库，专为 GenAI 应用构建。它的核心任务是存储、索引、检索深度学习模型输出的 Embedding 向量——把文本、图片、音频、视频这类非结构化数据转成向量后，实现向量相似度检索。

核心特点：

• 开源，Apache 2.0 许可证，完全开源
• 专为 GenAI 设计，面向 AI 应用的高性能向量检索
• 高速检索，支持以极低性能损失实现高速度搜索
• 海量扩展，可扩展至数百亿向量，性能损耗极小
• 生态友好，提供 Python、Java、Go、Node.js、REST API，深度适配大模型 RAG 框架（LangChain、LlamaIndex）

典型应用场景：

1. RAG 检索增强生成

大模型知识库的典型玩法：把文档、PDF、网页转成 Embedding 存入 Milvus；用户提问时检索相关片段，喂给大模型。这个套路能解决大模型幻觉、私有知识问答，落地在企业知识库、智能客服、企业 AI 助手等方向。如果你正在做模型 API 接入或搭建 RAG 流水线，通常还需要一个稳定的 模型 API 中转方案，把 Claude、GPT、Gemini 等模型的调用统一管理起来。

2. 多模态检索

• 图像检索：以图搜图、商品图片搜索、版权图片查重
• 音频检索：语音片段检索、声音相似匹配
• 图文混合搜索：输入文字找图片、图片搜文字

3. 推荐系统

用户、物品向量化后，做相似商品推荐、内容推荐、用户兴趣召回。

4. 去重、风险检测

文本去重、评论内容查重；内容风控、相似文本检测、恶意内容聚类识别。

5. AI Agent 记忆

Agent 把对话、历史经验向量化存入 Milvus，实现长期记忆与历史上下文检索。

6. 生物、科研向量检索

特征向量检索，分子、基因向量相似度分析等科研场景。

架构：https://milvus.io/docs/zh/architecture_overview.md

Milvus 集群由五个核心组件和三个第三方依赖组件构成：

• 核心组件
  • 协调器：可启用主从模式，提供高可用性
  • 代理：每个集群一个或多个
  • 流节点：每个集群一个或多个
  • 查询节点：每个集群一个或多个
  • 数据节点：每个集群一个或多个
• 第三方依赖
  • 元存储：存储 Milvus 中各组件的元数据，如 etcd
  • 对象存储：负责 Milvus 中索引和二进制日志文件等大型文件的数据持久化，例如 S3
  • WAL 存储：为 Milvus 提供先写日志（WAL）服务，如 Woodpecker。在啄木鸟零磁盘模式下，WAL 直接使用对象存储和元存储，无需额外部署，减少第三方依赖

部署模式及适用场景：

部署模式	适用场景
Milvus Lite	轻量级，适合笔记本/学习/原型开发（pip 安装）
Milvus Standalone	单机生产部署，适合百万级向量的数据集
Milvus Distributed	企业级分布式方案，横向扩展处理数十亿向量
Zilliz Cloud	Milvus 托管的全托管云服务

github: https://github.com/milvus-io/milvus

官方文档：https://milvus.io/docs/zh/quickstart.md

operator: https://github.com/zilliztech/milvus-operator/

二、部署

2.1 Milvus Operator（Distributed 模式，生产环境）

每个组件独立运行，可弹性扩展。这套方案适合大型数据集和高负荷场景。

组件要求：

• etcd 3.5.0
• MinIO RELEASE.2024-12-18T13-15-44Z
• Woodpecker v0.1.37+
• Pulsar 2.8.2（Milvus 支持四种消息队列：rocksmq（基于 RocksDB）、Pulsar、Kafka 和 Woodpecker）
• k8s 1.16+

硬件需求可通过 Milvus Sizing Tool 查询不同数据量下的资源配置：

• 单机：4c8g+
• 集群：8c32G+，内存取决于数据量

磁盘性能测试：IOPS 应超过 500，fsync 延迟应低于 10ms

$ mkdir test-data
$ fio --rw=write --ioengine=sync --fdatasync=1 --directory=test-data --size=2200m --bs=2300 --name=mytest

1. 安装 operator

$ helm install milvus-operator \
-n milvus-operator --create-namespace \
--wait --wait-for-jobs \
https://github.com/zilliztech/milvus-operator/releases/download/v1.3.7/milvus-operator-1.3.7.tgz

如果已经安装过、需要更新配置，用下面的命令：

$ helm upgrade milvus-operator \
-n milvus-operator --create-namespace \
--wait --wait-for-jobs \
https://github.com/zilliztech/milvus-operator/releases/download/v1.3.7/milvus-operator-1.3.7.tgz

2. 创建 Milvus cluster 实例

$ kubectl apply -f https://raw.githubusercontent.com/zilliztech/milvus-operator/main/config/samples/milvus_cluster_woodpecker.yaml

如果要自定义参数，参考：https://milvus.io/docs/system_configuration.md

3. 检查状态

$ kubectl get pods

NAME                                                  READY   STATUS    RESTARTS   AGE
my-release-etcd-0                                     1/1     Running   0          2m36s
my-release-etcd-1                                     1/1     Running   0          2m36s
my-release-etcd-2                                     1/1     Running   0          2m36s
my-release-milvus-datanode-58955c65b9-j4j7s            1/1     Running   0          92s
my-release-milvus-mixcoord-686f84968f-jcv5d            1/1     Running   0          92s
my-release-milvus-proxy-646f48fc7c-4lctb               1/1     Running   0          92s
my-release-milvus-querynode-0-d89d7677b-x7j7q          1/1     Running   0          91s
my-release-milvus-streamingnode-556bdcc87c-2qwcc       1/1     Running   0          92s
my-release-minio-0                                    1/1     Running   0          2m36s
my-release-minio-1                                    1/1     Running   0          2m36s
my-release-minio-2                                    1/1     Running   0          2m36s
my-release-minio-3                                    1/1     Running   0          2m35s

从输出可以看到，这个集群默认带上了：

• Woodpecker 消息队列
• Streaming Node 流节点，增强数据处理
• Mix Coordinator 混合协调器，提高效率

4. 暴露端口测试

# 查看端口，默认是19350
$ kubectl get pod my-release-milvus-proxy-84f67cdb7f-pg6wf --template \
='{{(index (index .spec.containers 0).ports 0).containerPort}}{{"\n"}}'

# 临时代理端口测试
$ kubectl port-forward --address 0.0.0.0 service/my-release-milvus 27017:19530

# 暴露web ui
$ kubectl port-forward --address 0.0.0.0 service/my-release-milvus 27018:9091

5. 更新与卸载

通过 patch 更新参数示例：

# 试运行
$ kubectl patch milvus my-release --type='merge'\
-p '{"spec":{"components":{"disableMetric":false}}}' \
--dry-run=client -o yaml

# 正式修改
$ kubectl patch milvus my-release --type='merge'\
-p '{"spec":{"components":{"disableMetric":false}}}'

卸载：

# 卸载实例
$ kubectl delete milvus my-release

# 卸载operator
$ helm -n milvus-operator uninstall milvus-operator

6. 扩缩容

参考：https://milvus.io/docs/hpa.md

将相应组件的 replica 设置为 -1（以 proxy 组件为例）：

使用 kubectl patch：

$ kubectl patch milvus --type='json' -p='[{"op": "replace", "path": "/spec/components/proxy/replicas", "value": -1}]'

或者在 CR 的 yaml 中定义：

apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
  name:
spec:
  mode: cluster
  components:
    proxy:
      replicas: -1

定义 HPA 资源：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-release-milvus-proxy-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-release-milvus-proxy
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 60
  behavior:
    scaleUp:
      policies:
      - type: Pods
        value: 1
        periodSeconds: 30
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Pods
        value: 1
        periodSeconds: 60

应用 HPA 资源：

$ kubectl apply -f hpa.yaml
$ kubectl get hpa

2.2 Docker Compose（Standalone 模式，开发测试环境）

在一个进程中运行所有组件的 Milvus 单实例，适用于数据集小、工作量小的情况。在 Standalone 模式下，可以选择更简单的 WAL 实现，如 Woodpecker 和 rocksmq，消除对第三方 WAL 存储的依赖。对于小规模验证场景，用 Docker Compose 拉起一套单机环境是最省事的路径。

环境要求：

• Docker 19.03+
• Docker Compose 1.25.1+

1. 下载 docker-compose.yml

$ wget https://github.com/milvus-io/milvus/releases/download/v3.0.1/milvus-standalone-docker-compose.yml -O docker-compose.yml
$ cat docker-compose.yml

version: '3.5'

services:
  etcd:
    container_name: milvus-etcd
    image: quay.io/coreos/etcd:v3.5.25
    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-12-18T13-15-44Z
    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:v3.0.1
    command: ["milvus", "run", "standalone"]
    security_opt:
      - seccomp:unconfined
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
      MQ_TYPE: woodpecker
    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:
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - "etcd"
      - "minio"

networks:
  default:
    name: milvus

2. 启动

$ docker compose up -d

3. 查看状态

$ docker compose ps

4. 访问 web ui

http://<server ip>:9091/webui/

部署部分到这里就完成了，下一篇继续介绍 Milvus 的连接配置与基础使用。