📚 课程目录第3章 Helm Chart在OCI中的存储结构

3. Helm Chart 在 OCI 中的存储结构：Repository、Tag、Digest、Manifest 的组成与关系

当 Helm Chart 被推送至 OCI Registry 后，其物理存储结构不再是传统的 tgz 文件，而是由 Repository、Tag、Digest 和 Manifest 四个核心元素构成的 OCI 制品体系。理解这四者的组成与关系，是构建变更门禁与回滚判断的基础。

3.1 四要素定义与职责

要素	定义	在 Helm 中的角色
Repository	OCI 中的命名空间，类似文件系统中的目录	标识 Chart 的名称与归属，如 `oci://registry.example.com/charts/nginx`
Tag	指向某个具体版本的引用标签，可变	通常对应 Chart 版本号，如 `1.2.3`，可被覆盖
Digest	基于内容计算的 SHA256 哈希值，不可变	唯一标识 Chart 内容的精确快照，用于防篡改验证
Manifest	描述 OCI 制品的元数据 JSON 文档	记录 Chart 的层信息、配置、签名引用等

关键认知： Tag 是“指针”，Digest 是“指纹”。Tag 可以随时指向新的 Digest，但 Digest 一旦生成就永久绑定该内容。回滚判断的核心依据是 Digest 而非 Tag。

3.2 存储结构层次关系

Helm Chart 在 OCI Registry 中的存储遵循 OCI Distribution Spec 的层级模型。下图展示了从 Repository 到具体 Blob 的完整链路：

3.3 Manifest 内部结构详解

Manifest 是 OCI 存储的核心枢纽，它是一个 JSON 文档，记录了 Chart 的所有组成信息。以下是一个典型的 Helm Chart Manifest 示例：

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.cncf.helm.config.v1+json",
    "size": 1234,
    "digest": "sha256:a1b2c3d4..."
  },
  "layers": [
    {
      "mediaType": "application/vnd.cncf.helm.chart.content.v1.tar+gzip",
      "size": 56789,
      "digest": "sha256:e5f6g7h8..."
    },
    {
      "mediaType": "application/vnd.cncf.helm.chart.provenance.v1.prov",
      "size": 890,
      "digest": "sha256:i9j0k1l2..."
    }
  ],
  "annotations": {
    "org.opencontainers.image.title": "nginx",
    "org.opencontainers.image.version": "1.2.3"
  }
}

  Manifest 关键字段说明：
  config：存储 Chart.yaml 的元数据，包括名称、版本、API 版本等。
layers：实际内容层，至少包含 Chart 压缩包层，可选包含 provenance 签名层。
annotations：附加标签，可用于存储版本号、描述等辅助信息。
digest：Manifest 自身的 SHA256 哈希，作为整个制品的唯一标识。

3.4 四要素关系总结

四要素之间的核心关系可以用以下流程概括：

Repository 作为容器，容纳多个版本的 Chart。
每个版本通过 Tag 引用，Tag 通常与 Chart 版本号一致。
Tag 指向一个 Manifest，Manifest 的 SHA256 值即为 Digest。
Manifest 内部描述 Config 和 Layers，这些内容以 Blob 形式存储，Blob 的地址也是 Digest。

门禁与回滚启示： 在变更门禁中，应校验 Tag 对应的 Digest 是否与预期一致，防止 Tag 被篡改指向恶意版本。在回滚判断中，应基于 Digest 而非 Tag 进行版本比对，因为 Digest 保证内容一致。

3.5 常见操作与对应关系

操作	涉及要素	说明
`helm push`	Repository + Tag + Manifest + Digest	生成新 Manifest，计算 Digest，关联 Tag
`helm pull`	Repository + Tag/Digest	通过 Tag 或 Digest 获取 Manifest，再拉取 Blob
`helm list --repo`	Repository + Tag	列出 Repository 下所有 Tag
`oras copy`	Repository + Digest	基于 Digest 精确复制制品，避免 Tag 歧义