企业官网建设流程全解析

本指南围绕 autoskills 仓库中 azure-deploy 技能的强制规则文件 global-rules.md 展开，系统讲解 Azure 部署过程中两条不可逾越的安全红线——危险操作必须经用户确认、订阅与区域不得擅自假设——并深入结合 pre-deploy-checklist.md 的完整部署前检查流程。读者将掌握一套可直接落地的 Azure 安全部署规范：何时必须调用ask_user、如何正确确认订阅与区域、如何规避资源组冲突、RBAC 传播延迟与标签冲突等高频故障。

为什么 Azure 部署需要“全局强制规则”

在 azure-deploy 技能体系中，global-rules.md不是普通建议，而是对所有相关技能一律适用、违反即不可接受的强制性约束（原文以MANDATORY标注）。它的定位非常明确：

• azure-deploy 只负责执行已经准备好的应用的部署（azd up、azd deploy、terraform apply、az deployment），不负责创建应用或生成基础设施代码；
• 在执行这些命令前，必须满足两个前置条件：azure-prepare已生成.azure/deployment-plan.md，且azure-validate已将其状态置为Validated；
• 任何部署动作都可能带来删除、覆盖、不可逆、成本、安全五类风险，因此必须有统一的确认机制兜底。

该文件与技能主文档的 Rules 一节（SKILL.md）互相引用，构成了“先确认、再检查、后执行”的完整安全闭环。

Rule 1：一切危险操作必须经过ask_user确认

第一条红线：在任何危险操作之前，必须无条件使用ask_user征求用户明确同意。

什么算“危险操作”

global-rules.md 用一张表划定了危险操作的边界，凡落入以下类别的动作都属于必须确认的范围：

确认方式示例

规则给出了标准化的ask_user调用模板——问题必须具体描述后果，选项必须明确且可执行：

ask_user( question: "This will permanently delete resource group 'rg-myapp'. Continue?", choices: ["Yes, delete it", "No, cancel"] )

没有例外

global-rules.md 明确列举了三条“不得”：

1. 不得假设用户想要删除或覆盖——即使任务描述听起来像是要清理旧环境；
2. 不得基于“用户要求部署”就继续——部署（deploy）不等于删除旧资源（delete old）；
3. 不得批量执行危险操作而不逐个确认——每个破坏性动作都必须单独征求同意。

Rule 2：永远不要假设订阅或区域

第二条红线：必须使用ask_user确认两件事：

• Azure 订阅（必须展示真实的订阅名称和 ID）；
• Azure 区域/位置（location）。

规则明确指出“永远不要假设”（Never Assume），并指向 pre-deploy-checklist.md 作为落地指南。这条规则在实践中往往是被忽视的高频事故源：部署到了错误的订阅，或把资源创建到了不支持某服务的区域，都会造成资源浪费与返工。

部署前检查清单：Rule 2 的九步落地

pre-deploy-checklist.md 将 Rule 2 扩展为一条必须按顺序完成、缺一不可的检查链。它开宗明义地警告：在完成所有步骤之前，禁止运行azd up——试错不仅浪费时间，还会产生孤立资源（orphan resources）。

Step 1–2：确认当前订阅并征求用户选择

先用 Azure MCP 工具列出订阅，或使用 CLI 回退方案：

az account show --query "{name:name, id:id}" -o json

然后必须用ask_user确认，且选项要展示真实名称与 ID：

ask_user( question: "Which Azure subscription would you like to deploy to?", choices: [ "Use current: <subscription-name> (<subscription-id>) (Recommended)", "Let me specify a different subscription" ] )

清单特别强调了一个反模式：永远不要用自由输入框让用户填订阅（❌ Wrong 示例），因为自由输入极易拼错，也无法校验权限。

Step 3：先创建 AZD 环境，再谈其他

这是“先有环境、后有部署”的强制顺序：

# 新项目（尚无 azure.yaml） azd init -e <environment-name> --no-prompt # 已有项目（azure.yaml 已存在） azd env new <environment-name> --no-prompt

两条命令都会创建.azure/<env-name>/配置目录并将其设为默认环境；环境名会直接成为资源组名的一部分（rg-<env-name>）。注意：严禁手动mkdir创建.azure/目录，必须让 azd 自己生成，否则环境结构会损坏。

Step 4：检查资源组是否已存在

跳过这一步会直接撞上 “Invalid resource group location” 错误。先列出资源组：

mcp_azure_mcp_group_list subscription: <subscription-id>

CLI 回退：

az group show --name rg-<env-name> --query "{location:location}" -o json 2>&1

如果rg-<env-name>已存在，必须用ask_user提供三个选项：复用现有 RG 的位置、换一个环境名、删除旧 RG 重新开始（删除属于危险操作，按 Rule 1 必须确认）。

Step 5：检查标签冲突（仅 AZD）

AZD 依靠azd-service-name标签在目标资源组内定位部署目标，同一 RG 内出现同标签的多个资源会导致部署失败：

az resource list --resource-group rg-<env-name> --tag azd-service-name=<service-name> --query "[].name" -o table

若发现冲突，优先推荐新建环境（azd env new <new-name> --no-prompt，非破坏性、无需确认）；只有删除旧资源才需要ask_user。

Step 5a：检查既有 Container Apps 环境（仅 Container Apps）

