文档首页/ 容器镜像服务 SWR/ 最佳实践（企业版）/ 使用 OCI v1.1.0 规范管理和关联容器镜像及其衍生制品
更新时间：2026-09-22 GMT+08:00
查看PDF
分享

使用 OCI v1.1.0 规范管理和关联容器镜像及其衍生制品

操作场景

在云原生应用交付过程中，容器镜像通常需要关联多种衍生制品（Artifact），包括软件物料清单（SBOM）、数字签名、漏洞扫描报告、attestation等。这些制品与镜像形成关联关系，共同构成可追溯、可验证的供应链安全体系。

容器镜像服务（SWR）企业版支持 OCI Image 和 Distribution 规范，您可以使用 ORAS（OCI Registry As Storage）客户端将衍生制品推送到 SWR，并通过 Referrers API 查询镜像关联的制品树，实现镜像及其衍生制品的统一管理和关联。

通过本章节的操作，您可以实现：

  • 使用 ORAS 将 SBOM、签名等衍生制品推送到 SWR 并与镜像建立关联关系。
  • 通过 Referrers API 或 SWR API 查询镜像的关联制品树。
  • 跨 SWR 实例分发制品及其关联关系。

OCI 规范与衍生制品概述

OCI（Open Container Initiative）规范定义了容器镜像和制品的标准格式与分发协议。OCI Distribution 规范 v1.1.0 引入了 Reference Types（引用类型），允许一个制品引用另一个制品，从而实现衍生制品与目标镜像的关联。

表1 OCI规范组件说明

规范组件

说明

OCI Image Format

定义容器镜像的清单（Manifest）、配置（Config）和分层（Layers）的格式。

OCI Distribution Spec

定义镜像仓库的推送、拉取、发现等 HTTP API 接口。

OCI Image Specification (v1.1.0)

在 Manifest 中引入 subject 字段，用于表明当前制品与另一个制品的“父子”关联关系。

OCI Reference Types（独立规范）

定义通过独立的 Referrers API 来发现和获取与制品关联的附件（如签名、SBOM），无需修改原镜像清单，通常配合 artifactType 使用。
表2 常见衍生制品类型

制品类型

用途

SBOM（软件物料清单）

列出镜像中包含的所有软件组件及其版本，用于供应链安全合规审计。

数字签名

对镜像内容进行签名，确保镜像完整性和来源可信。

漏洞扫描报告

记录镜像漏洞扫描结果，用于安全合规验证。

attestation

证明镜像构建过程的元数据（如构建时间、构建者、构建环境）。

约束与限制

  • ORAS 客户端版本需 1.1.0 及以上，以支持 Reference Types 功能。
  • 衍生制品的 mediaType 需遵循 OCI 规范格式（如application/vnd.oci.image.manifest.v1+json）。
  • 推送衍生制品时，目标镜像必须已存在于 SWR 中，否则无法建立关联关系。

前提条件

  • 已创建 SWR 企业版实例，且实例状态为"可用"。
  • 已创建命名空间，且已获取登录指令（镜像仓库地址和认证信息）。
  • 已在 SWR 中推送至少一个容器镜像，作为衍生制品的关联目标。
  • 已安装 Docker（用于构建和推送基础镜像）。
  • 本地或 CI 环境已安装 ORAS CLI 1.1.0 及以上版本。安装方法请参见ORAS 官方安装指南。
  • 已安装syft工具，安装方法请参见syft 官方安装指南。

安装和配置 ORAS 客户端

  1. 安装 ORAS

    Linux 环境安装示例：

    # 下载ORAS
curl -LO https://github.com/oras-project/oras/releases/download/v1.2.0/oras_1.2.0_linux_amd64.tar.gz
# 解压
tar -xzf oras_1.2.0_linux_amd64.tar.gz
# 移动到系统路径
sudo mv oras /usr/local/bin/ 
# 验证安装
oras version

  2. 安装syft

    安装示例：

    # 安装syft（SBOM生成工具）
