2. Helm 环境搭建：安装 Helm 客户端、配置 Helm 仓库、Helm 命令基础

在将 Helm 集成到 CI/CD 流水线之前，必须完成本地或构建环境中的 Helm 基础环境搭建。本章将指导你完成 Helm 客户端的安装、官方与第三方仓库的配置，以及最常用的三个核心命令：helm repo、helm search 和 helm install。

2.1 安装 Helm 客户端

Helm 采用客户端-服务端架构（v3 版本已移除 Tiller 服务端，仅保留客户端）。安装方式支持包管理器、二进制脚本和手动下载。推荐使用官方脚本或包管理器，确保版本与 Kubernetes 集群兼容。

安装方式	适用平台	命令/步骤
官方脚本（推荐）	Linux / macOS	curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
Homebrew	macOS	brew install helm
Chocolatey	Windows	choco install kubernetes-helm
二进制手动安装	所有平台	从 GitHub Releases 下载 tar.gz，解压后放入 /usr/local/bin

2.2 配置 Helm 仓库

Helm 仓库（Repository）是存储 Chart 包的 HTTP 服务器。配置仓库后，可以通过 helm repo 命令进行增删查改。以下为常用仓库配置清单：

仓库名称	URL	用途
Bitnami	https://charts.bitnami.com/bitnami	官方维护的常用应用 Chart（nginx、redis、postgresql 等）
Stable（已归档）	https://charts.helm.sh/stable	旧版官方仓库，部分 Chart 已迁移至 Bitnami
Prometheus Community	https://prometheus-community.github.io/helm-charts	监控与告警相关 Chart
Jetstack（cert-manager）	https://charts.jetstack.io	证书管理 Chart

配置步骤：

1. 添加仓库：helm repo add bitnami https://charts.bitnami.com/bitnami
2. 更新仓库索引：helm repo update
3. 查看已配置仓库：helm repo list
4. 删除仓库：helm repo remove bitnami

2.3 Helm 命令基础：repo、search、install

以下三个命令是 Helm 日常操作的核心，也是 CI/CD 流水线中最常用的指令。掌握它们即可完成从查找 Chart 到部署应用的完整链路。

2.3.1 helm repo — 仓库管理

helm repo 是仓库操作的入口命令，子命令包括：

• helm repo add [name] [url] — 添加新仓库
• helm repo list — 列出所有已配置仓库
• helm repo update — 更新本地仓库索引缓存
• helm repo remove [name] — 移除指定仓库
• helm repo index [dir] — 基于本地目录生成仓库索引文件（用于自建仓库）

2.3.2 helm search — 搜索 Chart

支持两种搜索模式：

命令	说明	示例
helm search hub	搜索 Helm Hub（Artifact Hub）中的公共 Chart	helm search hub nginx
helm search repo	搜索已添加的本地仓库中的 Chart	helm search repo bitnami/nginx

2.3.3 helm install — 部署 Chart

基本语法：helm install [release-name] [chart] [flags]

常用参数：

• --namespace — 指定目标命名空间（默认 default）
• --create-namespace — 如果命名空间不存在则自动创建
• --values / -f — 指定自定义 values 文件
• --set — 直接设置键值对覆盖默认值
• --version — 指定 Chart 版本
• --wait — 等待所有 Pod 就绪后再返回
• --timeout — 设置等待超时时间（默认 5m）

完整示例：

# 添加并更新仓库
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# 搜索 nginx Chart
helm search repo bitnami/nginx --versions

# 使用自定义 values 文件部署 release
helm install my-nginx bitnami/nginx \
  --namespace production \
  --create-namespace \
  --values ./custom-values.yaml \
  --set replicaCount=3 \
  --version 18.0.0 \
  --wait \
  --timeout 10m

2.4 Helm 环境搭建与命令流程总览

下图展示了从零开始搭建 Helm 环境、配置仓库、搜索 Chart 到完成首次部署的完整流程：

2.5 常见问题与避坑指南

问题	原因	解决方案
helm repo update 超时	网络代理或仓库地址不可达	检查 HTTP_PROXY 环境变量；使用 helm repo add --insecure-skip-tls-verify 跳过证书验证（仅测试环境）
helm install 报错 already exists	Release 名称在命名空间中已存在	使用 helm list -n [namespace] 查看已有 release；改用 helm upgrade --install 实现幂等部署
Chart 版本找不到	本地索引未更新或仓库未添加	执行 helm repo update；确认仓库 URL 正确且 Chart 名称拼写无误
Pod 一直处于 Pending 状态	集群资源不足或 PVC 无法绑定	检查 kubectl describe pod；增加 --timeout 值或调整资源请求