1.目的

• 通过国内华为云开源镜像站快速下载 Helm 二进制包

• 将 Helm 安装至系统可执行目录，使其可在任意路径下运行

• 确保安装后能够正常与 Kubernetes 集群交互

2.前置条件

操作系统为 Ubuntu 24.04

• 条件说明：本文档的所有操作步骤均以 Ubuntu 24.04 为基础编写，使用其他版本可能存在兼容性差异，建议尽量采用该版本。

• 检查方法：执行 lsb_release -a

• 满足方式：若版本不符，可考虑升级系统至 24.04，或自行验证当前版本中各项依赖的兼容性。

当前用户拥有 sudo 权限

• 条件说明：后续安装软件、修改系统配置等操作均需要管理员权限，因此执行脚本的用户必须具备 sudo 权限。

• 检查方法：运行 sudo -v，若无需输入密码或验证通过即可，若提示“not in sudoers”则说明无权限。

• 满足方式：联系系统管理员，将当前用户添加至 sudo 或 wheel 组，并配置相应的权限。

网络可正常访问华为镜像站

• 条件说明：安装包和依赖将通过华为镜像站 https://mirrors.huaweicloud.com 获取，要求宿主机能够与该地址正常建立连接。

• 检查方法：执行 curl -I https://mirrors.huaweicloud.com，若返回 HTTP 响应头且状态码正常，表示可访问；若长时间无响应或连接失败，则说明存在网络问题。

• 满足方式：排查网络配置、DNS 解析或防火墙策略，确保出站流量不被拦截，必要时可更换为其他可访问的镜像源。

wget 或 curl 已安装

• 条件说明：部分下载或验证步骤依赖 wget 或 curl 工具，必须至少安装其中一个。

• 检查方法：使用 which wget 或 which curl 检查命令是否存在，若输出路径则表示已安装；若无任何输出则未安装。

• 满足方式：若均未安装，可运行 sudo apt update && sudo apt install wget -y（或 curl）进行安装。

kubectl 已配置并能访问集群

• 条件说明：如需使用 Helm 管理 Kubernetes 集群，则必须提前配置好 kubectl 及对应的 kubeconfig 文件，确保能与目标集群正常通信。此项为可选推荐项，不涉及 Helm 操作时可忽略。

• 检查方法：执行 kubectl cluster-info，若成功返回集群信息则说明已就绪；若提示连接错误或无法找到资源，则需要进一步配置。

• 满足方式：安装 kubectl，并从集群管理员处获取合法的 kubeconfig 文件，放置于 ~/.kube/config 或通过 KUBECONFIG 环境变量指定路径。

2.版本查询

在华为云镜像站查询Helm版本 

以版本v4.1.1为例

https://mirrors.huaweicloud.com/helm/v4.1.1

里面包含 helm-v4.1.1-linux-amd64.tar.gz 等文件。

3.操作步骤

3.1 下载 Helm 二进制发布包

wget https://mirrors.huaweicloud.com/helm/v4.1.4/helm-v4.1.4-linux-amd64.tar.gz

若服务器未安装 wget，可改为 curl：

curl -LO https://mirrors.huaweicloud.com/helm/v4.1.4/helm-v4.1.4-linux-amd64.tar.gz

3.2 解压下载的压缩包

tar -zxvf helm-v4.1.4-linux-amd64.tar.gz

参数说明：

• -z：通过 gzip 解压 .gz 文件

• -x：从归档中提取文件（extract）

• -v：显示处理过程（verbose）

• -f：指定要操作的文件（file）

解压后会生成 linux-amd64/ 目录，其中包含可执行文件 helm，以及 LICENSE、README.md 等辅助文件。

3.3 安装 Helm 到系统路径

sudo mv linux-amd64/helm /usr/local/bin/helm

说明：

• sudo：以 root 权限执行，因为 /usr/local/bin 仅 root 可写

• /usr/local/bin 是标准系统级本地软件目录，默认包含在 PATH 中，安装后终端可直接识别 helm 命令

3.4 验证安装

helm version

version.BuildInfo{Version:"v3.16.4", GitCommit:"...", GitTreeState:"clean", GoVersion:"go1.22.5"}

3.5 清理下载文件

rm helm-v4.1.4-linux-amd64.tar.gz
rm -rf linux-amd64/

4.确保 Helm 可使用

4.1 添加 Bitnami 仓库

# 添加 Bitnami 官方仓库（活跃且维护良好）
helm repo add bitnami https://charts.bitnami.com/bitnami

# 更新仓库索引
helm repo update

如果网络不通或 URL 错误，会返回 Error: no repositories found 或 Failed to fetch，请检查镜像可达性和 URL 拼写。

4.2 搜索仓库中的 Chart

验证仓库可用

helm search repo bitnami/nginx

预期输出为表格形式，列出所有匹配的 Chart 版本，类似：

