本頁面由 Cloud Translation API 翻譯而成。

排解 OS 套件問題

瞭解實用的疑難排解步驟，解決您在 Artifact Registry 中管理 OS 套件時遇到的問題。

如要瞭解如何解決 OS 套件的 Artifact Registry 遠端存放區問題，請參閱「排解遠端存放區問題」。

驗證和權限問題

您無法連線至存放區，執行安裝套件等動作。套件管理員的輸出內容包含 401 或 403 錯誤，表示驗證或權限有問題。

Apt 錯誤示例：

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

這些錯誤的可能原因有很多。請確認 VM 符合下列規定：

確認 VM 有相關聯的服務帳戶。
Compute Engine VM
1. 前往「VM instances」(VM 執行個體) 頁面。
2. 在 VM 清單中，按一下 VM 的名稱。
  
  在「詳細資料」分頁中，服務帳戶和存取範圍會顯示在「API 和身分管理」下方。
根據預設，Compute Engine VM 會使用 Compute Engine 預設服務帳戶，並具有一組有限的存取範圍。預設服務帳戶電子郵件地址的格式為 PROJECT_NUMBER-compute@developer.gserviceaccount.com。

視機構政策設定而定，系統可能會自動將專案的編輯者角色授予預設服務帳戶。強烈建議您強制執行 iam.automaticIamGrantsForDefaultServiceAccounts 機構政策限制，停用自動授予角色功能。如果您是在 2024 年 5 月 3 日後建立機構，系統預設會強制執行這項限制。

停用自動角色授予功能後，您必須決定要將哪些角色授予預設服務帳戶，然後自行授予這些角色。

如果預設服務帳戶已具備「編輯者」角色，建議您將「編輯者」角色替換為權限較少的角色。如要安全地修改服務帳戶的角色，請使用政策模擬器查看變更的影響，然後授予及撤銷適當的角色。

如要變更服務帳戶或將服務帳戶附加至 VM，請參閱「變更執行個體的服務帳戶與存取權範圍」。
其他 VM
如果是其他 VM，您必須具備服務帳戶，才能代表 VM 執行動作。
1. 如果沒有服務帳戶，請建立服務帳戶。
2. 建立服務帳戶時，請授予 Artifact Registry Reader (roles.artifactregistry.reader) 角色，這樣就不必另外設定權限。
確認 VM 服務帳戶具備存放區的讀取權限，以及 cloud-platform API 存取範圍。
Compute Engine VM
Artifact Registry 會自動擷取 VM 服務帳戶憑證。如果存放區與 VM 位於不同專案，則必須授予 VM 服務帳戶 Artifact Registry 讀者角色。此外，請務必確認 VM 具有 cloud-platform 存取範圍。

如要設定 cloud-platform 存取範圍，
1. 停止 VM 執行個體，並將 INSTANCE 替換為 VM 執行個體名稱。
  gcloud compute instances stop INSTANCE
2. 設定存取範圍：
  gcloud compute instances set-service-account INSTANCE \ --scopes=cloud-platform
3. 重新啟動 VM 執行個體。
  gcloud compute instances start INSTANCE
其他 VM
將 Artifact Registry 讀取者角色授予 VM 服務帳戶。根據預設，使用者管理的服務帳戶具有cloud-platform存取權範圍。
確認您已按照步驟準備 VM，以便存取存放區。請參閱 Apt 或 Yum 準備操作說明。
確認您已正確設定 Apt 或 Yum，以便存取存放區。

如果您是從 Compute Engine VM 連線至 Apt 存放區，請務必確認存放區網址包含 ar+ 前置字元。

憑證輔助程式問題

如果 VM 找不到 Apt 憑證輔助程式，就會顯示下列錯誤訊息：

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

如果您嘗試在從映像檔建立的 VM 上安裝 apt-transport-artifact-registry 套件，但該映像檔未包含 Apt 存放區簽署金鑰，就會發生這個錯誤。

如要解決這個問題，請按照下列步驟操作：

在 VM 上安裝簽署金鑰：
Debian VM
使用下列指令安裝 Apt 存放區簽署金鑰：
```
curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add -
```
將 LOCATION 替換為存放區的區域或多區域位置。
Ubuntu VM
使用下列指令安裝 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 替換為存放區的區域或多區域位置。
重新嘗試準備 VM 的步驟。

驗證外掛程式問題

如果 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

如果套件上傳成功，輸出內容中會顯示該檔案，且檔案名稱中含有專屬 ID，類似以下範例：

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

如要解決這個問題，請按照下列步驟操作：

請嘗試只上傳或匯入特定套件，確認您可以個別新增套件，而不是批次匯入。
如果有多個套件失敗，請分批匯入或上傳較小的檔案，確保作業不會超過權杖到期時間。

排解 OS 套件問題 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

驗證和權限問題

Compute Engine VM

其他 VM