curl -sSfL https://get.anchore.io/syft | sudo sh -s -- -b /usr/local/bin
# 验证安装 
syft version

  3. 登录 SWR 企业版实例

    使用 SWR 企业版实例的登录指令进行认证： 
    oras login <实例地址> -u <用户名> -p <密码>

    实例地址格式为“注册表总览界面 > 访问地址”，可在 SWR 控制台企业版实例详情页 > 访问管理 > 访问凭证获取登录指令。

推送衍生制品到 SWR

以下分别以 SBOM 和镜像签名为例，说明如何将衍生制品推送到 SWR 并与目标镜像建立关联。

场景一：生成 SBOM 并推送到 SWR

  1. 生成 SBOM 文件

    使用 syft 工具为已有镜像生成 SBOM（以 JSON 格式为例）： 
    syft <实例地址>/<命名空间>/<镜像名称>:<版本> -o json > sbom.json

    生成的 sbom.json 文件包含镜像中所有软件组件的清单信息。

  2. 附加 SBOM 文件（关联到主镜像）

    使用 oras attach 命令将 SBOM 关联到已有镜像： 
    oras attach <实例地址>/<命名空间>/<镜像名称>:<版本> \  
    --artifact-type application/sbom+json \  
    ./sbom.json:application/json

    application/sbom+json 是 --artifact-type 的一个示例值，你也可以根据 SBOM 的具体格式使用标准的媒体类型（如 application/vnd.sbom.spdx+json）。

  3. 成功执行后，可以用 oras discover 命令查看主镜像下关联的 SBOM 制品列表： 

    oras discover <实例地址>/<命名空间>/<镜像名称>:<版本> --artifact-type application/sbom+json

场景二：使用 Cosign 对镜像签名并推送

SWR 企业版提供原生的镜像签名功能，使用数据加密服务（DEW）中的密钥对镜像进行签名，保障镜像分发部署过程中的一致性，避免中间人攻击和非法镜像更新。镜像签名操作请参见镜像签名。

查询镜像的关联制品树

推送衍生制品后，您可以通过以下方式查询镜像关联的所有制品。

  • 使用 ORAS 查询关联制品

    使用 ORAS 的 discover 命令查询目标镜像关联的所有衍生制品：

    oras discover <实例地址>/<命名空间>/<镜像名称>:<版本>
  • 使用 SWR API 查询制品和附件
    SWR 企业版提供以下 API 用于查询制品和附件信息：
    表3 API参数表

    API

    用途

    ListInstanceArtifacts

    获取制品版本列表

    ShowInstanceArtifact

    获取制品版本详情

    ListInstanceAccessories

    获取制品附件列表

    查询制品附件列表示例：

    GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/namespaces/{namespace_name}/repositories/{repository_name}/artifacts/{reference}/accessories

    返回结果中包含该制品关联的所有衍生制品的 digest、类型和大小等信息。

拉取衍生制品

您可以使用 ORAS 拉取指定的衍生制品到本地：

oras pull <实例地址>/<命名空间>/<镜像名称>@sha256:<制品digest>

拉取衍生制品时使用 digest（而非 tag）进行引用，确保获取的是不可变的具体版本。

跨实例分发制品

当您需要将镜像及其所有衍生制品从一个 SWR 实例同步到另一个实例（如从开发环境同步到生产环境）时，可以使用 ORAS 的 copy 命令：

oras copy -r \
    <源实例地址>/<命名空间>/<镜像名称>:<版本>\
    <目标实例地址>/<命名空间>/<镜像名称>:<版本>
  • -r（--recursive）参数表示递归复制，ORAS 会将目标镜像及其所有关联的衍生制品（SBOM、签名、扫描报告等）一并复制到目标实例，保持制品间的关联关系。
  • 跨实例分发前，请确保已在源实例和目标实例均完成 ORAS 登录认证。

相关文档