NAME                                    CHART VERSION   APP VERSION     DESCRIPTION                                       
bitnami/nginx                           24.0.1          1.31.0          NGINX Open Source is a web server that can be a...
bitnami/nginx-ingress-controller        12.0.7          1.13.1          NGINX Ingress Controller is an Ingress controll...
bitnami/nginx-intel                     2.1.15          0.4.9           DEPRECATED NGINX Open Source for Intel is a lig...

如果能看到上述表格，说明仓库添加和索引更新完全正常，Helm 已具备从仓库拉取 Chart 的能力。

5.验证 Helm 与 Kubernetes 集群交互

Helm 最终需要与目标 Kubernetes 集群通信，必须通过实际模拟安装来确认全链路可用。

5.1 确认 kubectl 配置正确

kubectl get nodes

• 第一行应显示集群 API 地址

• 第二行应列出节点列表且状态均为 Ready

5.2 执行模拟部署

使用 --dry-run=client 标志可让 Helm 仅生成最终要提交的资源清单，而不会在集群中真正创建对象：

helm install test-nginx bitnami/nginx --dry-run=client

成功标志：

• 大量 YAML 输出，包含 Deployment、Service 等 Kubernetes 资源定义

• 没有任何 Error: Kubernetes cluster unreachable 或权限拒绝信息

出现以上输出，即证明 Helm 可以正确读取 kubeconfig、与 API Server 通信、渲染模板，完全具备部署能力。

5.3 真实部署并回收

进行真实的部署和卸载：

helm install hello bitnami/nginx --wait --timeout 60s

--wait 会让 Helm 等待 Pod 就绪，若超过 60 秒可能因镜像拉取慢或其他问题导致超时，生产环境验证通常用 --dry-run 即足够。

成功标志：

NAME: hello
LAST DEPLOYED: Thu March 21 20:00:28 2026
NAMESPACE: default
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None
NOTES:
CHART NAME: nginx
CHART VERSION: 24.0.1
APP VERSION: 1.31.0

确认成功安装后，可卸载：

helm uninstall hello

6.总结清单

客户端安装验证

• 命令：helm version

• 通过标准：终端正常显示 Helm 的客户端版本信息（含版本号、Git 提交等），无 command not found 错误。这表明 Helm 已正确安装并在 PATH 路径中可用。

仓库管理验证

• 命令：helm repo list 及 helm search repo bitnami/nginx

• 通过标准：helm repo list 能列出已添加的仓库，其中包含 bitnami 仓库；helm search repo bitnami/nginx 能返回该 Chart 的搜索结果列表，而非报错。这说明仓库已正确添加并可正常检索应用。

集群交互验证

• 命令：先执行 kubectl cluster-info，确认集群连通性，然后执行 helm install <release-name> bitnami/nginx --dry-run

• 通过标准：kubectl cluster-info 无连接错误；helm install --dry-run 能输出正确的 Kubernetes 资源 YAML 清单，不出现权限或连接异常。这验证了 Helm 具备与集群正常交互并将模板渲染为实际资源定义的能力。

三层全部通过，说明 Helm 已完整部署且可用。

7.常见问题排错

wget 报 404 Not Found

• 现象：使用 wget 下载文件时返回 404 错误。

• 可能原因：URL 中指定的版本号不正确或已过期。

• 解决办法：参考 2 节的方法重新获取当前最新版本号，替换下载链接中的版本部分。

tar: command not found

• 现象：执行 tar 命令解压时提示命令不存在。

• 可能原因：系统缺少 tar 解压工具。

• 解决办法：运行 sudo apt install tar -y 进行安装。

helm: command not found

• 现象：终端执行 helm 命令时提示未找到。

• 可能原因：二进制文件未移入 PATH 目录，或命令缓存未更新。

• 解决办法：执行 hash -r 刷新命令缓存，或重新登录终端；确认已将 helm 放置到 /usr/local/bin，且该路径在 PATH 变量中。

helm version 正常，但 dry-run 报连接错误

• 现象：Helm 本地版本显示正常，但执行 helm install --dry-run 时提示无法连接集群。

• 可能原因：kubeconfig 文件不存在或配置错误。

• 解决办法：检查 ~/.kube/config 是否存在且内容有效，执行 kubectl cluster-info 查看具体错误信息，确保 kubectl 能够正常访问集群。

仓库更新失败（Failed to fetch）

• 现象：helm repo update 时报 Failed to fetch 错误。

• 可能原因：DNS 解析问题或防火墙拦截了仓库地址。

• 解决办法：测试网络连通性：ping mirrors.huaweicloud.com 以及 curl https://charts.bitnami.com/bitnami/index.yaml，根据结果排查 DNS 设置、代理配置或防火墙规则。

helm search repo 无结果

• 现象：执行 helm search repo 查询不到预期 Chart。

• 可能原因：未执行 helm repo update 更新索引，或本地仓库缓存损坏。

• 解决办法：先执行 helm repo update 更新索引；若仍无效，移除并重新添加仓库（helm repo remove 后再 helm repo add）。