排查操作系统软件包问题

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

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

身份验证和权限问题

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

Apt 错误示例：

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

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

如需更改服务帐号或将服务帐号附加到虚拟机，请参阅更改实例的服务帐号和访问权限范围。
其他虚拟机
对于其他虚拟机，您必须拥有一个可以代表虚拟机执行操作的服务帐号。
1. 创建一个服务帐号（如果您没有该帐号）。
2. 请在创建服务帐号时授予 Artifact Registry Reader (roles.artifactregistry.reader) 角色，这样您就无需在单独的步骤中配置权限。
确保虚拟机服务帐号具有代码库的读取权限以及 cloud-platform API 访问权限范围。
Compute Engine 虚拟机
Artifact Registry 会自动检索虚拟机服务帐号凭据。所需的配置取决于您使用的是默认服务帐号还是用户代管式服务帐号。

默认服务账号

如果虚拟机使用默认服务帐号，则此服务帐号默认具有 Editor 角色，包括对同一项目中代码库的读取权限。如果代码库与虚拟机位于不同的项目中，请向虚拟机服务帐号授予 Artifact Registry Reader 角色。

此外，默认服务帐号并不具有所有必需的 API 访问权限范围。

如需设置 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 访问权限范围。
其他虚拟机
向虚拟机服务帐号授予 Artifact Registry Reader 角色。默认情况下，用户代管式服务帐号具有 cloud-platform 访问权限范围。
确认您已按照相关步骤准备好虚拟机以访问代码库。请参阅 Apt 或 Yum 准备说明。
确认您已正确配置 Apt 或 Yum，以访问代码库。

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

凭据帮助程序问题

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

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

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

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

在虚拟机上安装签名密钥：
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-central1-apt.pkg.dev\apt-project\apt-repo：

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

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

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-central1/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 虚拟机

其他虚拟机