常見問題 - Azure Container Registry

本文說明 Azure Container Registry 的常見問題與已知問題。

有關登錄檔疑難排解指南，請參閱：

• 排除登錄系統的登入、驗證和授權問題
• 疑難排解登錄檔網路問題
• 疑難排解登錄檔效能

資源管理

我可以使用 Azure Resource Manager (ARM) 範本建立 Azure Container Registry (ACR) 嗎？

是。 以下是一個範本，可用於建立登錄檔。

是否有針對 ACR 中映像檔的安全性弱點掃描？

是。 請參閱 Microsoft Defender for Cloud、Twistlock 和 Aqua 的文件。

如何將 Kubernetes 設定為搭配 Azure Container Registry？

請參閱 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'), '2017-10-01').passwords[0].value]"
}

若要取得第二組密碼：

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

即使複本已成功透過 Azure CLI 或 Azure PowerShell 刪除，但在入口網站中刪除複寫時仍出現 Forbidden 狀態

當使用者在登錄檔中擁有 Container Registry Contributor and Data Access Configuration Administrator 角色 (允許透過 Azure CLI 刪除複本)，但在訂閱上缺乏讀取者權限時，就會發生此錯誤。 透過入口網站刪除複本需要訂用帳戶的讀者存取權。 若要解決此問題，請在訂用帳戶上為該使用者指派讀者權限：

az role assignment create --role "Reader" --assignee user@contoso.com --scope /subscriptions/<subscription_id> 

防火牆規則已成功更新但未生效

防火牆規則變更需要一些時間才能傳播。 變更防火牆設定後，請等待數分鐘再驗證變更。

登錄檔作業

如何存取 Docker Registry HTTP API V2？

ACR 支援 Docker Registry HTTP API V2。 API 可在 https://<your registry login server>/v2/ 存取。 範例： https://mycontainerregistry.azurecr.io/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@$_ }

附註

您可以在刪除命令中加入 -y 以略過確認。

如需詳細資訊，請參閱在 Azure Container Registry 中刪除容器映像。

為什麼在刪除映像檔後，登錄檔的配額使用量不會減少？

若基礎層仍被其他容器映像參考，就會發生此情況。 如果您刪除沒有任何參考的映像，登錄檔使用量會在數分鐘內更新。

如何驗證儲存配額的變更？

使用以下 docker 檔案建立一個具有 1GB 層的映像檔。 此步驟確保該映像檔具有未與登錄檔中任何其他映像共享的層。

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.io/1gb:latest .
docker push myregistry.azurecr.io/1gb:latest

您應該可以在 Azure 入口網站中看到儲存使用量增加，或者可以使用 CLI 查詢使用量。

az acr show-usage -n myregistry

使用 Azure CLI 或入口網站刪除映像檔，並在幾分鐘後檢查更新後的使用量。

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

在容器中執行 CLI 時，如何驗證我的登錄檔？

您需要透過掛載 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

如何啟用 TLS 1.2？

使用任何近期的 docker 用戶端 (版本 18.03.0 及以上) 啟用 TLS 1.2。

重要事項

自 2020 年 1 月 13 日起，Azure 容器登錄檔將要求所有來自伺服器和應用程式的安全連線使用 TLS 1.2。 TLS 1.0 和 1.1 的支援已淘汰。

Azure Container Registry 是否支援內容信任？

是的，您可以在 Azure 容器登錄檔中使用受信任的映像檔，搭配 Docker 內容信任。 詳情請參閱 Azure 容器登錄檔中的內容信任。

指紋檔案位於哪裡？

位於 ~/.docker/trust/tuf/myregistry.azurecr.io/myrepository/metadata 下：

• 所有角色的公開金鑰和憑證 (委派角色除外) 存放於 root.json。
• 委派角色的公開金鑰和憑證則存放於其父角色的 JSON 檔案中 (例如 targets/releases 角色的 targets.json)。

您應在 Docker 和 Notary 用戶端完成整體 TUF 驗證後，再驗證這些公開金鑰和憑證。

如何在不授予管理登錄檔資源權限的情況下，授予提取或推送映像檔的存取權？

ACR 支援 Microsoft Entra 角色導向存取控制（RBAC）及內建角色 ，提供不同層級的 Microsoft Entra 權限，例如授予影像推送或拉取權限，但不授予整個登錄檔權限。

