博客
总是深夜报错？这份Helm版Milvus分布式集群离线部署教程请收好

总是深夜报错？这份Helm版Milvus分布式集群离线部署教程请收好

2025-03-18

By 尹珉

"又是一个通宵,就为了部署离线Milvus集群，结果

ImagePullBackOff又报错了，

镜像拉不下来，

证书过期了，

存储类找不到，

etcd集群起不来……

相信这是不少开发者在离线环境部署Milvus时，都遇到过的痛苦经历。

平心而论，Kubernetes固然强大,但陡峭的学习曲线和繁琐的配置让人望而生畏。尤其是对于Milvus这样的分布式向量数据库,涉及etcd、MinIO等多个组件的协同部署，层出不穷的错误信息几乎让每个尝试离线部署的开发者都抓狂过。

但现在，这些都将成为过去式！

借助Helm工具（ Kubernetes 的包管理工具，通过预定义的模板封装 Kubernetes 资源，使得用户可以轻松地安装、升级、回滚和管理复杂的应用程序），我们可以将过去复杂的离线部署工作简化到极致，只需几分钟，就能在内网环境搭建一个生产级的Milvus集群。

2.11-1.png

02 前置条件

2.1 知识储备

了解Kubernetes基础概念(Pod、Service、PVC等)
掌握kubectl基本命令操作
会使用helm部署应用
镜像仓库harbor：（https://goharbor.io/）
对Milvus有基本认知即可（参考：https://milvus.io/docs/architecture_overview.md）

2.2 环境检查清单

Kubernetes集群版本 1.28.8（https://kubernetes.io/docs/home/）
自行准备StorageClass
Helm版本 ≥ 3.15（https://helm.sh/docs/）
确保集群节点间网络互通
Milvus版本 2.5.3

2.3 资源预估


主机名	CPU	内存	系统盘	数据盘	用途
k8s-control-1	4	8	40	100	k8s-control-plane
k8s-control-2	4	8	40	100	k8s-control-plane
k8s-control-3	4	8	40	100	k8s-control-plane
k8s-registry	4	8	40	100	Harbor私有镜像仓库
k8s-artifact	2	4	40	100	联网主机用于下载和准备离线包
合计	20	40	200	500

03 离线部署

让我们开始动手实践吧！首先,我们需要一台能访问外网的服务器作为"资源中转站",它将帮助我们打包所有离线部署所需的"弹药"。

在具有公网访问权限的服务器上准备离线部署所需的资源包:

3.1 安装 Helm

Helm就像是Kubernetes的包管理器,它能让复杂的应用部署变得像安装手机APP一样简单，本文采用比较灵活的二进制版本安装。

下载二进制版本 Helm

wget https://get.helm.sh/helm-v3.15.4-linux-amd64.tar.gz

解压

tar -zxvf helm-v3.15.4-linux-amd64.tar.gz

移动二进制文件到 /usr/local/bin 目录

mv linux-amd64/helm /usr/local/bin/清理残留rm -rf linux-amd64/

验证 Helm 可用性

$ helm versionversion.BuildInfo{Version:"v3.15.4", GitCommit:"fa9efb07d9d8debbb4306d72af76a383895aa8c4", GitTreeState:"clean", GoVersion:"go1.22.6"}

3.2 制作 Milvus 离线部署资源清单（manifest）

添加Milvus官方Helm Repo

helm repo add milvus https://zilliztech.github.io/milvus-helm/helm repo update

编辑自定义 value 文件，实现如下功能

1）默认配置部署的 Milvus，没有启用安全认证，任何人都可以随意读写。这不符合生产环境要求，因此，需要增加认证配置。

2）启用 Attu 图形化管理工具

手动创建自定义配置文件 values.yaml （文件名可自定义），写入以下内容:

vi values.yaml
extraConfigFiles:  user.yaml: |+    common:      security:        authorizationEnabled: trueattu:  enabled: true

生成部署资源清单文件

 helm template -f values.yaml demo-release milvus/milvus > milvus_manifest.yaml

说明：demo-release 是项目名称，可自定义。

3.3 拉取和保存镜像

运行以下命令拉取并保存离线部署 Milvus 所需的容器镜像。

下载离线镜像拉取脚本

wget https://raw.githubusercontent.com/milvus-io/milvus/master/deployments/offline/requirements.txtwget https://raw.githubusercontent.com/milvus-io/milvus/master/deployments/offline/save_image.py

