使用指纹验证软件包版本身份

您可以使用制品指纹来唯一标识 Artifact Registry 代码库中的软件包。

当您将软件包推送到代码库时，Artifact Registry 会计算相应软件包版本的指纹。指纹是一种加密不可变的引用，可用于验证软件包在 Google Cloud系统（例如 Compute Engine 和 Cloud Build）之间移动时是否未被修改。检索软件包的指纹后，您可以使用该指纹来确保软件包在某些 Artifact Registry API 请求期间有效。 您还可以通过手动计算本地指纹并将其与仓库中的指纹进行比较，来验证同一软件包的本地实例和仓库实例。

准备工作

  1. 启用 Artifact Registry，包括启用 Artifact Registry API 和安装 Google Cloud CLI。
  2. （可选）为 gcloud 命令配置默认值。

所需的角色

如需获得在 Artifact Registry 代码库中查看软件包版本指纹所需的权限，请让您的管理员为您授予 Google Cloud 项目的 Artifact Registry Reader (roles/artifactregistry.reader) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

检索代码库中软件包版本的指纹

指纹具有以下结构：

VERSION@DIRSUM_SHA256:HASH_VALUE

如需检索 Artifact Registry 代码库中软件包版本的指纹，请在 Google Cloud CLI 中输入以下内容：

gcloud artifacts versions describe VERSION --repository=REPOSITORY --location=LOCATION --package=PACKAGE_NAME

其中：

  • VERSION 是软件包的版本，例如 1.0543。
  • REPOSITORY 是包含您要评估的软件包的代码库
  • LOCATION 是代码库的单区域或多区域位置。如果您设置默认位置，则可以省略此标志。
  • PACKAGE_NAME 是软件包的名称。

响应如下所示：

fingerprints:
- type: DIRSUM_SHA256
  value: 7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04
name: projects/test-project/locations/us-west1/repositories/test-repo/packages/test-pkg/versions/v1
updateTime: '2025-08-15T00:03:41.809228Z'

指纹的完整地址是软件包版本，后跟指纹类型和哈希值。在此示例中，指纹地址为 VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04。

在 Artifact Registry API 中验证指纹是否为不可变引用

如果 Artifact Registry API 请求中软件包的指纹格式如下所示，则会验证您代码库中的相应软件包：

VERSION@DIRSUM_SHA256:HASH_VALUE

例如，您想在代码库中的软件包上创建附件。在以下命令中，为 target 定义的软件包的格式可让 Artifact Registry 同时验证软件包的指纹：

  gcloud artifacts attachments create my-attachment --target='projects/test-project/locations/us-west1/repositories/test-repo/packages/test-pkg/versions/v1@dirsum_sha256:30330c6b65a26ebf1a13e1b9ded4068b4c36d72ed3b62226e3243b5bee18fd31' --attachment-type="application/vnd.in-toto+json" --attachment-namespace="mynamespace.com" --files=att.txt

如果提供的指纹与当前版本的指纹不匹配，Artifact Registry 会拒绝相应 API 请求并显示 failed_precondition 错误。

以下请求在通过 API 库、Google Cloud CLI 和 curl 传递时，会验证所提供的指纹：

以下请求在通过 API 库和 curl 传递时会验证指纹：

验证软件包的本地实例和代码库实例是否相同

如需验证软件包在Google Cloud 系统之间移动时是否未被修改，请在您的代码库之外手动计算该软件包实例的指纹。

如需手动计算指纹，请执行以下操作：

  1. 按照查看代码库中软件包的指纹中的说明，在 Artifact Registry 中找到软件包的指纹。

  2. 手动计算外部软件包的指纹：

    1. 获取软件包中每个文件的短文件名和各个 SHA256 哈希值：

      1. 在 Google Cloud 控制台中打开代码库页面：

        打开“代码库”页面

      2. 选择您的代码库，然后选择包含要验证的软件包版本的映像。

      3. 点击文件标签页。

      4. 确定页面上显示的每个文件的短文件名和 SHA256 哈希值。 短文件名是文件位置后面的最终字符串。 例如，以下屏幕截图显示了 Maven 代码库中某个软件包的 Version 5.0 的六个文件。每个文件名都以 my-app-5.0 开头。每个文件的哈希值显示在 Hashes 列下：

        Maven 软件包版本 5.0 的 **文件** 标签页示例。

    2. 按短文件名的字母顺序对文件进行排序。

    3. 对于每个已排序的文件条目，将文件信息合并为以下缩短的字符串，在哈希值和文件名之间添加两个空格，并以 null 字节结尾：

      HASH_VALUE FILE_NAME/0

    4. 将每个缩短的字符串合并为一个完整序列，每个字符串之间没有空格或字符。

    5. 计算完整序列的 SHA256 哈希值。最终的 SHA256 哈希值是外部软件包的 dirsum_sha256。

  3. 比较手动计算的指纹与代码库中软件包的指纹。如果两个指纹相同，则表示您代码库中的软件包实例未被修改。