Milvus 2.5.14 使用 milvus-backup v0.5.7 的备份实践
目录
Milvus 2.5.14 使用 milvus-backup v0.5.7 的备份实践
背景
部署环境
1. 安装 milvus-backup 工具
2. 确认 Milvus 服务信息
3. 编写 backup.yaml 配置
4. 执行备份
5. 遇到的问题及解决方案
(1) invalid key: log.file.rootpath
(2) invalid key: milvus.port 或 milvus.address
(3) 备份只有 meta 文件
(4) gcPause.address 配置错误
6. 数据验证
总结
Milvus 2.5.14 使用 milvus-backup v0.5.7 的备份实践
背景
在生产环境中，我们部署了 Milvus 2.5.14 集群，并使用 Helm 配置了外部 S3 作为存储后端。业务需求要求定期备份数据，以便跨环境迁移或灾难恢复。
在备份过程中，我们使用了官方工具 milvus-backup（版本 0.5.7），并踩到了一些配置上的坑，本文完整记录过程和解决方案。
部署环境
-
Milvus 版本：2.5.14
-
部署方式：Helm on Kubernetes
-
存储：外部 S3（MinIO 兼容）
-
S3 地址：
10.130.135.145:9000 -
S3 Bucket：
milvus-data -
S3 AccessKey / SecretKey：已用
*号替换
1. 安装 milvus-backup 工具
下载最新版 v0.5.7：
wget https://github.com/zilliztech/milvus-backup/releases/download/v0.5.7/milvus-backup_Linux_x86_64.tar.gz
tar -xzf milvus-backup_Linux_x86_64.tar.gz
chmod +x milvus-backup
mv milvus-backup /usr/local/bin/
2. 确认 Milvus 服务信息
查看 Kubernetes Service：
kubectl get svc -n milvus
输出：
NAME TYPE CLUSTER-IP PORT(S)
milvus ClusterIP 10.233.48.134 19530/TCP,9091/TCP
-
19530 → gRPC 客户端连接
-
9091 → HTTP API（gcPause 功能）
如果在集群内部运行 milvus-backup，可直接用 10.233.48.134；
如果在集群外运行，需要 kubectl port-forward：
kubectl port-forward svc/milvus 19530:19530 9091:9091 -n milvus
3. 编写 backup.yaml 配置
这是 v0.5.7 必须遵守的完整配置格式，注意 milvus.address 和 milvus.port 分开写，日志配置必须包含 log.file.rootPath。
log:
level: info
console: true
file:
rootPath: "logs/backup.log"
http:
simpleResponse: true
milvus:
address: 10.233.48.134
port: 19530
user: ""
password: ""
tlsMode: 0
rpcChannelName: "by-dev-replicate-msg"
minio:
storageType: "minio"
address: 10.130.135.145
port: 9000
accessKeyID: "FGNB*****"
secretAccessKey: "9VtCpfoO*****"
bucketName: "milvus-data"
rootPath: "files"
backupStorageType: "minio"
backupAddress: 10.130.135.145
backupPort: 9000
backupAccessKeyID: "FGNB*****"
backupSecretAccessKey: "9VtCpfoO*****"
backupBucketName: "milvus-data"
backupRootPath: "backup"
backupUseSSL: false
crossStorage: "false"
backup:
maxSegmentGroupSize: 2G
parallelism:
backupCollection: 4
copydata: 128
restoreCollection: 2
importJobNum: 768
gcPause:
enable: true
address: http://10.233.48.134:9091
4. 执行备份
创建备份：
milvus-backup create --config backup.yaml --set BACKUP_NAME=backup_$(date +%Y%m%d_%H%M%S)
恢复备份：
milvus-backup restore --config backup.yaml --set BACKUP_NAME=backup_20250723_153000
列出备份：
milvus-backup list --config backup.yaml
删除备份：
milvus-backup delete --config backup.yaml --set BACKUP_NAME=backup_20250723_153000
5. 遇到的问题及解决方案
(1) invalid key: log.file.rootpath
-
原因：配置文件缺少或拼写错误
log.file.rootPath -
解决：必须写
rootPath，且区分大小写
(2) invalid key: milvus.port 或 milvus.address
-
原因：配置字段不能写成
host:port，必须拆分为address和port两个字段 -
解决：按官方示例写
address: 10.233.48.134和port: 19530
(3) 备份只有 meta 文件
-
检查
utility.list_collections()和Collection.num_entities，发现数据量只有 0 或 1 -
原因：Milvus 备份实际数据段（segment），数据过少时只备份 meta
-
解决：确认数据写入流程，或手动调用
flush()生成 segment 后再备份
(4) gcPause.address 配置错误
-
需要指向暴露 9091 的 Milvus 服务
-
在集群内使用
ClusterIP:9091，外部使用port-forward 127.0.0.1:9091
6. 数据验证
在 Python 中使用 pymilvus 检查数据：
from pymilvus import connections, utility, Collection
connections.connect("default", host="10.233.48.134", port="19530")
# 列出所有集合
collections = utility.list_collections()
for name in collections:
c = Collection(name)
print(f"{name}: {c.num_entities} entities")
总结
这次备份过程踩过的坑主要集中在：
-
配置文件格式变化（v0.5.x 必须用 address/port 分离格式）
-
日志配置必须显式声明
-
对象存储参数必须与 Milvus 配置一致
-
数据未 flush 只备份 meta
掌握了这些要点后，可以顺利完成 Milvus 集群的数据备份与恢复，并支持跨环境迁移。