安装 python 依赖包

默认命令pip3 install -r requirements.txt国内网络受，请使用下面的命令加速下载pip3 install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

下载离线镜像

python3 save_image.py --manifest milvus_manifest.yaml

2.11-2.png

下载的镜像，以每个镜像一个压缩文件的形式，保存在save_image.py脚本所在目录的 images 子目录中。

查看生成的离线镜像文件$ ls -lh images/total 1.6G-rw-r--r-- 1 root root 755M Jan 16 02:14 apachepulsar-pulsar.tar.gz-rw-r--r-- 1 root root  70M Jan 16 02:15 docker.io-milvusdb-etcd.tar.gz-rw-r--r-- 1 root root 553M Jan 16 02:21 milvusdb-milvus.tar.gz-rw-r--r-- 1 root root  93M Jan 16 02:22 minio-minio.tar.gz-rw-r--r-- 1 root root  95M Jan 16 02:24 zilliz-attu.tar.gz

打包离线部署镜像资源

tar zcvf milvus-2.5-images.tar.gz images

3.4在离线环境准备镜像仓库

本文假设已经存在离线镜像仓库，Harbor 或是 Registry 都可。

说明：若没有离线镜像仓库，推荐使用Harbor自行安装（https://github.com/goharbor/harbor）

3.5上传离线镜像到镜像仓库服务器

本文约定的存储目录为/srv。

3.6导入 Image

tar xvf milvus-2.5-images.tar.gz
cd images
for image in $(find . -type f -name "*.tar.gz") ; do gunzip -c $image | docker load; done

3.7重新标记镜像Tag并推送到私有仓库

假设内网镜像仓库地址为 harbor.milvus.local，请用实际值替换。

#标记 tagdocker tag docker.io/milvusdb/etcd:3.5.16-r1 harbor.milvus.local/docker.io/milvusdb/etcd:3.5.16-r1docker tag milvusdb/milvus:v2.5.3 harbor.milvus.local/milvusdb/milvus:v2.5.3docker tag minio/minio:RELEASE.2023-03-20T20-16-18Z harbor.milvus.local/minio/minio:RELEASE.2023-03-20T20-16-18Zdocker tag apachepulsar/pulsar:3.0.7 harbor.milvus.local/apachepulsar/pulsar:3.0.7docket tag zilliz/attu:v2.4.12 harbor.milvus.local/zilliz/attu:v2.4.12#推送docker push harbor.milvus.local/docker.io/milvusdb/etcd:3.5.16-r1docker push harbor.milvus.local/milvusdb/milvus:v2.5.3docker push harbor.milvus.local/minio/minio:RELEASE.2023-03-20T20-16-18Zdocker push harbor.milvus.local/apachepulsar/pulsar:3.0.7docket push harbor.milvus.local/zilliz/attu:v2.4.12

经过前面的准备工作,我们已经有了:

✓ 完整的部署配方(manifest)

✓ 所有必需的镜像

✓ 配置好的私有镜像仓库

现在,让我们一步步把Milvus分布式的服务搭建起来吧

3.8部署 Milvus集群

上传离线部署资源文件milvus_manifest.yaml到 k8s 集群任一控制节点的/srv/milvus 目录。
修改资源清单中的镜像地址为私有镜像仓库地址

sed -i 's#apachepulsar/pulsar:3.0.7#harbor.milvus.local/apachepulsar/pulsar:3.0.7#g' milvus_manifest.yamlsed -i 's#milvusdb/milvus:v2.5.3#harbor.milvus.local/milvusdb/milvus:v2.5.3#g' milvus_manifest.yamlsed -i 's#docker.io/milvusdb/etcd:3.5.16-r1#harbor.milvus.local/docker.io/milvusdb/etcd:3.5.16-r1#g' milvus_manifest.yamlsed -i 's#minio/minio:RELEASE.2023-03-20T20-16-18Z#harbor.milvus.local/minio/minio:RELEASE.2023-03-20T20-16-18Z#g' milvus_manifest.yamlsed -i 's#zilliz/attu:v2.4.12#harbor.milvus.local/zilliz/attu:v2.4.12#g' milvus_manifest.yaml

执行下面的命令部署 Milvus

kubectl apply -f milvus_manifest.yaml

3.9 查看部署结果

安装命令成功执行后，观察 Pod 运行状态。

kubectl get pods

安装成功后，输出结果如下 :