这是容易造成环境漂移的隐藏陷阱：跳过此步，azd up可能静默创建一个名称意外的 Container Apps 环境（例如"deployment-prod"），导致部署时间大幅拉长。只有当资源组已存在时才需检查：

az containerapp env list \ --resource-group rg-<env-name> \ --query "[].{name:name, location:location, provisioningState:properties.provisioningState}" \ -o table

处理策略：Failed/Deleting状态的环境视为无冲突；Succeeded的环境需ask_user三选一——复用现有环境（用azd env select <matching-env-name>或重建并azd env set AZURE_SUBSCRIPTION_ID/AZURE_LOCATION指向既有资源组）、换个新环境名、或删除重建（危险操作，需确认）。

Step 6：征求区域选择

必须用ask_user提供支持架构中全部服务的区域列表，服务级限制见 region-availability.md。

Step 7：设置环境变量

所有变量必须在azd up之前设置完毕，而不是在错误恢复阶段补：

azd env get-values # 确认 AZURE_SUBSCRIPTION_ID / AZURE_LOCATION 已配置

Step 8：此时才允许部署

azd up --no-prompt

Step 9：Terraform 变量解析校验（仅 AZD + Terraform）

对 azd+Terraform 项目强制：Terraform 文件与main.tfvars.json中禁止残留 Go 风格模板变量（{{ .Env.VAR }}），必须使用${VAR}语法，否则部署会因未解析变量失败。校验脚本与修复步骤（改用TF_VAR_*环境变量、重跑 azure-validate）均已写入清单。

正确序列速查

# 1. 先建环境 azd env new myapp-dev --no-prompt # 2. 设置订阅 azd env set AZURE_SUBSCRIPTION_ID 25fd0362-... # 3. 确认 RG 无冲突后设置区域 azd env set AZURE_LOCATION westus2 # 4. 验证 azd env get-values # 5. 部署 azd up --no-prompt

高频错误对照：规则背后的“为什么”

清单和 troubleshooting.md 给出了常见误区的正反对照，这也解释了规则如此强硬的根源：

Container Apps + ACR：必做 RBAC 传播健康检查

这是 checklist 中最关键的专项检查之一：当 Container Apps 通过托管身份从 ACR 拉取镜像时，必须采用两阶段流程，并在“预配”与“镜像部署”之间插入AcrPull角色传播闸门。原因是 Azure RBAC 传播存在 1–5 分钟延迟，若跳过闸门，Container App 修订版会因等待拉取权限而超时（约 900 秒）。Bicep（AZD）路径的正确顺序是azd provision→ RBAC 健康检查 →azd deploy --no-prompt；Terraform 路径则是terraform apply→ 健康检查 →az acr build+az containerapp registry set+az containerapp update。两阶段模式使用公共占位镜像mcr.microsoft.com/azuredocs/containerapps-helloworld:latest先完成预配，再用真实镜像切换。

健康检查三步（两种路径通用）：取 Container App 托管身份的principalId（az containerapp identity show）、取 ACR 的id（az acr show）、轮询az role assignment list直到出现AcrPull（最多 5 次、每次间隔 60 秒）。轮询脚本（bash 与 PowerShell 双版本）完整收录于 pre-deploy-checklist.md。

部署后的活体角色验证

部署成功后，live-role-verification.md 要求对线上 Azure 状态做一次角色核对，与 azure-validate 的静态代码检查互补——因为 Bicep/Terraform 正确不代表预配成功，策略强制或人工修改也可能改变角色分配。

验证流程：先从.azure/deployment-plan.md找出所有带托管身份的服务，查询 principal ID；再按principalId查询角色分配；最后按业务需要交叉核对：

常见问题包括：角色作用域错误（分配到资源组而非具体资源）、用Contributor替代数据面角色（无数据面权限）、角色完全缺失、上次部署残留的陈旧 principal ID。结果需记录进.azure/deployment-plan.md的部署验证日志。

部署执行的完整工作流

按 recipes/azd/README.md，一次合规的 AZD 部署应走：azd env get-values验证环境 →azd provision --no-prompt预配 → （Container Apps + ACR 时）RBAC 健康检查 →azd deploy --no-prompt部署 → 后置部署步骤 → 验证 → 汇报。其中 verify.md 特别强调：汇报端点时必须是带https://的完整 URL（很多 Azure CLI 命令只返回裸主机名），且必须以azd show的输出为准解析Endpoint:行，因为azd deploy的输出经常在端点出现前就被截断。涉及 Azure SQL + 托管身份的应用还需在部署后完成 post-deployment.md 描述的 SQL 授权与 EF Core 迁移。

总结

azure-deploy 的全局规则看似只有两条，却贯穿了整个部署生命周期：Rule 1 通过ask_user把“删除、覆盖、不可逆、成本、安全”五类风险全部纳入人类确认范围；Rule 2 通过强制确认订阅与区域，杜绝了部署到错误租户或不可用区域的事故。而 pre-deploy-checklist.md 的九步流程、RBAC 传播闸门、活体角色验证，则把这两条红线变成了可操作、可验证、可回滚的工程规范。这套规则的直接价值在于：把 Azure 部署中最昂贵的三类失败——错误订阅、资源组位置冲突、ACR 拉取权限超时——从“事后救火”变成了“事前拦截”。