排查操作系统软件包问题

了解在管理 Artifact Registry 中的操作系统软件包时遇到问题时，您可能会发现有用的问题排查步骤。

身份验证和权限问题

您无法连接到代码库以执行安装软件包等操作。 软件包管理器的输出中包含 401 或 403 错误，这表示身份验证或权限存在问题。

Apt 错误示例：

Err:1 ar+https://-apt.pkg.dev/projects/my-project my-package Release
  Error downloading: code 401

E: Failed to fetch https://-apt.pkg.dev/projects/my-project/dists/quickstart-apt-repo/main/binary-amd64/Packages  403  Forbidden [IP: 74.125.20.82 443]
E: Some index files failed to download. They have been ignored, or old ones used instead.

Yum 错误示例：

/repodata/repomd.xml: [Errno 14] HTTPS Error 403 - Forbidden

这些错误可能有多种原因。确保您的虚拟机满足以下要求：

  1. 验证虚拟机是否具有关联的服务帐号。

    Compute Engine 虚拟机

    1. 转到虚拟机实例页面。

    2. 在虚拟机列表中，点击虚拟机的名称。

      在详细信息 标签页上，服务帐号和访问权限范围会显示在 API 和身份管理 下。

    默认情况下，Compute Engine 虚拟机使用 Compute Engine 默认服务账号，并且具有一组有限的 访问权限范围。默认服务帐号电子邮件地址 的格式为 PROJECT_NUMBER-compute@。

    根据您的组织政策配置，默认服务帐号可能会 自动获得项目的 Editor 角色。我们强烈建议您通过强制执行 iam.automaticIamGrantsForDefaultServiceAccounts 组织政策限制条件来停用自动角色授予功能。如果您的组织是在 2024 年 5 月 3 日之后创建的，则默认情况下会强制执行此限制条件。

    如果您停用自动角色授予功能，则必须决定向默认服务账号授予哪些角色，然后自行授予这些角色。

    如果默认服务帐号已具有 Editor 角色，我们建议您将 Editor 角色替换为权限较少的角色。

    如需更改服务帐号或将服务帐号关联到虚拟机，请参阅 更改实例的服务帐号和访问权限范围。

    其他虚拟机

    对于其他虚拟机，您必须拥有一个服务帐号才能代表虚拟机执行操作。

    1. 如果您没有服务帐号，请创建一个服务账号。

    2. 在创建服务帐号时授予 Artifact Registry Reader (roles.artifactregistry.reader) 角色，这样您就不需要在单独的步骤中配置权限。

  2. 确保虚拟机服务帐号对代码库以及 cloud-platform API 访问权限范围具有读取权限。

    Compute Engine 虚拟机

    Artifact Registry 会自动检索虚拟机服务帐号凭据。如果代码库与虚拟机位于不同的项目中，则您必须向虚拟机服务账号授予 Artifact Registry Reader 角色。您还必须确保虚拟机具有 cloud-platform 访问权限范围。

    如需设置 cloud-platform 访问权限范围，请执行以下操作：

    1. 停止虚拟机实例，将 INSTANCE 替换为虚拟机实例名称。

      gcloud compute instances stop INSTANCE

    2. 设置访问权限范围：

      gcloud compute instances set-service-account INSTANCE \
    --scopes=cloud-platform

    3. 重启虚拟机实例。

      gcloud compute instances start INSTANCE

    其他虚拟机

    向虚拟机服务 账号授予 Artifact Registry Reader 角色。默认情况下，用户代管式服务账号具有 cloud-platform 访问权限范围。

  3. 验证您是否已按照准备虚拟机以访问代码库的步骤操作。请参阅 Apt 或 Yum 准备 说明。

  4. 验证您是否已正确配置 Apt 或 Yum 以访问代码库。

    如果您要从 Compute Engine 虚拟机连接到 Apt 代码库，请确保代码库网址包含 ar+ 前缀。

凭据帮助程序问题

