Helm 3 最新完整教程（2026版）-平芜编程栈

基于 Helm v3.14+（Kubernetes 1.28~1.31 兼容），涵盖核心概念、工作负载模板、高级用法、CI/CD 集成与生产最佳实践。

1. Helm 简介与核心架构

Helm 是 Kubernetes 的包管理器，用于定义、安装、升级和管理 Kubernetes 应用。它通过Chart（图表）打包一组 Kubernetes 资源模板，通过Values实现环境差异化配置。

🔑 Helm v3 架构演进（对比 v2）

特性	Helm v2	Helm v3
服务端组件	Tiller（集群内运行，权限大）	无 Tiller，直接使用用户 RBAC 权限
Release 存储	ConfigMap	Secret（可配置为 ConfigMap）
依赖管理	`requirements.yaml`	`dependencies`内置于`Chart.yaml`
镜像仓库	HTTP Chart Museum / GitHub Pages	支持 OCI Registry（Docker Registry / Harbor / GHCR）
CRD 管理	自动安装/删除	仅创建，不删除（防误删数据）

2. 环境准备与安装

🐧 Linux / macOS

curlhttps://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3|bashhelm version

🪟 Windows (Scoop)

scoop install helm

✅ 验证与配置

# 添加官方仓库helm repoaddbitnami https://charts.bitnami.com/bitnami helm repo update# 搜索 Charthelm search repo nginx

3. Chart 目录结构与核心文件

helm create myapp tree myapp/

myapp/ ├── Chart.yaml # 元数据（名称、版本、依赖、API版本） ├── values.yaml # 默认配置值 ├── charts/ # 子 Chart（依赖） ├── templates/ # Kubernetes 资源模板 │ ├── deployment.yaml │ ├── service.yaml │ ├── ingress.yaml │ └── _helpers.tpl # 模板函数与命名规则 ├── crds/ # CRD 定义（仅安装，不卸载） └── tests/ # 测试用例

📄`Chart.yaml`示例

apiVersion:v2name:myappdescription:示例应用 Charttype:applicationversion:1.0.0# Chart 版本（语义化）appVersion:"2.5.0"# 应用镜像版本dependencies:-name:postgresqlversion:"12.5.0"repository:https://charts.bitnami.com/bitnamicondition:postgresql.enabled

4. Helm 基础操作

# 安装/升级（幂等）helminstallmy-release ./myapp--namespacedev --create-namespace helm upgrade my-release ./myapp-fvalues-prod.yaml--namespacedev# 回滚helm rollback my-release2--namespacedev# 查看状态helm status my-release-ndev helm list-A# 卸载helm uninstall my-release-ndev# 模板预览（不提交集群）helm template my-release ./myapp-fvalues.yaml

5. Kubernetes 三大工作负载详解与 Helm 实践

🟦 5.1 Deployment：无状态应用

特点：副本数灵活、支持滚动更新、Pod 无固定身份、适合快速扩缩容。

📦`templates/deployment.yaml`

apiVersion:apps/v1kind:Deploymentmetadata:name:{{include "myapp.fullname" .}}labels:{{-include "myapp.labels" .|nindent 4}}spec:replicas:{{.Values.replicaCount}}selector:matchLabels:{{-include "myapp.selectorLabels" .|nindent 6}}strategy:type:RollingUpdaterollingUpdate:maxSurge:1maxUnavailable:0template:metadata:labels:{{-include "myapp.selectorLabels" .|nindent 8}}spec:containers:-name:{{.Chart.Name}}image:"{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"imagePullPolicy:{{.Values.image.pullPolicy}}ports:-name:httpcontainerPort:80protocol:TCPresources:{{-toYaml .Values.resources|nindent 12}}

🎯 适用场景

Web 前端、REST API、微服务
需要快速水平扩展的应用
配置通过 ConfigMap/Secret 注入，无本地持久化状态

🟨 5.2 StatefulSet：有状态应用

特点：Pod 名称固定（<name>-<ordinal>）、有序部署/扩缩容、独立 PVC、Headless Service 提供稳定网络标识。

📦`templates/statefulset.yaml`

apiVersion:apps/v1kind:StatefulSetmetadata:name:{{include "myapp.fullname" .}}-dbspec:serviceName:{{include "myapp.fullname" .}}-headlessreplicas:{{.Values.db.replicaCount}}podManagementPolicy:OrderedReadyupdateStrategy:type:RollingUpdateselector:matchLabels:app.kubernetes.io/name:{{include "myapp.name" .}}-dbtemplate:metadata:labels:app.kubernetes.io/name:{{include "myapp.name" .}}-dbspec:containers:-name:dbimage:"{{ .Values.db.image.repository }}:{{ .Values.db.image.tag }}"ports:-containerPort:5432env:-name:POSTGRES_PASSWORDvalueFrom:secretKeyRef:name:{{include "myapp.fullname" .}}-db-secretkey:passwordvolumeClaimTemplates:-metadata:name:dataspec:accessModes:["ReadWriteOnce"]storageClassName:{{.Values.db.storageClass}}resources:requests:storage:{{.Values.db.storageSize}}

