常见问题 - Azure Container Registry

是的。 下面是可用于创建注册表的 a 模板。

是的。 可以将 Microsoft Defender 用于容器或其他解决方案，例如 Aqua。

请参阅 Kubernetes 文档以及 Azure Kubernetes Service 的步骤。

若要获取管理员凭据，必须启用注册表的 管理员用户。

若要使用Azure CLI获取管理员凭据，请运行以下命令：

az acr credential show -n myRegistry

若要使用Azure PowerShell获取管理员凭据，请运行以下命令：

Invoke-AzureRmResourceAction -Action listCredentials -ResourceType Microsoft.ContainerRegistry/registries -ResourceGroupName myResourceGroup -ResourceName myRegistry

若要在Resource Manager模板中获取管理员凭据，请运行以下命令以获取第一个密码：

{
    "password": "[listCredentials(resourceId('Microsoft.ContainerRegistry/registries', 'myRegistry'), '2025-04-01').passwords[0].value]"
}

然后，若要获取第二个密码，请运行以下命令：

{
    "password": "[listCredentials(resourceId('Microsoft.ContainerRegistry/registries', 'myRegistry'), '2025-04-01').passwords[1].value]"
}

若要使用 Azure 门户获取管理员凭据，请转到注册表并在服务菜单中的 Settings 下选择 Access 密钥。

以下 Azure 内置策略可用于防止用户在注册表上启用管理员用户：

如果注册表上具有容器注册表参与者和数据访问配置管理员角色（允许通过Azure CLI删除副本），但订阅上没有“读取者”角色，则会发生此错误。 若要解决此问题，请将读取者角色分配给订阅范围内的用户。

传播防火墙规则更改可能需要一些时间。 更改防火墙设置后，请等待几分钟，然后验证更改。

移动到较新版本的 ACR API。 可 在此处找到受支持的版本列表。

如果通过 SDK 使用 API，请通过更新到较新版本的 SDK 移动到较新的 API 版本。 可在 此处找到 SDK 及其最新版本的列表。

以下 API 版本已弃用，并将在下面列出的“支持结束日期”之前继续提供支持：

ACR 支持 Docker 注册表 HTTP API V2。 可通过 https://<your registry login server>/v2/ 访问 API。 示例： https://mycontainerregistry.azurecr.cn/v2/

对于 Bash，请运行以下命令：

az acr manifest list-metadata --name myRepository --registry myRegistry --query "[?tags[0]==null].digest" --output tsv  | xargs -I% az acr repository delete --name myRegistry --image myRepository@%

对于 PowerShell，请运行以下命令：

az acr manifest list-metadata --name myRepository --repository myRegistry --query "[?tags[0]==null].digest" --output tsv | %{ az acr repository delete --name myRegistry --image myRepository@$_ }

有关详细信息，请参阅 删除容器映像 在 Azure 容器注册表中。

当基础层仍被其他容器映像引用时，会出现这种情况。 如果删除没有引用的镜像，注册表使用情况应在几分钟内更新。

使用以下 docker 文件创建具有 1 GB 层的映像。 此步骤可确保映像具有不与注册表中的任何其他映像共享的层。

FROM alpine
RUN dd if=/dev/urandom of=1GB.bin  bs=32M  count=32
RUN ls -lh 1GB.bin

使用 docker CLI 生成映像并将其推送到注册表：

docker build -t myregistry.azurecr.cn/1gb:latest .
docker push myregistry.azurecr.cn/1gb:latest

应该能够看到存储使用量在Azure门户中有所增加，或者可以使用Azure CLI查询使用情况：

az acr show-usage -n myregistry

接下来，使用Azure CLI或在Azure门户中删除映像，等待几分钟，然后检查更新的使用情况。

az acr repository delete -n myregistry --image 1gb

需要通过装载Docker套接字来运行Azure CLI容器：

docker run -it -v /var/run/docker.sock:/var/run/docker.sock azuresdk/azure-cli-python:dev

在容器中安装 docker：

apk --update add docker

然后对注册表进行身份验证：

az acr login -n MyRegistry

目前，可以在 Azure Container Registry 中使用受信任的映像和 Docker 内容信任 （DCT）。 但是，Azure Container Registry将于 2028 年 3 月 31 日停用 DCT。

作为 DCT 的替代方法，Azure基于 Notary Project 提供签名和验证解决方案。 我们鼓励你尽快 从 DCT 过渡到公证项目 。

在 2026 年 5 月 31 日之前，可以在尚未启用它的新容器注册表或注册表上启用 Docker 内容信任。 有关详细信息，请参阅在 Azure 容器注册表中使用 Docker 内容信任管理签名映像。

指纹文件位于 ~/.docker/trust/private/tuf/myregistry.azurecr.cn/myrepository/metadata：

• 所有角色（委托角色除外）的公钥和证书都存储在 root.json 中。
• 委托角色的公钥和证书将存储在其父角色的 JSON 文件（例如，targets.json 角色的 targets/releases）中。