您也可以選擇使用 Microsoft Entra 屬性型存取控制 (ABAC) 來管理 Microsoft Entra 型存放庫權限，並將角色指派範圍限制於特定存放庫。

如何為登錄檔啟用自動映像隔離？

映像隔離目前是 ACR 的預覽功能。 可以啟用登錄檔的隔離模式，使只有通過安全掃描的映像對一般使用者可見。 詳情請參閱 ACR GitHub 存放庫。

如何啟用匿名提取存取？

更多資訊請參閱使您的登錄檔內容公開可用。

如何將不可分發層推送到登錄檔？

在清單中的不可分發層包含一個 URL 參數，可從中取得內容。 啟用不可分發層推送的一些可能使用情境包括網路受限的登錄檔、有限訪問的隔離登錄檔，或無網際網路連線的登錄檔。

例如，如果你設定了網路安全群組（NSG）規則，讓虛擬機只能從你的 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.io"]
   }
   

   附註

   該值為登錄檔地址的陣列，以逗號分隔。

2. 儲存並退出檔案。

3. 重新啟動 Docker。

當您將映像推送到清單中的登錄檔時，其不可分發層也會被推送到該登錄檔。

警告

不可分發的成品通常對其分發和共享方式有限制。 此功能僅用於將成品推送到私人登錄檔。 請確保您遵守所有涉及不可分發成品再分發的條款。

診斷與健康檢查

使用「az acr check-health」檢查健康狀態。

如要疑難排解常見的環境和登錄檔問題，請參閱檢查 Azure 容器登錄檔的健康狀態。

Docker 提取失敗，錯誤訊息：net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

• 如果此錯誤是暫時性問題，則重試可能會成功。
• 如果 docker pull 持續失敗，則可能是 Docker 精靈的問題。 通常可透過重新啟動 Docker 精靈緩解問題。
• 如果重新啟動 Docker 精靈後仍持續發生此問題，可能是機器的網路連線有問題。 要檢查機器的一般網路是否健康，請執行以下命令測試端點連線。 包含此連線檢查命令的最低 az acr 版本為 2.2.9。 若您使用舊版 Azure CLI，請升級。

az acr check-health -n myRegistry

• 您應始終在所有 Docker 用戶端操作中設置重試機制。

Docker 提取速度緩慢

使用速度測試工具測試機器網路下載速度。 如果機器網路較慢，考慮使用與登錄檔位於相同區域的 Azure 虛擬機器 (VM) 以提升網路速度。

Docker 推送速度緩慢

使用速度工具測試您的機器網路上傳速度。 如果機器網路速度緩慢，請考慮使用與您的登錄檔位於相同區域的 Azure VM 以改善網路速度。

Docker 推送成功但 docker pull 失敗並出現錯誤：unauthorized: authentication required

此錯誤可能發生在 Red Hat 版本的 Docker 精靈，其中 --signature-verification 預設為啟用。 您可以執行下列命令來檢查 Red Hat Enterprise Linux (RHEL) 或 Fedora 的 Docker 精靈選項：

grep OPTIONS /etc/sysconfig/docker

例如，Fedora 28 Server 具有以下 Docker 精靈選項：

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

若缺少 --signature-verification=false，則 docker pull 會失敗並出現類似以下的錯誤：

Trying to pull repository myregistry.azurecr.io/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
   

您可以執行 man dockerd 來查看 --signature-verification 的詳細資訊。

az acr login 成功但 docker 失敗並出現錯誤：unauthorized: authentication required

請務必使用全小寫的伺服器 URL，例如 docker push myregistry.azurecr.io/myimage:latest，即使登錄檔資源名稱是大寫或混合大小寫，例如 myRegistry。

啟用並取得 Docker 精靈的偵錯記錄

使用 debug 選項啟動 dockerd。 首先，如果 Docker 精靈組態檔 (/etc/docker/daemon.json) 不存在，請建立，並新增 debug 選項：

{    
    "debug": true    
}

接著，重新啟動精靈。

sudo service docker restart

詳細資訊請參閱 Docker 文件。

• 記錄可能會產生在不同位置，這取決於您的系統。 例如，Ubuntu 14.04 的位置是 /var/log/upstart/docker.log。
  詳細資訊請參閱 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，然後在 1 分鐘後使用相同使用者重新驗證：

  docker logout myregistry.azurecr.io
  docker login myregistry.azurecr.io
  

目前 ACR 不支援使用者刪除主區域複寫。 解決方法是在範本中包含主區域複寫建立，但透過加入 "condition": false 來跳過其建立，如下所示：

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

