Milvus 生产环境部署，优化，日常维护中遇到的问题

Milvus 生产环境运维深度指南

一、架构全景

整个集群由四大层组成，每层独立扩展：

Access Layer Access Layer
Proxy Proxy Proxy → 负载均衡 → 客户端 SDK
│ │ │
Coordinator Layer
RootCoord QueryCoord DataCoord IndexCoord（单 Active）
│ │ │ │
Worker Layer
QueryNode DataNode IndexNode（可水平扩展，有状态）
│ │
Storage Layer
MinIO/S3（对象存储） + etcd（元数据） + Kafka/Pulsar（消息队列）

各组件职责与瓶颈

二、生产部署（Kubernetes + Operator）

集群规模规划

关键配置

apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
name: prod–milvus
namespace: milvus
spec:
mode: cluster
components:
image: milvusdb/milvus:v2.5.4
proxy:
replicas: 3
serviceType: ClusterIP
queryNode:
replicas: 3
resources:
requests:
memory: 32Gi
cpu: 8
limits:
memory: 48Gi
cpu: 16
dataNode:
replicas: 2
resources:
requests:
memory: 16Gi
cpu: 4
limits:
memory: 32Gi
cpu: 8
indexNode:
replicas: 1
resources:
requests:
memory: 16Gi
cpu: 8
limits:
memory: 32Gi
cpu: 16
dependencies:
etcd:
external: true
endpoints:
– etcd–0.etcd–headless:2379
storage:
external: true
endpoint: s3.amazonaws.com
bucket: milvus–prod
accessKey: "${AWS_ACCESS_KEY}"
secretKey: "${AWS_SECRET_KEY}"
msgStream:
external: true
kafka:
broker: kafka–broker:9092
config:
# 关键优化参数
queryNode:
cache:
cacheSize: 32 # QueryNode 缓存大小，单位 GB
warmup: async # 异步预热，避免启动阻塞
dataCoord:
segment:
maxSize: 512 # 单 Segment 最大 512MB
maxLifetime: 86400 # 24 小时强制 Flush
common:
security:
authorizationEnabled: true
tlsMode: 1
retentionDuration: 43200 # Binlog 保留 12 小时

为什么外部依赖要独立部署

• etcd：Milvus 内嵌的 etcd 不做持久化，重启后全集群元数据丢失。生产环境必须外部独立部署 3 节点 etcd 集群。
• MinIO/S3：内部 MinIO 无法做高可用。生产环境走 AWS S3 / 阿里云 OSS / Ceph。
• Kafka/Pulsar：内嵌 RocksMQ 无法处理 > 10MB/s 的写入吞吐，必须切外部 Kafka。

三、索引选型与调参

索引对比矩阵

调参原则

# HNSW 参数（小规模，精度优先）
index_params = {
"index_type": "HNSW",
"metric_type": "COSINE",
"params": {
"M": 32, # 节点连接数，越大精度越高，内存越大
"efConstruction": 200, # 构建时搜索宽度
"ef": 64 # 查询时搜索宽度（单独设置）
}
}

# IVF_FLAT 参数（通用，均衡）
index_params = {
"index_type": "IVF_FLAT",
"metric_type": "COSINE",
"params": {
"nlist": 2048, # 聚类数 = 4 × sqrt(N)，N 为向量数
"nprobe": 16 # 查询时搜索的聚类数，越大精度越高
}
}

黄金法则：nlist = 4 × sqrt(N)，nprobe 默认 16-32。

四、监控体系

必须监控的指标

Prometheus + Grafana 部署

# 使用官方 Grafana 仪表盘
cd deployments/monitor/grafana
docker-compose up -d

Milvus 暴露 /metrics 端点，Prometheus 自动抓取即可。

五、高频故障与排查

1. 索引构建失败（ErrorCode 21: BuildIndexError）

现象：fail to build index: out of memory

根因：大 Segment 索引构建时内存超过 IndexNode 限制。

排查链路：

# 1. 查看 IndexNode 内存
kubectl top pod -n milvus | grep indexnode

# 2. 查看当前构建任务
# 连接 Milvus 后执行
milvus_cli index -l

# 3. 查看 Segment 大小
# 在 DataCoord 日志中 grep "sealed segment"