说明：确保所有Pod状态Running即可，除一次性任务状态Completed

2.11-3.png

注意：Milvus 2.5.3 默认使用了 Mix 模式的 coord 组件，所以只有一个 milvus-mixcoord 命名的 Pod。

3.10 配置 Milvus 和 Attu 的外部访问

为了让集群外部的应用和用户也能访问 Milvus 和 Attu 服务,我们需要为它们配置外部访问入口。考虑到简单易用,本文采用 Kubernetes 的 NodePort 方式来暴露服务。

创建并编辑外部访问 Milvus 服务的 svc 资源清单

vi demo-release-milvus-external-svc.yaml
kind: ServiceapiVersion: v1metadata:  name: demo-release-milvus-external-svc  namespace: default  labels:    app: demo-release-milvus-external-svcspec:  ports:    - name: milvus      protocol: TCP      port: 19530      targetPort: 19530      nodePort: 31800  selector:    app.kubernetes.io/instance: demo-release    app.kubernetes.io/name: milvus    component: proxy  clusterIP:  type: NodePort

创建并编辑外部访问 Attu 服务的 svc 资源清单

vi demo-release-milvus-attu-external-svc.yamlkind: ServiceapiVersion: v1metadata:  name: demo-release-milvus-attu-external-svc  namespace: default  labels:    app: demo-release-milvus-attu-external-svcspec:  ports:    - name: attu      protocol: TCP      port: 3000      targetPort: 3000      nodePort: 31801  selector:    app.kubernetes.io/instance: demo-release    app.kubernetes.io/name: milvus    component: attu  clusterIP:  type: NodePort

创建服务资源

kubectl apply -f demo-release-milvus-external-svc.yamlkubectl apply -f demo-release-milvus-attu-external-svc.yaml

查看资源创建结果

kubectl get deploy

2.11-4.png

kubectl get sts

2.11-5.png

接下来,我们将使用 Milvus 官方推荐的可视化管理工具 Attu 来验证集群是否部署成功。Attu 提供了友好的 Web 界面,可以帮助我们直观地查看和管理 Milvus 集群。

3.11登录 Attu 管理控制台

打开浏览器，访问 k8s 集群任意节点 IP 的 31801 端口，例如 http://192.168.9.91:31801，勾选「认证」按钮，输入默认用户名密码 root/Milvus，点击「连接」。

说明：这里使用了http://demo-release-milvus去访问的原因是使用了k8s集群的内部地址

2.11-6.png

登录首页

2.11-7.png

用户界面（请立即修改默认用户密码）

2.11-8.png

系统视图

2.11-9.png

04 写在最后

完成了这次离线部署,相信你已经体会到:Milvus集群部署其实并不可怕,关键是要做好充分的准备工作。对于想要在生产环境快速部署Milvus的用户来说，这套方案提供了一个可落地的实践范本。不过这套方案并非万能，在分布式向量数据库的部署方案上，我们通常需要在多个维度之间找到平衡点，以下是一些关于分布式部署的心得总结：

（1）如何做可用性与复杂度的平衡：

当你的团队已经有了一定的K8s使用经验，比如已经在跑其他微服务了，那用K8s部署Milvus就很合适。虽然前期配置确实有点麻烦，但后期运维会轻松很多。

如果你经常要在开发、测试、生产环境之间切换部署，用Helm就很方便了。改个配置文件就能搞定，不用每次都重新写一堆yaml。

考虑到很多企业内网环境复杂，用NodePort暴露服务最省事。特殊情况下想要更细致的访问控制，再改用Ingress也来得及。

（2）如何做性能与成本的权衡：

如果你的向量数据已经达到上千万了，用分布式部署是最佳选择，查询速度会快很多，用户体验也会好很多。

存储这块的选择一定要上SSD，如果是机械硬盘查询会出现卡顿现象。

整体资源规划建议CPU和内存尽量预留整体资源的三成冗余来应对突发流量暴增的场景。

（3）如何做维护性与稳定性的取舍：

像银行、医院这些对网络环境、硬件要求比较高的单位，提前把镜像和依赖准备好，避免在离线环境部署时出现缺少依赖、安装失败的情况。

如果集群规模比较大，建议企业内部自建一个镜像仓库用于分发不同节点，满足各个节点同时拉取镜像的需求。

这些选择背后，体现的是一种务实的架构思维 - 在保证系统可靠性的同时，尽可能降低维护成本。