使用 Helm 管理 Kubernetes 应用时，Chart（Helm 的软件包）的 API 版本差异、以及 Chart 存储库的交互规则，是理解 Helm 工作机制的核心。本文用通俗的语言拆解两个关键知识点：Helm Chart v1/v2 新旧 API 版本的核心差异，以及 Chart 存储库 API 的全部关键规则，帮你吃透这些“底层干货”。

一、先搞懂：Helm Chart 新旧 API 版本（v1 vs v2）

Chart 的 API 版本由 Chart.yaml 里的 apiVersion 字段指定，核心分 v1（旧版）和 v2（新版），两者适配不同 Helm 版本，功能差异显著。

1.1 核心定位：谁用哪个版本？

• API v1：Helm 2 的“原生版本”，兼容 Helm 2 和 Helm 3，但不支持 Helm 3 新特性（如库 Chart），适合需要兼容旧环境的场景；
• API v2：Helm 3 推出的默认版本，仅兼容 Helm 3+，支持库 Chart、内置依赖配置等新功能，是新开发 Chart 的首选。

1.2 v1 和 v2 的核心差异（通俗版）

不用死记复杂表格，记住这几个关键区别就够了：

对比维度	API v1（旧版）	API v2（新版）
依赖配置文件	单独写在 requirements.yaml	内嵌到 Chart.yaml 的 dependencies 字段
依赖锁定文件	生成 requirements.lock	生成 Chart.lock
库 Chart 支持	不支持（仅应用 Chart）	支持（通过 type: library 定义）
实用新增字段	仅 tillerVersion（Helm2 专用）、engine	新增 type（Chart 类型）、kubeVersion（指定兼容 K8s 版本）
适配场景	兼容 Helm2 旧环境	全新开发、使用 Helm3 新特性

举个实际例子：如果想让 Chart 仅兼容 K8s 1.24~1.29，只有 v2 能通过 kubeVersion: ">=1.24.0 <1.30.0" 实现；如果想做一个可复用的模板库 Chart（比如通用日志配置），也只有 v2 支持。

1.3 从 v1 迁移到 v2 的简单步骤

若要把旧的 v1 Chart 升级到 v2，按这 5 步走即可：

1. 修改 Chart.yaml 的 apiVersion 为 v2；
2. 添加 type: application（应用 Chart）或 type: library（库 Chart）；
3. 将 requirements.yaml 里的依赖项，复制到 Chart.yaml 的 dependencies 字段下；
4. 删除原有的 requirements.yaml 和 requirements.lock；
5. 执行 helm dependency update，自动生成新的 Chart.lock。

二、再吃透：Helm Chart 存储库 API

Helm 能从远程下载 Chart，靠的是“Chart 存储库 API”——这套规则极其轻量，核心仅一个必需文件（index.yaml），搭配可选的安装包（.tgz）和签名文件（.prov）即可运行。

2.1 核心概述：存储库 API 到底是啥？

简单说，Chart 存储库就是一个能通过 HTTP 访问的“静态文件服务器”（比如 GitHub Pages、Nginx、S3），无需复杂后端，只需满足 3 个核心规则：

• 必需提供 GET /index.yaml 接口（如存储库地址是 https://xxx.com/charts，则 https://xxx.com/charts/index.yaml 必须能访问且返回 200）；
• 可选提供 .tgz（Chart 安装包）、.prov（签名校验文件）；
• 所有文件遵循固定的命名和访问规则。

2.2 index.yaml：存储库的“商品目录”

index.yaml 是存储库的核心，相当于“商品清单”，记录所有可用 Chart 的版本、下载地址、校验和等信息。

（1）核心格式（简化版）

apiVersion: v1  # 固定值，不可修改
entries:  # 所有 Chart 的清单
  superapp:  # Chart 名称
    - name: superapp
      version: 0.1.0  # 遵循语义化版本（如 1.2.3）
      digest: "sha256:abc123..."  # .tgz 包的 SHA-256 校验和（防篡改）
      urls:  # 下载地址，支持相对/绝对路径
        - "superapp-0.1.0.tgz"
generated: "2024-07-01T11:00:00Z"  # 清单生成时间（RFC 3339 格式）

（2）Helm 何时更新/使用这份清单？

• 主动下载最新清单：执行 helm repo add（添加仓库）、helm repo update（更新仓库）、helm dependency update（更新依赖，未加 --skip-refresh）时；
• 使用本地缓存清单：执行 helm pull（拉取 Chart）、helm install/upgrade（安装/升级 Chart）、helm search repo（搜索 Chart）时（避免重复下载，提升速度）。

2.3 .tgz 文件：Chart 的“安装包”

.tgz 是 Chart 的压缩包（由 helm package 生成），相当于“安装程序”，规则简单：

• 命名：必须是 {Chart名}-{版本}.tgz（如 superapp-0.1.0.tgz）；
• 访问：下载地址需和 index.yaml 里的 urls 一致，访问时返回 200；
• 下载场景：执行 helm pull、helm install、helm upgrade 时，Helm 会自动下载该包。

2.4 .prov 文件：可选的“安全校验包”

.prov 是 Chart 的 PGP 签名文件，用于验证 Chart 完整性（防止篡改），属于可选但推荐的安全配置：

• 命名：和对应 .tgz 包同名，后缀加 .prov（如 superapp-0.1.0.tgz.prov）；
• 访问：必须和 .tgz 包在同一目录（如 tgz 地址是 xxx/superapp-0.1.0.tgz，则 prov 地址为 xxx/superapp-0.1.0.tgz.prov）；
• 下载场景：仅当执行命令时加 --verify 参数（如 helm install --verify），Helm 才会下载并校验。

2.5 存储库 API 的设计核心

这套 API 的目标是“简单 + 兼容”：只要是能运行 HTTP(S) 的静态服务，都能作为 Chart 存储库，无需搭建复杂后端，大幅降低 Chart 分发成本。

三、总结

1. Chart API 版本：v1 兼容旧环境，v2 是 Helm3 首选，核心差异在依赖配置和新特性支持，迁移步骤简单；
2. 存储库 API：核心是 index.yaml 清单，.tgz 是安装包，.prov 是安全校验包，规则轻量，静态服务器即可部署。

搞懂这些底层规则，不管是开发自定义 Chart，还是搭建私有 Chart 仓库，都能少踩坑～