修复：

• 降低 dataCoord.segment.maxSize 从 1024MB 到 512MB（减小 Segment 可降低索引构建峰值内存）
• 增大 IndexNode 内存限制
• 换用 IVF_FLAT 替代 HNSW（HNSW 构建时内存是 IVF 的 3-5 倍）

2. 查询延迟突然飙升（p99 > 500ms）

排查决策树：

查询变慢
├─ 所有查询都慢 → Proxy/QueryCoord 瓶颈
│ ├─ 检查 Proxy 连接数：netstat -an | grep 19530 | wc -l
│ └─ 检查 QueryCoord 频道分配：是否大量频道集中在单个 QueryNode
├─ 部分 Collection 慢 → 数据倾斜
│ ├─ 检查 Segment 分布：QueryNode 上 Segment 数量是否均衡
│ └─ 手动触发 LoadBalance：通过 MilvusOperator 配置
└─ 特定查询慢 → 索引或参数问题
├─ 检查 nprobe/ef 是否合理
└─ 检查过滤条件是否命中了未建索引的标量字段

修复：

• 给过滤字段创建标量索引
• 增加 QueryNode 副本数
• 减小 top_k 值
• 为 Collection 创建分区（Partition），用分区键过滤替代全量扫描

3. 内存溢出（OOM）

发生条件：

• QueryNode 同时加载的 Segment 过多
• HNSW 索引内存占用过大
• 大量并发查询的临时内存

修复：

queryNode:
memoryLimit: 48Gi # 上限
cache:
cacheSize: 24 # 缓存上限，设为 Pod 内存的 50%-60%
warmup: async
grouping:
maxNQ: 1000 # 单次查询最大向量数，防 OOM

4. Compaction 积压（小文件过多）

现象：/metrics 中 compaction_pending 持续增长，查询变慢。

根因：频繁小批量插入产生大量小 Segment，Compaction 合并速度跟不上。

修复：

# 1. 增大 Compaction 并发
# milvus.yaml
dataCoord:
compaction:
maxParallel: 4 # 默认 3

# 2. 批量写入，每次至少 1000 条
# 3. 触发手动 Compaction

collection.compact()

5. TSO 延迟（全集群卡死）

现象：所有操作超时，但各组件 Pod 均为 Running。

根因：RootCoord 单点故障或 etcd 响应慢，导致 TSO 分配延迟。

排查：

# 检查 RootCoord 是否存活
kubectl logs -n milvus deployment/rootcoord –tail=50 | grep -i "error\\|tso"

# 检查 etcd 延迟
etcdctl endpoint health

修复：确保 etcd 使用 SSD，RootCoord 为高可用部署（Active-Standby 模式，Milvus Operator 自动管理）。

六、升级策略

2.5 → 2.6 滚动升级（零停机）

严格按以下顺序执行 $TRAE_REF：

1. 备份数据（milvus-backup）
2. 拉新 Streaming Node
3. 迁移 Delegator 到新 Streaming Node
4. 滚动升级 MixCoord
5. 滚动升级 QueryNode
6. 滚动升级 DataNode
7. 滚动升级 IndexNode
8. 滚动升级 Proxy
9. 验证所有组件正常

升级前必须备份

# 安装
pip install milvus-backup

# 全量备份
milvus-backup backup \\
–host 127.0.0.1 \\
–collection "*" \\
–backup-path /backup/20250824

七、安全加固

common:
security:
authorizationEnabled: true
defaultRootPassword: "<强密码>"
tlsMode: 1 # 单向 TLS

创建 RBAC 用户：

from pymilvus import MilvusClient

client = MilvusClient(uri="https://milvus:19530", user="root", password="xxx")

# 创建只读用户
client.create_user(user_name="reader", password="xxx")
client.grant_role(user_name="reader", role_name="public")

# 创建读写用户
client.create_user(user_name="writer", password="xxx")
client.grant_role(user_name="writer", role_name="public")

八、运维检查清单

Milvus 生产运维的核心是三条线**：资源线（内存和 CPU 预留足够）、数据线（Segment 管理、Compaction、索引构建）、监控线（p99 延迟、OOM 预警、队列积压）。三条线都守住，基本不出大问题。**