🌐 Headless Service（必须配合 StatefulSet）

apiVersion:v1kind:Servicemetadata:name:{{include "myapp.fullname" .}}-headlessspec:clusterIP:None# 关键：无 ClusterIPports:-port:5432targetPort:5432name:dbselector:app.kubernetes.io/name:{{include "myapp.name" .}}-db

🎯 适用场景

数据库（MySQL、PostgreSQL、MongoDB）
消息队列（Kafka、RabbitMQ）
分布式协调服务（ZooKeeper、etcd）
需要稳定 DNS 标识与独立存储的集群

🟥 5.3 DaemonSet：节点级守护进程

特点：每个 Node 运行一个 Pod、自动跟随节点增删、通常使用hostNetwork/hostPath或特权模式。

📦`templates/daemonset.yaml`

apiVersion:apps/v1kind:DaemonSetmetadata:name:{{include "myapp.fullname" .}}-agentlabels:{{-include "myapp.labels" .|nindent 4}}spec:selector:matchLabels:app.kubernetes.io/name:{{include "myapp.name" .}}-agenttemplate:metadata:labels:app.kubernetes.io/name:{{include "myapp.name" .}}-agentspec:tolerations:-operator:Exists# 容忍所有污点，包括控制面节点containers:-name:node-exporterimage:"{{ .Values.agent.image.repository }}:{{ .Values.agent.image.tag }}"args:---path.procfs=/host/proc---path.sysfs=/host/sysports:-containerPort:9100volumeMounts:-name:procmountPath:/host/procreadOnly:true-name:sysmountPath:/host/sysreadOnly:truevolumes:-name:prochostPath:path:/proc-name:syshostPath:path:/sys

🎯 适用场景

日志收集（Fluentd、Filebeat、Loki Promtail）
监控指标采集（Prometheus Node Exporter、Datadog Agent）
网络插件（Calico、Cilium、Flannel）
存储插件（Ceph CSI、Rook）

6. 工作负载对比与选型指南

维度	Deployment	StatefulSet	DaemonSet
Pod 身份	随机命名，可替换	固定序号（`pod-0`,`pod-1`）	与 Node 绑定，通常唯一
扩缩容	随机调度，并行	严格按序号创建/删除	自动跟随节点数量
网络标识	通过 Service 负载均衡	Headless Service + 稳定 DNS	通常直接访问 Pod IP 或 hostPort
存储模型	共享 PVC 或无状态	独立 PVC（`volumeClaimTemplates`）	通常`hostPath`或本地存储
更新策略	RollingUpdate / Recreate	RollingUpdate（有序）	OnDelete / RollingUpdate
典型场景	Web/API/微服务	DB/缓存/消息队列	监控/日志/CNI/CSI
Helm 注意事项	最常用，模板简单	需配 Headless Service，注意`storageClass`兼容性	注意`tolerations`、节点亲和性、权限升级

💡选型口诀：
无状态跑 Deployment，有状态上 StatefulSet，管节点用 DaemonSet。

7. 高级特性与最佳实践

🔹 7.1 依赖管理与子 Chart

helm dependency update ./myapp helm dependency build ./myapp

在templates/中覆盖子 Chart 值：

# values.yamlpostgresql:enabled:trueauth:postgresPassword:"supersecret"primary:persistence:size:10Gi

🔹 7.2 Helm Hooks（生命周期钩子）

apiVersion:batch/v1kind:Jobmetadata:name:"{{include "myapp.fullname" .}}-db-init"annotations:"helm.sh/hook":post-install,post-upgrade"helm.sh/hook-weight":"5""helm.sh/hook-delete-policy":hook-succeededspec:template:spec:containers:-name:initimage:"{{ .Values.db.image.repository }}:{{ .Values.db.image.tag }}"command:["sh","-c","psql -c 'CREATE DATABASE app;'"]restartPolicy:Never

🔹 7.3 OCI 仓库支持（Helm v3.8+）

# 登录helm registry login ghcr.io-uUSER-pTOKEN# 推送helm package ./myapp--version1.2.0 helm push myapp-1.2.0.tgz oci://ghcr.io/myorg/charts# 安装helminstallmyapp oci://ghcr.io/myorg/charts/myapp--version1.2.0

🔹 7.4 生产最佳实践

值结构分层：按环境拆分values-dev.yaml、values-staging.yaml、values-prod.yaml
避免硬编码：使用{{ .Values }}+ 默认值，敏感信息走 Secret/外部密钥管理
Chart 版本控制：遵循 SemVer，appVersion与镜像版本对齐

Lint 与测试：

helm lint ./myapp helm unittest ./myapp# 需安装 plugin

CRD 安全：CRD 只增不删，升级前手动评估兼容性
资源限额：始终定义resources.requests/limits，配合 VPA/HPA

8. CI/CD 与 GitOps 集成

🛠 GitHub Actions 示例

