4. OCI 分发协议核心：Artifact Manifest、Referrers API、Distribution Spec 要点

OCI 分发协议是云原生供应链中镜像与制品的“物流标准”。本章聚焦三个核心组件：Artifact Manifest（制品清单）、Referrers API（引用查询接口）和 Distribution Spec（分发规范）。理解这三者的协同关系，是设计可信镜像供应链的基础。

4.1 OCI Artifact Manifest：超越容器镜像的制品描述

传统 OCI Image Manifest 仅描述容器层与配置。Artifact Manifest 将其扩展为通用制品描述格式，支持 SBOM、签名、扫描报告、策略文件等任意供应链元数据。

特性 Image Manifest (v1) Artifact Manifest (v1.1+)
描述对象 容器镜像层 + 配置 任意 OCI 制品（签名、SBOM、策略）
mediaType 固定为镜像类型 自定义或标准制品类型
subject 字段 无 指向被引用的目标制品 digest
artifactType 无 明确声明制品类别（如 application/vnd.cyclonedx）
引用查询 需遍历仓库 通过 Referrers API 直接查询
关键设计点：Artifact Manifest 通过 subject 字段建立“制品→目标镜像”的引用关系，使签名、SBOM 等元数据成为镜像的“附件”，而非独立对象。

4.2 Referrers API：按 digest 查询所有关联制品

Referrers API 是 OCI Distribution Spec 1.1 新增的端点，允许客户端通过 GET /v2/{repository}/referrers/{digest} 查询指定 digest 的所有引用制品。它解决了传统分发中“找到镜像后如何找到其签名/SBOM”的难题。

# 查询镜像 digest 的所有引用制品（按 artifactType 过滤）
GET /v2/my-repo/referrers/sha256:abc123?artifactType=application/vnd.cyclonedx

# 响应示例（简化）
{
  "references": [
    {
      "digest": "sha256:def456",
      "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
      "artifactType": "application/vnd.cyclonedx",
      "size": 1234
    },
    {
      "digest": "sha256:ghi789",
      "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
      "artifactType": "application/vnd.cncf.notary.v2.signature",
      "size": 567
    }
  ]
}
实践建议：在镜像推送流水线中，先推送镜像，再推送签名和 SBOM 的 Artifact Manifest，并确保 subject 字段指向镜像 digest。后续任何客户端均可通过 Referrers API 一次性获取所有关联制品。

4.3 Distribution Spec：分发协议的整体框架

OCI Distribution Spec 定义了仓库与客户端之间的 HTTP API 契约，涵盖 blob 上传/下载、manifest 管理、标签操作和引用查询。其核心端点如下：

端点 方法 用途
/v2/{repo}/blobs/{digest} GET / DELETE 获取或删除 blob（层、配置、附件）
/v2/{repo}/blobs/uploads/ POST / PUT 分片上传 blob
/v2/{repo}/manifests/{ref} GET / PUT / DELETE 管理 manifest（tag 或 digest 引用）
/v2/{repo}/referrers/{digest} GET 查询指定 digest 的所有引用制品
/v2/_catalog GET 列出仓库列表（可选）

4.4 三组件协同流程：从推送签名到验证

下图展示了 Artifact Manifest、Referrers API 和 Distribution Spec 在镜像供应链中的协同工作流：

OCI 分发协议三组件协同流程 OCI 分发协议三组件协同流程 推送方 (CI/CD) 镜像 Manifest Artifact Manifest Distribution Spec OCI 兼容仓库 Referrers API 验证方 (K8s/策略) 推送镜像 推送签名/SBOM 查询引用制品 流程说明： 1. 推送方先推送镜像 Manifest，再推送签名/SBOM 的 Artifact Manifest（subject 指向镜像 digest）。 2. 验证方通过 Referrers API 查询镜像 digest 的所有引用制品，无需遍历仓库。

4.5 关键设计要点与避坑

  • subject 字段必须指向不可变 digest：不要使用 tag 作为 subject 引用，tag 可变会导致引用断裂。始终使用 sha256:... 格式。
  • artifactType 标准化：建议使用已注册的媒体类型（如 application/vnd.cyclonedx、application/vnd.cncf.notary.v2.signature），避免自定义类型带来的互操作问题。
  • Referrers API 分页：当引用制品数量较多时，API 支持分页（通过 Link header），客户端应实现分页逻辑，避免遗漏。
  • 仓库兼容性：并非所有 OCI 仓库都实现了 Referrers API（如 Harbor 2.8+、Docker Hub 部分支持）。在生产环境前需验证目标仓库的兼容性。
常见陷阱：部分实现将 Artifact Manifest 的 mediaType 误设为 Image Manifest 类型，导致仓库无法正确识别为制品引用。务必使用 application/vnd.oci.artifact.manifest.v1+json。

4.6 三组件关系总结

组件 核心职责 依赖关系
Artifact Manifest 定义制品的元数据结构和引用关系 依赖 Distribution Spec 的 manifest 管理端点
Referrers API 提供按 digest 查询所有引用制品的接口 依赖 Artifact Manifest 的 subject 字段建立索引
Distribution Spec 定义 blob/manifest/引用查询的 HTTP 协议 作为底层传输协议，被前两者调用

三者共同构成了 OCI 分发协议的核心能力：Artifact Manifest 定义“是什么”和“引用谁”，Referrers API 提供“如何查”，Distribution Spec 保障“如何传”。在镜像供应链信任边界设计中，这一组合使得签名、SBOM、策略等元数据能够与镜像本身解耦分发，同时保持强关联性。

← 上一章 📖 返回目录 下一章 →