Azure 开发者 CLI（azd）容器应用部署

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

快速开始

# 初始化并部署
azd auth login
azd init                    # 创建 azure.yaml 和 .azure/ 目录
azd env new       # 创建环境（dev、staging、prod）
azd up                      # 部署基础设施 + 构建 + 部署

核心文件结构

project/
├── azure.yaml              # azd 服务定义 + 钩子（hooks）
├── 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}" }
  }
}

语法：${VAR_NAME} 或 ${VAR_NAME=default_value}

设置环境变量

# 为当前环境设置变量
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 复用已有镜像层 — 仅上传变更的层

保留手动变更

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

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

容器应用服务发现

同一环境内容器应用之间的内部 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 KEY value               # 设置环境变量

# 部署
azd up                              # 完整部署：基础设施 + 构建 + 应用部署
azd provision                       # 仅部署基础设施
azd deploy                          # 仅部署代码
azd deploy --service backend        # 仅部署 backend 服务

# 调试
azd show                            # 显示项目当前状态
az containerapp logs show -n  -g  --follow  # 实时流式输出日志

参考文件

• Bicep 模式：参阅 references/bicep-patterns.md 获取 Container Apps 模块示例
• 故障排查：参阅 references/troubleshooting.md 查看常见问题解决方案
• azure.yaml Schema：参阅 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 权限“已存在”导致部署失败