在 Docker 和 Notary 客户端完成总体 TUF 验证之后，再验证公钥和证书。

ACR 支持Microsoft Entra基于角色的访问控制（RBAC）和内置角色，这些角色提供不同级别的Azure基于 Entra 的权限，例如授予映像推送或拉取权限，而无需向整个注册表授予权限。

可以选择使用 Microsoft Entra 基于属性的访问控制 （ABAC） 来管理基于 Microsoft Entra 的存储库权限并将角色分配范围限定到特定存储库。

映像隔离目前是 ACR 的预览版功能。 可以启用注册表的隔离模式，以便只有通过安全扫描的映像才能对普通用户可见。 有关详细信息，请参阅 ACR GitHub 存储库。

可以使用Azure CLI配置匿名拉取访问。 有关详细信息，请参阅 未经身份验证的匿名拉取访问。

清单中的不可分发层包含可从中获取内容的 URL 参数。 启用不可分发层推送的一些可能用例适用于网络受限注册表、访问受限的气隙注册表或没有 Internet 连接的注册表。

例如，如果设置了网络安全组（NSG）规则，使得 VM 只能从 Azure 容器注册表拉取映像，则拉取外部或非分发层时，Docker 可能会遇到故障。 例如，Windows Server Core 镜像在其清单中包含对 Azure 容器注册表的外部层引用，在这种情况下将无法拉取。

要启用不可分发层的推送，请执行以下操作：

1. 编辑 daemon.json 文件，该文件位于 Linux 主机上的 /etc/docker/ 和 Windows Server 上的 C:\ProgramData\docker\config\daemon.json。 假设文件之前为空，请添加以下内容：

   {
     "allow-nondistributable-artifacts": ["myregistry.azurecr.cn"]
   }
   

   注意

   值是注册表地址的数组，各个地址之间以逗号分隔。

2. 保存并退出该文件。

3. 重启 Docker。

当您将镜像推送到列表中的注册表时，它们的不可分发层将被推送到注册表。

可以使用 az acr check-health 排查常见环境和注册表问题，请参阅 检查Azure容器注册表的运行状况。

可能会出现错误 net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)。 若要解决此问题，请执行下列操作：

• 首先，请等待几分钟，然后重试。 此问题可能是暂时性的。
• 如果 docker pull 连续失败，请尝试重启 Docker 守护程序。
• 如果在重启 Docker 守护程序后继续看到此问题，则可能是因为网络连接问题。 运行以下命令以测试终结点连接：

az acr check-health -n myRegistry

• 始终应该对所有 Docker 客户端操作使用重试机制。

这通常是由于计算机处于慢速网络。 检查网络下载速度。 若要提高速度，请考虑在注册表所在的同一区域中使用Azure虚拟机（VM），以提高网络速度。

首先，请确保使用全小写格式的服务器 URL，例如docker push myregistry.azurecr.cn/myimage:latest，即使注册资源名称是大写或大小写混合，例如myRegistry。

Red Hat 版本的 Docker 守护程序在默认启用 --signature-verification 时，也可能发生此错误。 可以运行以下命令来检查 Red Hat Enterprise Linux (RHEL) 或 Fedora 的 Docker 守护程序选项：

grep OPTIONS /etc/sysconfig/docker

例如，Fedora 28 服务器使用以下 Docker 守护程序选项：

OPTIONS='--selinux-enabled --log-driver=journald --live-restore'

如果缺少 --signature-verification=false，docker pull 将会失败并出现如下所示的错误：

Trying to pull repository myregistry.azurecr.cn/myimage ...
unauthorized: authentication required

若要解决该错误：

1. 将选项 --signature-verification=false 添加到 Docker 守护程序配置文件 /etc/sysconfig/docker。 例如：

   OPTIONS='--selinux-enabled --log-driver=journald --live-restore --signature-verification=false'

2. 运行以下命令重启 Docker 守护程序服务：

   sudo systemctl restart docker.service
   

运行 --signature-verification 可以找到 man dockerd 的详细信息。

使用 dockerd 选项启动 debug。 首先创建 Docker 守护程序配置文件 (/etc/docker/daemon.json)（如果不存在），并添加 debug 选项：

{    
    "debug": true    
}

然后重启守护程序。

sudo service docker restart

可以在 Docker 文档中找到详细信息。

• 日志可能在不同的位置生成，具体取决于所用的系统。 有关具体信息，请参阅 Docker 文档。

• 对于 docker for Windows，日志在 %LOCALAPPDATA%/docker/下生成。 但是，若要访问完整的守护程序日志，可能需要运行以下附加命令：

  docker run --privileged -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /usr/local/bin/docker:/usr/local/bin/docker alpine sh
  
  docker run --net=host --ipc=host --uts=host --pid=host -it --security-opt=seccomp=unconfined --privileged --rm -v /:/host alpine /bin/sh
  chroot /host
  

  现在，可以访问运行 dockerd 的 VM 的所有文件。 日志位于 /var/log/docker.log。

