name: azd-deployment
description: 使用 Azure Developer CLI (azd) 将容器化应用程序部署到 Azure Container Apps。适用于设置 azd 项目、编写 azure.yaml 配置、为 Container Apps 创建 Bicep 基础设施、配置 ACR 远程构建、实现幂等部署、管理本地/.azure/Bicep 环境变量或排查 azd up 失败。触发场景包括：azd 配置、Container Apps 部署、多服务部署以及使用 Bicep 的基础设施即代码请求。

Azure Developer CLI (azd) Container Apps 部署

使用远程构建、托管标识和幂等基础设施，将容器化的前端 + 后端应用程序部署到 Azure Container Apps。

快速开始

# 初始化和部署
azd auth login
azd init                    # 创建 azure.yaml 和 .azure/ 文件夹
azd env new <环境名称>      # 创建环境（dev, staging, prod）
azd up                      # 预配基础设施 + 构建 + 部署

核心文件结构

项目/
├── azure.yaml              # azd 服务定义和钩子
├── infra/
│   ├── main.bicep          # 根基础设施模块
│   ├── main.parameters.json # 从环境变量注入参数
│   └── modules/
│       ├── container-apps-environment.bicep
│       └── container-app.bicep
├── .azure/
│   ├── config.json         # 默认环境指针
│   └── <环境名称>/
│       ├── .env            # 环境特定值（azd 管理）
│       └── config.json     # 环境元数据
└── src/
    ├── frontend/Dockerfile
    └── backend/Dockerfile

azure.yaml 配置

最小配置

name: azd-deployment
services:
  backend:
    project: ./src/backend
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

包含钩子的完整配置

name: azd-deployment
metadata:
  template: my-project@1.0.0

infra:
  provider: bicep
  path: ./infra

azure:
  location: eastus2

services:
  frontend:
    project: ./src/frontend
    language: ts
    host: containerapp
    docker:
      path: ./Dockerfile
      context: .
      remoteBuild: true

  backend:
    project: ./src/backend
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      context: .
      remoteBuild: true

hooks:
  preprovision:
    shell: sh
    run: |
      echo "预配前..."

  postprovision:
    shell: sh
    run: |
      echo "预配后 - 设置 RBAC 等。"

  postdeploy:
    shell: sh
    run: |
      echo "前端: ${SERVICE_FRONTEND_URI}"
      echo "后端: ${SERVICE_BACKEND_URI}"

关键 azure.yaml 选项

环境变量流转

三级配置

1. 本地 .env - 仅用于本地开发
2. .azure/<环境>/.env - azd 管理，从 Bicep 输出自动填充
3. main.parameters.json - 将环境变量映射到 Bicep 参数

参数注入模式

// infra/main.parameters.json
{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION=eastus2}" },
    "azureOpenAiEndpoint": { "value": "${AZURE_OPENAI_ENDPOINT}" }
  }
}

语法：${变量名} 或 ${变量名=默认值}

设置环境变量

# 为当前环境设置
azd env set AZURE_OPENAI_ENDPOINT "https://my-openai.openai.azure.com"
azd env set AZURE_SEARCH_ENDPOINT "https://my-search.search.windows.net"

# 在初始化时设置
azd env new prod
azd env set AZURE_OPENAI_ENDPOINT "..." 

Bicep 输出 → 环境变量

// 在 main.bicep 中 - 输出会自动填充到 .azure/<环境>/.env
output SERVICE_FRONTEND_URI string = frontend.outputs.uri
output SERVICE_BACKEND_URI string = backend.outputs.uri
output BACKEND_PRINCIPAL_ID string = backend.outputs.principalId

幂等部署

为何 azd up 是幂等的

1. Bicep 是声明式的 - 资源会协调到期望状态。
2. 远程构建具有唯一标签 - 镜像标签包含部署时间戳。
3. ACR 重用层 - 仅上传已更改的层。

保留手动更改

通过门户添加的自定义域名在重新部署时可能会丢失。可通过钩子保留：

hooks:
  preprovision:
    shell: sh
    run: |
      # 在预配前保存自定义域名
      if az containerapp show --name "$FRONTEND_NAME" -g "$RG" &>/dev/null; then
        az containerapp show --name "$FRONTEND_NAME" -g "$RG" \
          --query "properties.configuration.ingress.customDomains" \
          -o json > /tmp/domains.json
      fi

  postprovision:
    shell: sh
    run: |
      # 验证/恢复自定义域名
      if [ -f /tmp/domains.json ]; then
        echo "保存的域名: $(cat /tmp/domains.json)"
      fi

处理现有资源

// 引用现有 ACR（不重新创建）
resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
  name: containerRegistryName
}

// 将 customDomains 设置为 null 以保留门户添加的域名
customDomains: empty(customDomainsParam) ? null : customDomainsParam

Container App 服务发现

同一环境中 Container Apps 之间的内部 HTTP 路由：

// 在前端环境变量中引用后端
env: [
  {
    name: 'BACKEND_URL'
    value: 'http://ca-backend-${resourceToken}'  // 内部 DNS
  }
]

前端 nginx 代理到内部 URL：

location /api {
    proxy_pass $BACKEND_URL;
}

托管标识与 RBAC

启用系统分配的标识

resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  identity: {
    type: 'SystemAssigned'
  }
}

output principalId string = containerApp.identity.principalId

预配后 RBAC 分配

hooks:
  postprovision:
    shell: sh
    run: |
      PRINCIPAL_ID="${BACKEND_PRINCIPAL_ID}"

      # Azure OpenAI 访问权限
      az role assignment create \
        --assignee-object-id "$PRINCIPAL_ID" \
        --assignee-principal-type ServicePrincipal \
        --role "Cognitive Services OpenAI User" \
        --scope "$OPENAI_RESOURCE_ID" 2>/dev/null || true

      # Azure AI Search 访问权限
      az role assignment create \
        --assignee-object-id "$PRINCIPAL_ID" \
        --role "Search Index Data Reader" \
        --scope "$SEARCH_RESOURCE_ID" 2>/dev/null || true

常用命令

# 环境管理
azd env list                        # 列出环境
azd env select <名称>               # 切换环境
azd env get-values                  # 显示所有环境变量
azd env set 键 值                   # 设置变量

# 部署
azd up                              # 完整预配 + 部署
azd provision                       # 仅基础设施
azd deploy                          # 仅代码部署
azd deploy --service backend        # 部署单个服务

# 调试
azd show                            # 显示项目状态
az containerapp logs show -n <应用> -g <资源组> --follow  # 流式传输日志

参考文件

• Bicep 模式：请参阅 references/bicep-patterns.md 获取 Container Apps 模块。
• 故障排除：请参阅 references/troubleshooting.md 获取常见问题。
• azure.yaml 模式：请参阅 references/azure-yaml-schema.md 获取完整选项。

重要提醒

1. 始终使用 remoteBuild: true - 在 M1/ARM Mac 上部署到 AMD64 时，本地构建会失败。
2. Bicep 输出会自动填充 .azure/<环境>/.env - 请勿手动编辑。
3. 使用 azd env set 设置机密 - 不要在 main.parameters.json 中使用默认值。
4. 服务标签 (azd-service-name) - azd 查找 Container Apps 所必需。
5. 钩子中的 || true - 防止 RBAC "已存在" 错误导致部署失败。