在直接 REST API 呼叫中，驗證資訊格式不正確

您可能會遇到 InvalidAuthenticationInfo 錯誤，尤其是在使用帶有 -L 或 --location 選項 (以跟隨重新導向) 的 curl 工具時。 例如，使用帶有 -L 選項及基本驗證的 curl 擷取 Blob：

curl -L -H "Authorization: basic $credential" https://$registry.azurecr.io/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:2019-01-01T00:00:00.0000000Z</Message></Error>

根本原因是某些 curl 實作會使用原始請求的標頭跟隨重新導向。

要解決此問題，您需要手動跟隨重新導向，而不使用原始標頭。 使用 curl 的 -D - 選項列印回應標頭，然後擷取 Location 標頭：

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

為什麼 Azure 入口網站無法列出我所有的存放庫或標籤？

如果您使用 Microsoft Edge 或 IE 瀏覽器，最多只能看到 100 個存放庫或標籤。 如果您的登錄檔有超過 100 個存放庫或標籤，我們建議您使用 Firefox 或 Chrome 瀏覽器來完整列出。

為什麼 Azure 入口網站無法擷取存放庫或標籤？

瀏覽器可能無法將擷取存放庫或標籤的請求傳送到伺服器。 可能原因有多種，例如：

• 網路連線不足
• 防火牆
• 從允許僅私人存取的登錄檔，使用公共網路存取入口網站
• 廣告封鎖程式
• 網域名稱伺服器 (DNS) 錯誤

請聯絡您的網路管理員或檢查網路組態與連線狀態。 嘗試使用您的 Azure CLI 執行 az acr check-health -n yourRegistry，檢查您的環境是否能連線至容器登錄檔。 此外，您也可以嘗試在瀏覽器中使用隱身或私人模式，以避免任何過期的瀏覽器快取或 Cookie。

為什麼我的提取或推送請求會因不允許的操作而失敗？

以下是可能被禁止操作的一些情況：

• 已不再支援傳統登錄檔。 使用 az acr update 或 Azure 入口網站升級至受支援的服務層級。
• 影像或存放庫可能遭到鎖定，因此無法刪除或更新。 您可以使用 az acr repository show 命令查看目前屬性。
• 如果影像處於隔離狀態，某些操作將被禁止。 了解更多關於隔離的資訊。
• 您的登錄檔可能已達到其儲存體限制。

存放庫格式無效或不支援

如果在指定存放庫名稱進行存放庫操作時看到「不支援的存放庫格式」、「格式無效」或「所請求的資料不存在」 等錯誤，請檢查名稱的拼寫與大小寫。 有效的存放庫名稱僅能包含小寫英數字、句點、連字號、底線以及正斜線。

如何在 Windows 上收集 http 追蹤？

先決條件

• 啟用在 Fiddler 中解密 HTTPS
• 透過 Docker UI 啟用 Docker 以使用 Proxy。
• 完成後務必還原設定。 啟用此功能且 Fiddler 未運行時，Docker 將無法運作。

Windows 容器

將 Docker Proxy 設定為 127.0.0.1:8888

Linux 容器

查找 Docker vm 虛擬交換器的 IP：

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

將 Docker Proxy 設定為前一個命令的輸出與連接埠 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' 資料夾？

如果您將本機來源資料夾傳遞給 az acr build 命令，.git 資料夾預設會從上傳的封包中排除。 您可以建立一個 .dockerignore 檔案，內容如下設定。 它告訴命令在上傳的封包中恢復 .git 下的所有檔案。

