Azure Container Registry 云构建与 ACR Tasks 完全指南从 az acr build 到多步流水线自动化【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot在 GitHub Copilot 生态的 awesome-copilot 仓库中azure-container-registry-cli技能见 SKILL.md系统整理了通过az acr命令组管理 Azure 容器注册表的完整实践而其中的 build-and-tasks.md 则是聚焦镜像构建与自动化任务这一核心场景的权威参考。本文以该参考文档为主体围绕az acr build、az acr run、az acr task三大命令展开覆盖快速云构建、一次性任务、可触发的持久化任务、三类触发器、多步任务 YAML 与专用 Agent Pools并结合仓库中同一技能族的 auth-and-security.md、images-and-artifacts.md、networking-and-geo.md 补充身份、清理与网络边界场景。读完本文你将能够在无本地 Docker 守护进程的情况下完成云端构建、把构建-测试-推送流水线固化为可持续触发的 ACR Task并为受限网络环境配置专用计算资源。概览三条构建路径的分工在动手之前先厘清az acr命令组中与构建相关的三兄弟对应 SKILL.md 中的 CLI 结构命令用途持久性典型场景az acr build一次性云构建并推送Quick Build无手动验证、CI 管道中按需构建az acr run在注册表任务运行器中执行容器命令或一次性多步任务无执行acr purge清理、试运行acb.yamlaz acr task可持久化、可触发的构建定义有提交触发、基础镜像触发、定时触发核心原则是优先使用az acr build与 ACR Tasks而不是本地的docker builddocker push——构建在 Azure 端执行、不依赖本地守护进程且能与 Git 提交、基础镜像更新、cron 定时等触发器深度集成。az acr随 Azure CLI 核心发行无需安装扩展只有在使用acrtransfer导出/导入管道时才需要扩展见 SKILL.md。Quick Buildaz acr build的完整用法az acr build在 Azure 中执行构建并将结果推送到注册表全程不需要本地 Docker 守护进程这是它相比docker build最显著的优势。基础与进阶参数# 从当前目录构建并推送 az acr build --registry {registry} --image app:v1 . # 自定义 Dockerfile、构建参数、目标平台 az acr build --registry {registry} --image app:v1 \ --file docker/Dockerfile.prod \ --build-arg VERSION1.2.3 \ --platform linux/amd64 .三个高频参数说明--file指定 Dockerfile 路径相对构建上下文默认为上下文根目录的Dockerfile--build-arg透传给 Docker 构建的 ARG 变量可重复指定多个--platform目标平台如linux/amd64、linux/arm64、windows/amd64用于跨平台交叉构建。跨平台与多架构镜像的正确姿势需要特别澄清的是每次az acr build只针对单一目标平台产出一个单架构镜像并不会自动生成多架构清单列表# 为每个平台分别构建使用带架构信息的 tag az acr build --registry {registry} --image app:v1-arm64 --platform linux/arm64 . az acr build --registry {registry} --image app:v1-amd64 --platform linux/amd64 . # 然后在本地方可组装并推送 manifest list多架构索引 # docker manifest create/push或在本地使用 docker buildx这一点对生产环境至关重要若集群节点同时包含 amd64 与 arm64必须走分平台构建 清单列表合并的流程而不能指望单次 build 产出多架构镜像。从 Git 仓库直接构建无需在本地克隆代码az acr build支持直接从远程 Git 仓库拉取构建上下文az acr build --registry {registry} --image app:v1 https://github.com/{org}/{repo}.git#{branch}:{folder}URL 的#后依次是分支与子目录可精确指定要构建的代码位置。仅校验不推送# --no-push验证构建是否成功但不推送镜像 az acr build --registry {registry} --image app:test --no-push .Quick Build 的两个实践要点构建上下文会上传az acr build会把上下文目录打包上传到云端执行务必使用.dockerignore排除node_modules、.git、构建产物等无关内容保持上传体积小、构建速度快tag 策略为每次构建使用唯一值如 Git SHA、运行 ID避免依赖latest——否则无法追溯当前 latest 对应哪次提交也会让回滚变得困难。ACR Tasks 提供的内置运行变量正是为此设计的见下文。一次性任务az acr runaz acr run适合不需要持久化定义的场景两种形态# 在注册表的任务运行器中执行一个容器命令 # 上下文为 /dev/null 表示不上传任何文件 az acr run --registry {registry} --cmd {registry}.azurecr.io/app:v1 /dev/null # 针对当前目录执行一个多步任务文件 az acr run --registry {registry} --file acb.yaml .第一种形态的典型用途是执行acr purge清理命令详见 images-and-artifacts.md# 清理前永远先做 dry-run az acr run --registry {registry} \ --cmd acr purge --filter app:.* --ago 30d --untagged --dry-run /dev/nullacr purge以 ACR Task 容器mcr.microsoft.com/acr/acr-cli形式运行--filter接受仓库:tag正则且可重复指定多个仓库。注意--untagged会忽略--ago时间窗、删除所有未打 tag 的清单包括刚推送中途的镜像与 referrer 制品若近期未打 tag 的清单需要保留请省略该参数。持久化构建定义az acr taskACR Tasks 将构建定义固化在注册表中可被 Git 提交、基础镜像更新或 cron 定时器触发是自动化流水线的核心。创建、触发、查看与清理# 创建任务main 分支每次提交都触发构建 az acr task create --registry {registry} --name build-app \ --image app:{{.Run.ID}} \ --context https://github.com/{org}/{repo}.git#main \ --file Dockerfile \ --git-access-token {pat} \ --commit-trigger-enabled true \ --base-image-trigger-enabled true # 手动触发 az acr task run --registry {registry} --name build-app # 列出任务 / 查看运行历史 az acr task list --registry {registry} --output table az acr task list-runs --registry {registry} --name build-app --output table # 查看日志最近一次运行或按 run-id 指定 az acr task logs --registry {registry} --name build-app az acr task logs --registry {registry} --run-id {run-id} # 更新 / 停用 / 删除 az acr task update --registry {registry} --name build-app --image app:{{.Run.ID}} az acr task update --registry {registry} --name build-app --status Disabled az acr task delete --registry {registry} --name build-app --yes创建时的关键参数--context任务监听/构建的 Git 仓库位置#后为分支--git-access-token访问私有仓库的 PATGitHub 等平台--commit-trigger-enabled/--base-image-trigger-enabled分别开启提交触发与基础镜像触发见下一节--image镜像 tag 模板可引用运行变量。运行变量为每次构建生成唯一 tag--image支持以下内置运行变量用于生成可追溯的唯一 tag变量含义示例值{{.Run.ID}}本次运行的全局唯一 IDca1{{.Run.Commit}}触发构建的提交 SHAa1b2c3d…{{.Run.Branch}}触发构建的分支名main{{.Run.Date}}运行日期/时间20240101.120000实战中最常用的组合是app:{{.Run.ID}}——每次运行自动获得新 tag天然规避latest覆盖问题且az acr task list-runs的 run-id 与镜像 tag 一一对应便于回滚定位。触发器让流水线自动化ACR Tasks 支持三类触发器共同覆盖代码变化、依赖变化、时间到达三种自动化驱动场景# Timer 触发器cron 表达式使用 UTC 时区例如每天凌晨 2 点重建 az acr task timer add --registry {registry} --name build-app \ --timer-name nightly --schedule 0 2 * * * az acr task timer list --registry {registry} --name build-app az acr task timer remove --registry {registry} --name build-app --timer-name nightly三类触发器的定位Commit trigger推送代码到被跟踪分支时重建镜像创建任务时的--commit-trigger-enabled trueBase image trigger基础镜像如打了安全补丁的mcr.microsoft.com官方镜像更新时自动重建是操作系统/框架安全打补丁的关键机制--base-image-trigger-enabled trueTimer triggercron 定时执行同时也是调度acr purge清理任务的标准方式——结合 images-and-artifacts.md 中的示例可把清理固化为每晚执行的持久任务az acr task create --registry {registry} --name purge-old-images \ --cmd acr purge --filter app:.* --ago 30d --untagged \ --context /dev/null --schedule 0 3 * * *跨注册表访问与托管身份当任务需要访问其他注册表或 Azure 资源时为其分配托管身份# 分配系统分配身份 az acr task identity assign --registry {registry} --name build-app # 为其他注册表添加凭据使用该身份认证 az acr task credential add --registry {registry} --name build-app \ --login-server {other-registry}.azurecr.io --use-identity [system]这与 auth-and-security.md 中优先使用 Entra 身份而非管理员凭据的原则一脉相承任务身份 RBAC 角色AcrPull/AcrPush或 ABAC 仓库角色可避免在任务定义中存储明文凭据。多步任务 YAMLacb.yaml单条命令无法表达先构建、再测试、成功才推送的流程这时使用 ACR 的多步任务文件。以下acb.yaml是典型的三段式流水线——构建、运行测试、仅在成功时推送version: v1.1.0 steps: - build: -t $Registry/app:{{.Run.ID}} -f Dockerfile . - cmd: $Registry/app:{{.Run.ID}} run-tests - push: - $Registry/app:{{.Run.ID}}几个关键概念version: v1.1.0多步任务的 YAML 语法版本$Registry内置变量展开为当前注册表的登录服务器地址避免硬编码{{.Run.ID}}运行变量贯穿三步保证同一镜像身份一致build/cmd/push步骤类型分别对应镜像构建、容器命令执行、镜像推送任何一步失败则整个任务失败后续步骤不会执行。执行方式同样有两种——一次性试运行或固化为带触发的任务# 一次性运行 az acr run --registry {registry} --file acb.yaml . # 或从 YAML 创建带 Git 触发的持久任务 az acr task create --registry {registry} --name build-test-push \ --file acb.yaml \ --context https://github.com/{org}/{repo}.git#main \ --git-access-token {pat}注意az acr run与az acr task create的上下文语义不同az acr run --file acb.yaml .基于本地当前目录执行适合调试而az acr task create --file acb.yaml --context git-url将任务绑定到远程仓库由触发器驱动。Agent Pools专用任务计算资源Agent Pools 是Premium SKU特性提供专用的任务计算资源解决两类问题需要更多 CPU 的任务以及在网络受限防火墙/VNet的注册表上运行任务。后者是文档明确指出的两种受支持方式之一另一种是受信任服务 任务网络绕过策略详见 networking-and-geo.md。# 创建 Agent Pool层级别支持 S1/S2/S3/I6I 系列为隔离实例 az acr agentpool create --registry {registry} --name pool1 --tier S2 # 防火墙/VNet 场景池必须挂接到能访问注册表专用终结点的子网 # 不带 --subnet-id 时运行在 VNet 之外 az acr agentpool create --registry {registry} --name pool1 --tier S2 \ --subnet-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Network/virtualNetworks/{vnet}/subnets/{subnet} az acr agentpool list --registry {registry} --output table # 在构建与任务中指定使用该池 az acr build --registry {registry} --agent-pool pool1 --image app:v1 . az acr task create --registry {registry} --name build-app --agent-pool pool1 ...关于 VNet 场景的关键提醒Agent Pool 的--subnet-id指向的子网必须能够访问注册表的专用终结点否则构建代理无法拉取上下文或推送镜像。若注册表关闭了公共访问标准 ACR Tasks 代理将无法触达注册表必须改用 VNet 内子网的 Agent Pool或显式开启任务网络绕过策略见 networking-and-geo.md 中的properties.networkRuleBypassAllowedForTaskstrue配置。边界情况与安全注意原文档在三个位置标注了 ⚠️ 提醒实践中务必逐条落实1. ABAC 注册表上任务的源注册表访问权限在启用 ABAC 仓库权限的注册表roleAssignmentModeAbacRepositoryPermissions上任务与快速构建/运行默认没有源注册表的访问权限。处理方式# 对 az acr build / az acr run以调用者身份认证源注册表 az acr build --registry {registry} --image app:v1 --source-acr-auth-id [caller] . az acr run --registry {registry} --cmd ... --source-acr-auth-id [caller] /dev/null # 对 az acr task create / update使用 [system] 或用户分配身份的资源 ID az acr task create --registry {registry} --name build-app \ --source-acr-auth-id [system] \ --assign-identity [system] ... # 创建时必须确保任务确实拥有该身份关键顺序先确保任务拥有该身份创建时加--assign-identity [system]或在已存在的任务上运行az acr task identity assign再在引用它时授予Container Registry Repository ...系列角色。这与 auth-and-security.md 中ABAC 模式下AcrPull/AcrPush不被认可、须改用Container Registry Repository Reader/Writer/Contributor的规则完全一致。2. 清理任务的身份限制结合 networking-and-geo.md自 2025 年 6 月 1 日起对网络受限的注册表使用系统分配托管身份的任务仅靠--allow-trusted-services true已不足够运行时会收到 403——必须显式开启任务网络绕过策略或改用 VNet 内 Agent Pool或使用用户分配身份不受影响。3. 不依赖latesttag所有构建路径都应使用唯一 tag{{.Run.ID}}、Git SHA、构建编号可结合 images-and-artifacts.md 中的镜像锁定az acr repository update --image app:v1 --write-enabled false对正式发布版本做防覆盖保护。快速上手路径将上述命令组合成一个可直接照做的流程前置条件见 SKILL.md安装 Azure CLI 并az login、az account set --subscription {subscription-id}# 1. 创建注册表SKU: Basic | Standard | Premium az acr create --resource-group {rg} --name {registry} --sku Standard # 2. 云端快速构建验证 az acr build --registry {registry} --image app:v1 . # 3. 以多步 YAML 固化构建-测试-推送流水线 az acr task create --registry {registry} --name build-test-push \ --file acb.yaml \ --context https://github.com/{org}/{repo}.git#main \ --git-access-token {pat} \ --commit-trigger-enabled true --base-image-trigger-enabled true # 4. 查看运行状态与日志 az acr task list-runs --registry {registry} --name build-test-push --output table az acr task logs --registry {registry} --name build-test-push至此你已经掌握了从一次性云端构建、一次性多步任务到可持续触发的持久化任务、多步 YAML 流水线与专用计算池的完整 ACR 自动化能力。配合同一技能族的 auth-and-security.md身份与权限、images-and-artifacts.md镜像清理与锁定、networking-and-geo.md私有网络与跨区域即可在 Azure 上落地一套安全、自动化的镜像构建与交付体系。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考