name:Helm CIon:[push,pull_request]jobs:test:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-uses:azure/setup-helm@v3-run:helm lint ./myapp-run:helm template ./myapp-f values-test.yaml|kubeval--strict

🌐 GitOps（ArgoCD / Flux）

ArgoCD：原生支持 Helm，自动同步helm install/upgrade状态
Flux：使用HelmReleaseCRD 声明式管理

apiVersion:helm.toolkit.fluxcd.io/v2beta2kind:HelmReleasemetadata:name:myappnamespace:prodspec:interval:5mchart:spec:chart:./myappsourceRef:kind:GitRepositoryname:my-repovalues:replicaCount:3image:tag:"2.5.0"

🔍 变更预览插件

helm plugininstallhttps://github.com/databus23/helm-diff helmdiffupgrade my-release ./myapp-fvalues-prod.yaml

9. 常见坑与排错指南

现象	原因	解决
`release "xxx" has no deployed releases`	首次安装失败但未清理	`helm uninstall xxx`或`helm install --atomic`
`failed to create resource: ... already exists`	手动创建了同名资源	删除冲突资源或使用`--replace`
StatefulSet Pod 卡在`Pending`	PVC 无法绑定 / StorageClass 不存在	检查`storageClassName`与 Provisioner 状态
Helm 升级后旧 Pod 未删除	标签选择器变更	使用`kubectl rollout restart`或调整`selector`
Hook 执行阻塞升级	Hook 未设置`hook-delete-policy`或超时	添加`"helm.sh/hook-delete-policy": hook-succeeded`
OCI 拉取 401	未登录或 Token 过期	`helm registry login`重新认证

🐛 调试命令速查

helm template ./myapp--debug>rendered.yaml helm get manifest my-release-ndev helmhistorymy-release-ndev kubectl describe pod<pod-name>-ndev

📎 附录：Helm 常用命令速查表

命令	说明
`helm create <name>`	创建新 Chart
`helm install <release> <chart>`	安装 Release
`helm upgrade <release> <chart>`	升级 Release
`helm rollback <release> [revision]`	回滚到指定版本
`helm uninstall <release>`	删除 Release（不删 CRD/PVC）
`helm list [-A]`	列出已安装 Release
`helm repo add/update/search`	仓库管理
`helm dependency update/build`	拉取/构建依赖
`helm lint`	语法与规范检查
`helm template`	本地渲染模板
`helm package`	打包为`.tgz`
`helm push`	推送至 OCI 仓库

📚 延伸阅读

官方文档：https://helm.sh/docs/
Chart 最佳实践：https://helm.sh/docs/chart_best_practices/
Kubernetes 工作负载官方指南：https://kubernetes.io/docs/concepts/workloads/
Helm 插件生态：https://artifacthub.io/packages/search?kind=plugin

💡学习建议：从helm create开始，逐步替换deployment.yaml→statefulset.yaml→daemonset.yaml，配合helm template --debug观察渲染结果，最后接入 CI/CD 实现自动化。

1. Helm 简介与核心架构

🔑 Helm v3 架构演进（对比 v2）

2. 环境准备与安装

🐧 Linux / macOS

🪟 Windows (Scoop)

✅ 验证与配置

3. Chart 目录结构与核心文件

📄Chart.yaml示例

4. Helm 基础操作

5. Kubernetes 三大工作负载详解与 Helm 实践

🟦 5.1 Deployment：无状态应用

📦templates/deployment.yaml

🎯 适用场景

🟨 5.2 StatefulSet：有状态应用

📦templates/statefulset.yaml

🌐 Headless Service（必须配合 StatefulSet）

🎯 适用场景

🟥 5.3 DaemonSet：节点级守护进程

📦templates/daemonset.yaml

🎯 适用场景

6. 工作负载对比与选型指南

7. 高级特性与最佳实践

🔹 7.1 依赖管理与子 Chart

🔹 7.2 Helm Hooks（生命周期钩子）

🔹 7.3 OCI 仓库支持（Helm v3.8+）

🔹 7.4 生产最佳实践

8. CI/CD 与 GitOps 集成

🛠 GitHub Actions 示例

🌐 GitOps（ArgoCD / Flux）

🔍 变更预览插件

9. 常见坑与排错指南

🐛 调试命令速查

📎 附录：Helm 常用命令速查表

📚 延伸阅读

2026年国内酒吧管理系统有哪些？15款软件功能与适用场景

工业级字符识别实战：C#结合YOLO+Tesseract实现药品批号与电子元件丝印精准校验

如何用开源工具打破音乐平台格式壁垒：解锁加密音乐的完整解决方案

Windows 11任务栏歌词终极解决方案：Taskbar-Lyrics完整指南

OpenProject开发环境一站式编织指南：打造你的项目管理交响乐团

Micro-C与HiChIP助力揭示RB通过调控黏连蛋白重塑染色质结构的全新非经典抑癌机制

📄`Chart.yaml`示例

📦`templates/deployment.yaml`

📦`templates/statefulset.yaml`

📦`templates/daemonset.yaml`