工件缓存故障排除指南
本文是教程系列的第四部分。 第一部分概述了工件缓存及其功能、优势和限制。 在第二部分中，你将了解如何使用 Azure CLI 启用工件缓存功能。 在第三部分中，你将了解如何使用 Azure CLI 通过身份验证启用工件缓存功能。
本文可帮助排查尝试使用工件缓存时可能会遇到的问题。
症状和原因
可能包括以下一个或多个问题：
缓存的映像未显示在实际存储库中
凭据状态不正常
无法创建缓存规则
无法使用通配符创建缓存规则
可能的解决方案
缓存的映像未显示在实时存储库中
如果你遇到缓存的映像未显示在 ACR 的存储库中的问题，我们建议验证存储库路径。 错误的存储库路径会导致缓存的映像不会显示在 ACR 的存储库中。
- Docker Hub 的登录服务器为
docker.io。 - Microsoft 工件注册表的登录服务器为
mcr.microsoft.com。
Azure 门户会自动填充这些字段。 但是，许多 Docker 存储库的路径以 library/ 开头。 例如，若要缓存 hello-world 存储库，正确的存储库路径为 docker.io/library/hello-world。
凭据不正常
凭据是一组密钥保管库机密，以专用存储库的用户名和密码形式运行。 凭据不正常的原因通常是这些机密不再有效。 在 Azure 门户中，你可以选择凭据以编辑和应用更改。
- 验证 Azure 密钥保管库中的机密是否未过期。
- 验证 Azure 密钥保管库中的机密是否有效。
- 验证是否分配了对 Azure 密钥保管库的访问权限。
若要分配对 Azure 密钥保管库的访问权限：
az keyvault set-policy --name myKeyVaultName --object-id myObjID --secret-permissions get
详细了解密钥保管库。 详细了解如何分配对 Azure 密钥保管库的访问权限。
无法创建缓存规则
缓存规则限制
如果在创建缓存规则时遇到问题，建议验证是否创建了超过 1000 个缓存规则。
建议删除任何不需要的缓存规则，以避免达到限制。
详细了解缓存术语
无法使用通配符创建缓存规则
如果尝试创建缓存规则，但与现有规则存在冲突。 错误消息显示，已存在具有指定目标存储库通配符的缓存规则。
要解决此问题，需要执行以下步骤：
确定导致冲突的现有缓存规则。 查找对目标存储库使用通配符(*)的现有规则。
删除与源存储库和通配符重叠的冲突缓存规则。
使用所需的通配符和目标存储库创建新的缓存规则。
仔细检查缓存配置，确保正确应用新规则，并且没有其他存在冲突的规则。
上游支持
工件缓存当前支持以下上游注册表：
| 上游注册表 | 支持 | 可用性 |
|---|---|---|
| Docker Hub | 支持经过身份验证的拉取和未经身份验证的拉取。 | Azure CLI、Azure 门户 |
| Microsoft 工件注册表 | 仅支持未经身份验证的拉取。 | Azure CLI、Azure 门户 |
| ECR Public | 仅支持未经身份验证的拉取。 | Azure CLI、Azure 门户 |
| GitHub 容器注册表 | 支持经过身份验证的拉取和未经身份验证的拉取。 | Azure CLI、Azure 门户 |
| Nvidia | 支持经过身份验证的拉取和未经身份验证的拉取。 | Azure CLI |
| Quay | 支持经过身份验证的拉取和未经身份验证的拉取。 | Azure CLI、Azure 门户 |
| registry.k8s.io | 支持经过身份验证的拉取和未经身份验证的拉取。 | Azure CLI |