Microsoft Entra角色分配通常很快发生，但有时可能会出现延迟。 你可能还会在 ACR 令牌服务器上遇到最多 10 分钟的权限延迟。 若要缓解、运行 docker logout、等待一分钟，然后使用相同的用户凭据再次进行身份验证：

docker logout myregistry.azurecr.cn
docker login myregistry.azurecr.cn

目前，ACR 不支持用户删除家庭复制。 相反，可以在模板中包含主复制创建，但通过添加以下内容 "condition": false跳过其创建：

{
    "name": "[concat(parameters('acrName'), '/', parameters('location'))]",
    "condition": false,
    "type": "Microsoft.ContainerRegistry/registries/replications",
    "apiVersion": "2025-04-01",
    "location": "[parameters('location')]",
    "properties": {},
    "dependsOn": [
        "[concat('Microsoft.ContainerRegistry/registries/', parameters('acrName'))]"
     ]
},

你可能会遇到 InvalidAuthenticationInfo 错误，尤其是结合选项 curl（-L，跟踪重定向）使用 --location 工具时。 例如，可以使用 curl 结合 -L 选项和基本身份验证来提取 Blob。

curl -L -H "Authorization: basic $credential" https://$registry.azurecr.cn/v2/$repository/blobs/$digest

这可能会导致以下响应：

<?xml version="1.0" encoding="utf-8"?>
<Error><Code>InvalidAuthenticationInfo</Code><Message>Authentication information is not given in the correct format. Check the value of Authorization header.
RequestId:00000000-0000-0000-0000-000000000000
Time:2023-01-01T00:00:00.0000000Z</Message></Error>

根本原因是某些 curl 实现使用原始请求中的标头跟踪重定向。

若要解决此问题，请在不使用标头的情况下手动跟踪重定向。 使用 -D - 的 curl 选项输出响应标头，然后提取 Location 标头：

REDIRECT_URL=$(curl -s -D - -H "Authorization: basic $credential" https://$registry.azurecr.cn/v2/$repository/blobs/$digest | grep "^Location: " | cut -d " " -f2 | tr -d '\r')
curl $REDIRECT_URL

发送提取请求失败的原因有多种，例如：

• 缺少网络连接
• 防火墙
• 使用公共网络上的门户访问一个仅允许专用访问的注册表
• 广告阻止程序
• 域名服务器 （DNS） 错误

请联系您的网络管理员或检查您的网络配置和连接。 尝试运行 az acr check-health -n yourRegistry 以检查环境是否能够连接到注册表。 还可以尝试在浏览器中使用隐身会话或专用会话，以避免任何过时的浏览器缓存或 Cookie。

下面是一些可能不允许进行操作的情况：

• 不再支持经典注册表。 使用 az acr update 或 Azure 门户升级到受支持的 服务层。
• 映像或存储库可能已锁定，因此无法进行删除或更新。 可以使用 az acr repository show 命令查看当前属性。
• 如果映像位于 quarantine，则禁止执行某些操作。
• 注册表可能已达到其存储限制。

如果在存储库作中指定存储库名称时看到“不支持的存储库格式”、“格式无效”或“请求的数据不存在”等错误，请检查名称的拼写和大小写。 有效的存储库名称只能包含小写字母数字字符、句点、短划线、下划线和正斜杠。

首先，在 Fiddler 中启用解密 HTTPS ，并允许 Docker 通过 Docker UI 使用代理 。 请确保在完成后恢复，因为 Docker 在启用代理且未运行 Fiddler 的情况下无法正常工作。

对于Windows容器，请将 Docker 代理配置为 127.0.0.1：8888。

对于 Linux 容器，请查找 Docker vm 虚拟交换机的 IP：

(Get-NetIPAddress -InterfaceAlias "*Docker*" -AddressFamily IPv4).IPAddress

然后，将 Docker 代理配置为输出上一个命令和端口 8888（例如 10.0.75.1：8888）。

以下命令可取消指定的注册表中所有正在运行的任务。

az acr task list-runs -r $myregistry --run-status Running --query '[].runId' -o tsv \
| xargs -I% az acr task cancel-run -r $myregistry --run-id %

如果将本地源文件夹传递到 az acr build 命令，则默认会从上传的包中排除 .git 文件夹。 可以使用以下设置创建 .dockerignore 文件：

!.git/**

此设置告知命令还原上传的包下 .git 的所有文件。 它还适用于 az acr run 命令。

我们目前不支持 GitLab 用作源代码触发器。

你可能会看到一个错误，指出未配置任何访问权限，因此在 ACR 任务中使用 az login --identity 时找不到任何订阅。 此错误通常是暂时性的，发生在托管身份的角色分配尚未传播时。 等待几秒钟，然后再重试。

可以在以下链接中找到示例 CI/CD 与 ACR 任务的集成：

• CircleCI
• GitHub Actions

后续步骤

• 了解更多关于 Azure 容器注册表的信息。