!.git/**

此設定也適用於 az acr run 命令。

任務是否支援 GitLab 作為來源觸發程序？

我們目前不支援 GitLab 作為來源觸發程序。

任務支援哪些 git 存放庫管理服務？

Git 服務	來源情境	手動建置	透過提交觸發程序自動建置
GitHub	https://github.com/user/myapp-repo.git#mybranch:myfolder	是的	是的
Azure Repos	https://dev.azure.com/user/myproject/_git/myapp-repo#mybranch:myfolder	是的	是的
GitLab	https://gitlab.com/user/myapp-repo.git#mybranch:myfolder	是的	否
BitBucket	https://user@bitbucket.org/user/mayapp-repo.git#mybranch:myfolder	是的	否

執行錯誤訊息疑難排解

錯誤訊息	疑難排解指南
VM 沒有設定存取權，因此未找到任何訂閱	如果您在 ACR 工作中使用 az login --identity，可能會發生此情況。 此錯誤是暫時性的，發生在管理身份的角色分配尚未被傳承時。 等待幾秒後再重試通常可行。

CI/CD 整合

• CircleCI
• GitHub Actions（GitHub 行動）

如果 Agent 集區建立因逾時問題失敗，該如何解決？

將正確的防火牆規則設定到現有的網路安全群組或使用者定義路由。 設定完成後，等待幾分鐘以讓防火牆規則生效。

啟用 Azure 內建的 ACR 政策，怎麼會阻止啟用管理員憑證？

以下 Azure 內建政策設定為相應的政策狀態時，會阻止使用者在其登錄檔啟用管理員使用者。

Azure 內建原則	原則狀態	管理員狀態
設定容器登錄檔以停用本地管理員帳號。	修改	停用
容器登錄檔應停用本地管理員帳號。	拒絕	停用
容器登錄檔應停用本地管理員帳號。	稽核	不符合規範

後續步驟

• 深入了解 Azure Container Registry。

本文說明 Azure Container Registry 的常見問題與已知問題。

有關登錄檔疑難排解指南，請參閱：

• 排除登錄系統的登入、驗證和授權問題
• 疑難排解登錄檔網路問題
• 疑難排解登錄檔效能

是。 以下是一個範本，可用於建立登錄檔。

是。 請參閱 Microsoft Defender for Cloud、Twistlock 和 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

重要事項

系統管理使用者帳戶是為單一使用者存取登錄檔而設計，主要用於測試目的。 我們不建議將系統管理帳戶的認證與多位使用者共用。 建議對使用者使用個別身分，並在無頭情境中使用服務主體。 請參閱驗證概觀。

在取得系統管理認證之前，請確認登錄檔的系統管理使用者已啟用。

若要取得第一組密碼：

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

若要取得第二組密碼：

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

當使用者在登錄檔中擁有 Container Registry Contributor and Data Access Configuration Administrator 角色 (允許透過 Azure CLI 刪除複本)，但在訂閱上缺乏讀取者權限時，就會發生此錯誤。 透過入口網站刪除複本需要訂用帳戶的讀者存取權。 若要解決此問題，請在訂用帳戶上為該使用者指派讀者權限：

az role assignment create --role "Reader" --assignee user@contoso.com --scope /subscriptions/<subscription_id> 

防火牆規則變更需要一些時間才能傳播。 變更防火牆設定後，請等待數分鐘再驗證變更。

ACR 支援 Docker Registry HTTP API V2。 API 可在 https://<your registry login server>/v2/ 存取。 範例： https://mycontainerregistry.azurecr.io/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@$_ }

附註

您可以在刪除命令中加入 -y 以略過確認。

如需詳細資訊，請參閱在 Azure Container Registry 中刪除容器映像。

若基礎層仍被其他容器映像參考，就會發生此情況。 如果您刪除沒有任何參考的映像，登錄檔使用量會在數分鐘內更新。

使用以下 docker 檔案建立一個具有 1GB 層的映像檔。 此步驟確保該映像檔具有未與登錄檔中任何其他映像共享的層。

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.io/1gb:latest .
docker push myregistry.azurecr.io/1gb:latest

您應該可以在 Azure 入口網站中看到儲存使用量增加，或者可以使用 CLI 查詢使用量。

az acr show-usage -n myregistry

使用 Azure CLI 或入口網站刪除映像檔，並在幾分鐘後檢查更新後的使用量。

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

使用任何近期的 docker 用戶端 (版本 18.03.0 及以上) 啟用 TLS 1.2。

重要事項

自 2020 年 1 月 13 日起，Azure 容器登錄檔將要求所有來自伺服器和應用程式的安全連線使用 TLS 1.2。 TLS 1.0 和 1.1 的支援已淘汰。

是的，您可以在 Azure 容器登錄檔中使用受信任的映像檔，搭配 Docker 內容信任。 詳情請參閱 Azure 容器登錄檔中的內容信任。

指紋檔案位於哪裡？

位於 ~/.docker/trust/tuf/myregistry.azurecr.io/myrepository/metadata 下：

• 所有角色的公開金鑰和憑證 (委派角色除外) 存放於 root.json。
• 委派角色的公開金鑰和憑證則存放於其父角色的 JSON 檔案中 (例如 targets/releases 角色的 targets.json)。

您應在 Docker 和 Notary 用戶端完成整體 TUF 驗證後，再驗證這些公開金鑰和憑證。

ACR 支援 Microsoft Entra 角色導向存取控制（RBAC）及內建角色 ，提供不同層級的 Microsoft Entra 權限，例如授予影像推送或拉取權限，但不授予整個登錄檔權限。

您也可以選擇使用 Microsoft Entra 屬性型存取控制 (ABAC) 來管理 Microsoft Entra 型存放庫權限，並將角色指派範圍限制於特定存放庫。

映像隔離目前是 ACR 的預覽功能。 可以啟用登錄檔的隔離模式，使只有通過安全掃描的映像對一般使用者可見。 詳情請參閱 ACR GitHub 存放庫。

更多資訊請參閱使您的登錄檔內容公開可用。

在清單中的不可分發層包含一個 URL 參數，可從中取得內容。 啟用不可分發層推送的一些可能使用情境包括網路受限的登錄檔、有限訪問的隔離登錄檔，或無網際網路連線的登錄檔。

例如，如果你設定了網路安全群組（NSG）規則，讓虛擬機只能從你的 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.io"]
   }
   

   附註

   該值為登錄檔地址的陣列，以逗號分隔。

2. 儲存並退出檔案。

3. 重新啟動 Docker。

當您將映像推送到清單中的登錄檔時，其不可分發層也會被推送到該登錄檔。

警告

不可分發的成品通常對其分發和共享方式有限制。 此功能僅用於將成品推送到私人登錄檔。 請確保您遵守所有涉及不可分發成品再分發的條款。

如要疑難排解常見的環境和登錄檔問題，請參閱檢查 Azure 容器登錄檔的健康狀態。

• 如果此錯誤是暫時性問題，則重試可能會成功。
• 如果 docker pull 持續失敗，則可能是 Docker 精靈的問題。 通常可透過重新啟動 Docker 精靈緩解問題。
• 如果重新啟動 Docker 精靈後仍持續發生此問題，可能是機器的網路連線有問題。 要檢查機器的一般網路是否健康，請執行以下命令測試端點連線。 包含此連線檢查命令的最低 az acr 版本為 2.2.9。 若您使用舊版 Azure CLI，請升級。

az acr check-health -n myRegistry

• 您應始終在所有 Docker 用戶端操作中設置重試機制。

使用速度測試工具測試機器網路下載速度。 如果機器網路較慢，考慮使用與登錄檔位於相同區域的 Azure 虛擬機器 (VM) 以提升網路速度。

使用速度工具測試您的機器網路上傳速度。 如果機器網路速度緩慢，請考慮使用與您的登錄檔位於相同區域的 Azure VM 以改善網路速度。

此錯誤可能發生在 Red Hat 版本的 Docker 精靈，其中 --signature-verification 預設為啟用。 您可以執行下列命令來檢查 Red Hat Enterprise Linux (RHEL) 或 Fedora 的 Docker 精靈選項：

grep OPTIONS /etc/sysconfig/docker

例如，Fedora 28 Server 具有以下 Docker 精靈選項：

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

若缺少 --signature-verification=false，則 docker pull 會失敗並出現類似以下的錯誤：

Trying to pull repository myregistry.azurecr.io/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
   

您可以執行 man dockerd 來查看 --signature-verification 的詳細資訊。

請務必使用全小寫的伺服器 URL，例如 docker push myregistry.azurecr.io/myimage:latest，即使登錄檔資源名稱是大寫或混合大小寫，例如 myRegistry。

使用 debug 選項啟動 dockerd。 首先，如果 Docker 精靈組態檔 (/etc/docker/daemon.json) 不存在，請建立，並新增 debug 選項：

{    
    "debug": true    
}

接著，重新啟動精靈。

sudo service docker restart

詳細資訊請參閱 Docker 文件。

• 記錄可能會產生在不同位置，這取決於您的系統。 例如，Ubuntu 14.04 的位置是 /var/log/upstart/docker.log。
  詳細資訊請參閱 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，然後在 1 分鐘後使用相同使用者重新驗證：

  docker logout myregistry.azurecr.io
  docker login myregistry.azurecr.io
  

目前 ACR 不支援使用者刪除主區域複寫。 解決方法是在範本中包含主區域複寫建立，但透過加入 "condition": false 來跳過其建立，如下所示：

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

您可能會遇到 InvalidAuthenticationInfo 錯誤，尤其是在使用帶有 -L 或 --location 選項 (以跟隨重新導向) 的 curl 工具時。 例如，使用帶有 -L 選項及基本驗證的 curl 擷取 Blob：

curl -L -H "Authorization: basic $credential" https://$registry.azurecr.io/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:2019-01-01T00:00:00.0000000Z</Message></Error>

根本原因是某些 curl 實作會使用原始請求的標頭跟隨重新導向。

要解決此問題，您需要手動跟隨重新導向，而不使用原始標頭。 使用 curl 的 -D - 選項列印回應標頭，然後擷取 Location 標頭：

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

如果您使用 Microsoft Edge 或 IE 瀏覽器，最多只能看到 100 個存放庫或標籤。 如果您的登錄檔有超過 100 個存放庫或標籤，我們建議您使用 Firefox 或 Chrome 瀏覽器來完整列出。

瀏覽器可能無法將擷取存放庫或標籤的請求傳送到伺服器。 可能原因有多種，例如：

• 網路連線不足
• 防火牆
• 從允許僅私人存取的登錄檔，使用公共網路存取入口網站
• 廣告封鎖程式
• 網域名稱伺服器 (DNS) 錯誤

請聯絡您的網路管理員或檢查網路組態與連線狀態。 嘗試使用您的 Azure CLI 執行 az acr check-health -n yourRegistry，檢查您的環境是否能連線至容器登錄檔。 此外，您也可以嘗試在瀏覽器中使用隱身或私人模式，以避免任何過期的瀏覽器快取或 Cookie。

以下是可能被禁止操作的一些情況：

• 已不再支援傳統登錄檔。 使用 az acr update 或 Azure 入口網站升級至受支援的服務層級。
• 影像或存放庫可能遭到鎖定，因此無法刪除或更新。 您可以使用 az acr repository show 命令查看目前屬性。
• 如果影像處於隔離狀態，某些操作將被禁止。 了解更多關於隔離的資訊。
• 您的登錄檔可能已達到其儲存體限制。

如果在指定存放庫名稱進行存放庫操作時看到「不支援的存放庫格式」、「格式無效」或「所請求的資料不存在」 等錯誤，請檢查名稱的拼寫與大小寫。 有效的存放庫名稱僅能包含小寫英數字、句點、連字號、底線以及正斜線。

先決條件

• 啟用在 Fiddler 中解密 HTTPS
• 透過 Docker UI 啟用 Docker 以使用 Proxy。
• 完成後務必還原設定。 啟用此功能且 Fiddler 未運行時，Docker 將無法運作。

Windows 容器

將 Docker Proxy 設定為 127.0.0.1:8888

Linux 容器

查找 Docker vm 虛擬交換器的 IP：

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

將 Docker Proxy 設定為前一個命令的輸出與連接埠 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 作為來源觸發程序。

Git 服務	來源情境	手動建置	透過提交觸發程序自動建置
GitHub	https://github.com/user/myapp-repo.git#mybranch:myfolder	是的	是的
Azure Repos	https://dev.azure.com/user/myproject/_git/myapp-repo#mybranch:myfolder	是的	是的
GitLab	https://gitlab.com/user/myapp-repo.git#mybranch:myfolder	是的	否
BitBucket	https://user@bitbucket.org/user/mayapp-repo.git#mybranch:myfolder	是的	否

執行錯誤訊息疑難排解

錯誤訊息	疑難排解指南
VM 沒有設定存取權，因此未找到任何訂閱	如果您在 ACR 工作中使用 az login --identity，可能會發生此情況。 此錯誤是暫時性的，發生在管理身份的角色分配尚未被傳承時。 等待幾秒後再重試通常可行。

CI/CD 整合

• CircleCI
• GitHub Actions（GitHub 行動）

將正確的防火牆規則設定到現有的網路安全群組或使用者定義路由。 設定完成後，等待幾分鐘以讓防火牆規則生效。

以下 Azure 內建政策設定為相應的政策狀態時，會阻止使用者在其登錄檔啟用管理員使用者。

Azure 內建原則	原則狀態	管理員狀態
設定容器登錄檔以停用本地管理員帳號。	修改	停用
容器登錄檔應停用本地管理員帳號。	拒絕	停用
容器登錄檔應停用本地管理員帳號。	稽核	不符合規範

後續步驟

• 深入了解 Azure Container Registry。