Azure DevOps Docker服务连接配置：ACR镜像推送失败求助

问题背景 #

已通过以下脚本创建拥有acrpush权限的服务主体（SP），用于Azure DevOps的Docker类型服务连接（仅用用户名/密码登录）：

#!/bin/bash
ACR_NAME=MYACRNAME
SERVICE_PRINCIPAL_NAME=MYACRNAME_PUSH

ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)

PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpush --query "password" --output tsv)
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)

echo "Service principal ID: $USER_NAME"
echo "Service principal password: $PASSWORD"

配置服务连接后，使用以下Azure DevOps流水线模板执行时，登录步骤成功，但推送镜像时出现未授权错误：

parameters:
- name: docker
  type: object
  default:
    repository: ""
    tag: ""
    registry: ""

steps:
- task: Docker@2
  displayName: Registry Login
  continueOnError: false
  inputs:
    command: login
    containerRegistry: ${{ parameters.docker.registry }}

- task: Docker@2
  displayName: Push Image
  continueOnError: false
  inputs:
    command: push
    repository: ${{ parameters.docker.repository }}
    containerRegistry: ${{ parameters.docker.registry }}
    tags: ${{ parameters.docker.tag }}

错误信息：

unauthorized: {"errors":[{"code":"UNAUTHORIZED","message":"authentication required, visit https://aka.ms/acr/authorization for more information."}]} 

排查与解决方案 #

1. 验证服务主体的权限配置 #

• 核对创建SP时使用的ACR_REGISTRY_ID是否为目标ACR的完整资源ID，可重新执行az acr show --name $ACR_NAME --query "id" --output tsv确认
• 检查SP的角色权限：执行az role assignment list --assignee $USER_NAME --scope $ACR_REGISTRY_ID，确保输出中包含"roleDefinitionName": "acrpush"

2. 检查Docker服务连接配置 #

• 服务连接类型选择Docker Registry，认证方式选用户名和密码
• 用户名填入SP的appId（脚本输出的Service principal ID），密码填入脚本生成的PASSWORD
• 注册表URL必须是ACR的登录服务器地址（格式：myacrname.azurecr.io），不能遗漏或拼写错误

3. 确认镜像标签与仓库名匹配 #

• 推送任务中的repository参数必须对应ACR中的仓库名（例如myapp，完整镜像路径应为myacrname.azurecr.io/myapp:tag）
• 确保流水线中包含镜像构建与标记步骤，否则推送的镜像不存在会触发授权类错误，示例补充步骤：

  - task: Docker@2
    displayName: Build and tag image
    inputs:
      command: build
      repository: ${{ parameters.docker.repository }}
      tags: ${{ parameters.docker.tag }}
      containerRegistry: ${{ parameters.docker.registry }}
      dockerfile: '**/Dockerfile'
  

4. 优化Docker任务执行逻辑 #

• 移除单独的login任务：Docker@2的push或buildAndPush命令会自动使用服务连接凭证完成登录，单独登录可能因上下文切换导致会话失效。修改后的流水线示例：

  steps:
  - task: Docker@2
    displayName: Build and Push Image
    continueOnError: false
    inputs:
      command: buildAndPush
      repository: ${{ parameters.docker.repository }}
      containerRegistry: ${{ parameters.docker.registry }}
      tags: ${{ parameters.docker.tag }}
      dockerfile: '**/Dockerfile'
  

5. 检查ACR的访问限制 #

• 确认ACR未启用防火墙或虚拟网络限制，导致Azure DevOps代理无法访问推送端点（私有网络ACR需确保代理在允许的网络范围内）
• 排查ACR管理员用户状态：若启用了管理员用户，需确认服务连接未误用管理员凭证（避免权限冲突）

内容的提问来源于stack exchange，提问作者freedev