此页面由 Cloud Translation API 翻译。

排查操作系统软件包问题

如果您在 Artifact Registry 中管理操作系统软件包时遇到问题，可查阅以下实用的问题排查步骤。

如需了解如何解决 Artifact Registry 远程代码库（适用于操作系统软件包）的问题，请参阅排查远程代码库问题。

身份验证和权限问题

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

预约错误示例：

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

E: Failed to fetch https://us-west1-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

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

验证虚拟机是否具有关联的服务账号。
Compute Engine 虚拟机
1. 转到虚拟机实例页面。
2. 在虚拟机列表中，点击您的虚拟机的名称。
  
  在详细信息标签页上，服务账号和访问权限范围会显示在 API 和身份管理下。
默认情况下，Compute Engine 虚拟机使用 Compute Engine 默认服务账号，并且具有有限的一组访问范围。默认服务账号电子邮件地址的格式为 PROJECT_NUMBER-compute@developer.gserviceaccount.com。

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

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

如果默认服务账号已具有 Editor 角色，我们建议您将 Editor 角色替换为权限较少的角色。如需安全地修改服务账号的角色，请使用 Policy Simulator 查看更改的影响，然后授予和撤消相应的角色。

如需更改服务账号或将服务账号关联到虚拟机，请参阅更改实例的服务账号和访问权限范围。
其他 VM
对于其他虚拟机，您必须拥有一个服务账号才能代表虚拟机执行操作。
1. 如果您没有服务账号，请创建一个服务账号。
2. 在创建服务账号时授予 Artifact Registry Reader (roles.artifactregistry.reader) 角色，这样您就不需要在单独的步骤中配置权限。
确保虚拟机服务账号对相应代码库具有读取权限，并且具有 cloud-platform API 访问权限范围。
Compute Engine 虚拟机
Artifact Registry 会自动检索虚拟机服务账号凭据。如果代码库与虚拟机位于不同的项目中，则您必须向虚拟机服务账号授予 Artifact Registry 读取者角色。您还必须确保虚拟机具有 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
其他 VM
向虚拟机服务账号授予 Artifact Registry Reader 角色。默认情况下，用户代管式服务账号具有 cloud-platform 访问权限范围。
验证您是否已按照相关步骤准备虚拟机以访问代码库。请参阅 Apt 或 Yum 准备说明。
验证您是否已正确配置 Apt 或 Yum 以访问代码库。

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

凭据帮助程序问题

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

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

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

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

在虚拟机上安装签名密钥：
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 替换为代码库的单区域或多区域位置。
重新尝试执行虚拟机准备步骤。

身份验证插件问题

当 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 软件包是否已成功上传到代码库 us-west1-apt.pkg.dev\apt-project\apt-repo：

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

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

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/us-west1/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

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

尝试仅上传或导入特定软件包，以验证您是否可以单独添加该软件包，而不是批量导入。
如果多个软件包失败，请分批导入或上传，以免操作超出令牌过期期限。

排查操作系统软件包问题 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

身份验证和权限问题

Compute Engine 虚拟机

其他 VM