# 使用 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（引用类型），允许一个制品引用另一个制品，从而实现衍生制品与目标镜像的关联。
表1OCI规范组件说明 
| 规范组件                            | 说明                                                                              |
|:---|:---|
| 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 官方安装指南](https://oras.land/docs/installation)。
- 已安装syft工具，安装方法请参见[syft 官方安装指南](https://github.com/anchore/syft/?tab=readme-ov-file#installation)。
 
#### 安装和配置 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
   ```
   ![](https://support.huaweicloud.com/bestpractice2-swr/public_sys-resources/note_3.0-zh-cn.png)
   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）中的密钥对镜像进行签名，保障镜像分发部署过程中的一致性，避免中间人攻击和非法镜像更新。镜像签名操作请参见[镜像签名](https://support.huaweicloud.com/usermanual2-swr/swr_02_0431.html)。
#### 查询镜像的关联制品树
推送衍生制品后，您可以通过以下方式查询镜像关联的所有制品。
- **使用 ORAS 查询关联制品**
  使用 ORAS 的 discover 命令查询目标镜像关联的所有衍生制品：
  ```
  oras discover <实例地址>/<命名空间>/<镜像名称>:<版本>
  ```
  

- **使用 SWR API 查询制品和附件**
  SWR 企业版提供以下 API 用于查询制品和附件信息：
  表3API参数表 
  | API                                                                                   | 用途       |
  |:---|:---|
  | [ListInstanceArtifacts](https://support.huaweicloud.com/api-swr2/swr_03_0301.html)     | 获取制品版本列表 |
  | [ShowInstanceArtifact](https://support.huaweicloud.com/api-swr2/swr_03_0302.html)     | 获取制品版本详情 |
  | [ListInstanceAccessories](https://support.huaweicloud.com/api-swr2/swr_03_0304.html) | 获取制品附件列表  |
     
  查询制品附件列表示例：
  ```
  GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/namespaces/{namespace_name}/repositories/{repository_name}/artifacts/{reference}/accessories
  ```
  返回结果中包含该制品关联的所有衍生制品的 digest、类型和大小等信息。
  
 
#### 拉取衍生制品
您可以使用 ORAS 拉取指定的衍生制品到本地：
```
oras pull <实例地址>/<命名空间>/<镜像名称>@sha256:<制品digest>
```
![](https://support.huaweicloud.com/bestpractice2-swr/public_sys-resources/caution_3.0-zh-cn.png)
拉取衍生制品时使用 digest（而非 tag）进行引用，确保获取的是不可变的具体版本。
#### 跨实例分发制品
当您需要将镜像及其所有衍生制品从一个 SWR 实例同步到另一个实例（如从开发环境同步到生产环境）时，可以使用 ORAS 的 copy 命令：
```
oras copy -r \
    <源实例地址>/<命名空间>/<镜像名称>:<版本>\
    <目标实例地址>/<命名空间>/<镜像名称>:<版本>
```
- -r（--recursive）参数表示递归复制，ORAS 会将目标镜像及其所有关联的衍生制品（SBOM、签名、扫描报告等）一并复制到目标实例，保持制品间的关联关系。
- 跨实例分发前，请确保已在源实例和目标实例均完成 ORAS 登录认证。