当虚拟机无法找到 Apt 凭据帮助程序时，系统会显示以下错误消息：

E: Unable to locate package apt-transport-artifact-registry

当您尝试在从不包含 Apt 代码库签名密钥的映像创建的虚拟机上安装 apt-transport-artifact-registry 软件包时，会发生此错误。

如需解决此问题，请执行以下操作：

  1. 在虚拟机上安装签名密钥：

    Debian 虚拟机

    使用以下命令安装 Apt 代码库签名密钥：

    curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add -

    将 LOCATION 替换为代码库的区域级 位置。

    Ubuntu 虚拟机

    使用以下命令安装 Apt 代码库签名密钥：

    curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add - && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

    将 LOCATION 替换为代码库的区域级 位置。

  2. 重新尝试 虚拟机准备步骤。

身份验证插件问题

当 Yum 或 DNF 身份验证插件存在问题时，系统会显示以下错误消息：

Plugin "artifact-registry" can't be imported

此错误可能是由多种原因造成的。如需解决此错误，请尝试直接运行插件以确认依赖项、检查是否存在 Python 问题，或揭示其他可能的潜在问题。

如需直接运行插件，请使用以下命令之一：

  • 对于 Yum 插件：

    python /usr/lib/yum-plugins/artifact-registry.py

  • 对于 DNF 插件：

    python3 /usr/lib/pythonVERSION-NUMBER/site-packages/dnf-plugins/artifact-registry.py

    将 VERSION-NUMBER 替换为 Linux 发行版的默认 Python 版本。例如，Enterprise Linux 8 包含 Python 3.6。

    您可以列出已安装插件软件包中的文件，以验证 Python 库目录的名称。

    rpm -ql dnf-plugin-artifact-registry|grep artifact-registry.py

缺少最近上传的制品

如果您的 Apt 或 Yum 客户端找不到最近上传或导入到代码库的软件包，可能是因为重新生成 Apt 或 Yum 软件包索引的过程尚未完成。

对于小型代码库，重新生成 Apt 或 Yum 索引文件可能需要几秒钟。对于较大的代码库，重新编制索引可能需要几分钟或更长时间。

如需验证软件包是否已成功添加到代码库，请使用 Google Cloud CLI 列出软件包中的文件。运行以下命令：

gcloud artifacts files list \
    --package=PACKAGE \
    --project=PROJECT-ID \
    --repository=REPOSITORY \
    --location=LOCATION

例如，您可以使用以下命令检查名为 python3-gflags_1.5.1-5_all.deb 的python-gflags 软件包是否已成功上传到代码库 -apt.pkg.dev\apt-project\apt-repo：

gcloud artifacts files list \
    --package=python-gflags \
    --project=apt-project \
    --repository=apt-repo \
    --location=

如果软件包上传成功，则该文件会显示在输出中，并且文件名中包含唯一标识符，类似于以下示例：

FILE                                                                  CREATE_TIME          UPDATE_TIME          SIZE (MB)  OWNER
pool/python3-gflags_1.5.1-5_all_2414c7af6a64c99a5f488aad366d637a.deb  2023-01-12T20:39:53  2023-01-12T20:39:53  0.035      projects/apt-project/locations//repositories/apt-repo/packages/python3-gflags/versions/1.5.1-5

某些上传或导入的软件包的身份验证错误

如果导入或上传文件的时间超过身份验证令牌的有效期，则超出有效期后的上传将失败。令牌会在您获取后 60 分钟过期。如果令牌已过期，导入命令的输出中会显示类似于以下示例的错误。

errors:
- error:
    code: 16
    message: The request does not have valid authentication credentials.
  gcsSource:
    uris:
    - gs://my-bucket/debs/python/python3-gflags_1.5.1-5_all.deb

如需解决此问题，请执行以下操作：

  1. 尝试仅上传或导入特定软件包，以验证您是否可以单独添加软件包，而不是批量导入。
  2. 如果多个软件包失败，请分批导入或上传，以便操作不会超过令牌的有效期。