企业官网建设流程全解析

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与 ACR Tasks，而不是本地的docker build+docker push——构建在 Azure 端执行、不依赖本地守护进程，且能与 Git 提交、基础镜像更新、cron 定时等触发器深度集成。az acr随 Azure CLI 核心发行，无需安装扩展；只有在使用acrtransfer导出/导入管道时才需要扩展（见 SKILL.md）。

Quick Build：az 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 VERSION=1.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 的两个实践要点

1. 构建上下文会上传：az acr build会把上下文目录打包上传到云端执行，务必使用.dockerignore排除node_modules、.git、构建产物等无关内容，保持上传体积小、构建速度快；
2. tag 策略：为每次构建使用唯一值（如 Git SHA、运行 ID），避免依赖latest——否则无法追溯"当前 latest 对应哪次提交"，也会让回滚变得困难。ACR Tasks 提供的内置运行变量正是为此设计的（见下文）。

一次性任务：az acr run

az 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/null

acr purge以 ACR Task 容器（mcr.microsoft.com/acr/acr-cli）形式运行，--filter接受仓库:tag正则且可重复指定多个仓库。注意--untagged会忽略--ago时间窗、删除所有未打 tag 的清单（包括刚推送中途的镜像与 referrer 制品），若近期未打 tag 的清单需要保留，请省略该参数。

持久化构建定义：az acr task

ACR 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：访问私有仓库的 PAT（GitHub 等平台）；
• --commit-trigger-enabled/--base-image-trigger-enabled：分别开启提交触发与基础镜像触发（见下一节）；
• --image：镜像 tag 模板，可引用运行变量。

运行变量：为每次构建生成唯一 tag

--image支持以下内置运行变量，用于生成可追溯的唯一 tag：

实战中最常用的组合是"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 true）；
• Base image trigger：基础镜像（如打了安全补丁的mcr.microsoft.com官方镜像）更新时自动重建，是操作系统/框架安全打补丁的关键机制（--base-image-trigger-enabled true）；
• Timer trigger：cron 定时执行，同时也是调度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 仓库角色）可避免在任务定义中存储明文凭据。

多步任务 YAML：acb.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/I6（I 系列为隔离实例） 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.networkRuleBypassAllowedForTasks=true配置）。

边界情况与安全注意

原文档在三个位置标注了 ⚠️ 提醒，实践中务必逐条落实：

1. ABAC 注册表上任务的源注册表访问权限

在启用 ABAC 仓库权限的注册表（roleAssignmentMode=AbacRepositoryPermissions）上，任务与快速构建/运行默认没有源注册表的访问权限。处理方式：

# 对 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