你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

排查 Azure 容器应用 中的常见部署失败

本文可帮助您发现并解决 Azure 容器应用中最常需要升级给支持团队处理的部署失败场景。 每个场景都包含症状、门户和 CLI 中的诊断步骤以及解决方法。

在快速参考表中查找症状,并按照指向匹配方案的链接进行操作。

症状速查

症状 Scenario
部署因预配错误而失败,且未创建修订版本 映像拉取失败
已创建修订,但其状态为 FailedDegraded 容器崩溃和启动失败
机密或环境变量在运行时为空或缺失 机密访问问题
密钥保管库引用在部署期间或运行时失败 密钥保管库引用失败
托管标识调用返回 401 或 403 托管标识配置错误
Init 容器挂起或失败,应用永远不会启动 初始化计时问题
修订已预配,但标记为 Degraded 运行状况探测失败
应用正常,但请求返回错误或无响应 入口和流量路由问题
注册表身份验证失败(401 或未授权) 容器注册表身份验证

查看位置:诊断界面

使用以下诊断界面来排查部署失败问题。

Surface 它显示的内容 如何访问
诊断和解决问题 针对常见问题、故障排除类别和引导式分析的自动检测器。 在Azure门户中,转到容器应用并选择“诊断并解决问题”。
系统日志 平台级事件:映像拉取状态、探测结果、标识错误、机密同步结果。 az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50 或 Log Analytics ContainerAppSystemLogs_CL 表。
控制台日志 应用程序 stdout/stderr:堆栈跟踪、启动消息、运行时错误。 az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100 或门户“日志流”边栏选项卡。
HTTP 日志 入口层请求日志:状态代码、延迟、路径、重试、响应详细信息。 通过环境中的 Azure Monitor 诊断设置选择加入。 Log Analytics ContainerAppHTTPLogs 表。
修订详细信息属性 provisioningStateprovisioningErrorhealthStaterunningStaterunningStateDetails az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> -o json 或门户“修订”边栏选项卡。
部署时错误 未创建修订时的应用级 provisioningStateprovisioningError az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o json

镜像拉取失败

映像拉取失败是部署错误的最常见原因之一。 它们通常发生在 Azure 容器应用 创建出可用的修订版本之前。

症状

  • 未创建修订版本。
  • provisioningStateFailed
  • 错误消息提到 ImagePullBackOffUNAUTHORIZEDmanifest unknown

查看位置:映像拉取诊断

在Azure门户中,转到“容器应用>修订”(列表为空或显示失败条目)>诊断并解决问题,然后搜索“image”。

# Check app-level provisioning state and error
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "{provisioning:properties.provisioningState, error:properties.provisioningError, latestRevision:properties.latestRevisionName}" -o json

# List revisions (expect empty or failed)
az containerapp revision list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "[].{name:name, health:properties.healthState, provisioning:properties.provisioningState}" -o table

常见原因和解决方法

原因 错误信号 解决方法
图像标记不存在 manifest unknowntag not found 验证注册表中是否存在确切的标记: az acr repository show-tags --name <AZURE_CONTAINER_REGISTRY_NAME> --repository <REPOSITORY_NAME>
注册表需要身份验证 UNAUTHORIZED: authentication required 在容器应用中配置注册表凭据。 使用管理员凭据或托管标识进行 ACR 拉取。 请参阅 容器注册表身份验证
注册表主机名错误 name unknown、DNS 解析失败 验证 --image 值是否使用了正确的 <REGISTRY>.azurecr.io 主机名。
防火墙或 NSG 阻止访问注册表服务 连接超时 如果使用自定义 VNet,请确保对注册表进行出站访问。 添加 AzureContainerRegistry 服务标记或 FQDN 规则。

容器崩溃和启动失败

当已创建修订版本但工作负载无法启动或持续运行时,请使用本部分。

症状

  • 修订已创建,但 healthState 处于 Unhealthy 状态。
  • runningStateFailed
  • 控制台日志可能为空(在写入输出之前容器退出)。

查看位置:崩溃和启动诊断

在Azure门户中,转到“容器应用>修订”,选择失败的修订,然后打开“事件”选项卡。检查BackOffCrashLoopBackOff事件。

# Inspect revision detail
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "{health:properties.healthState, running:properties.runningState, details:properties.runningStateDetails, error:properties.provisioningError}" -o json

# Pull console logs (if any output was written)
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100

# Pull system logs for platform-level events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

常见原因和解决方法

原因 错误信号 解决方法
启动时应用崩溃 控制台日志中的堆栈跟踪 修复应用程序错误。 如果日志为空,则崩溃发生在刷新 stdout 之前。 添加早期日志记录或设置运行时以禁用输出缓冲(例如)。 PYTHONUNBUFFERED=1
命令或入口点无效 exec format errorexecutable file not found 验证容器的 commandargs 是否与映像所需的内容一致。 检查 az containerapp revision show 中是否有 properties.template.containers[].command
缺少环境变量 KeyErrorundefined、空引用 验证是否已设置所有必需的环境变量。 请参阅 机密访问问题
资源不足 OOMKilled 增加容器的内存和 CPU 限制: az containerapp update -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --cpu 1.0 --memory 2.0Gi

机密访问问题

使用本节可排查缺失或为空的密钥值问题,这些问题会导致应用程序在运行时配置失效。

症状

  • 容器启动,但应用程序失败,因为预期的配置值为空或缺失。
  • 引用机密的环境变量没有值。

查看位置:机密引用诊断

在Azure门户中,转到容器应用>设置>机密以验证机密是否存在。 然后转到 容器应用>修订,选择修订,并检查 容器详细信息>环境变量 以验证引用是否正确。

# List secrets defined on the app
az containerapp secret list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table

# Show the revision template to verify env var references
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "properties.template.containers[].env" -o json

常见原因和解决方法

原因 错误信号 解决方法
密钥名称不匹配 Env var 值为空 环境变量 secretRef 中必须与机密名称(区分大小写)完全匹配。
未定义机密 部署错误:引用了未知密钥 在部署之前定义机密: az containerapp secret set -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --secrets mysecret=myvalue
Secret 已更新,但修订版本未重新启动 旧值仍然保留 部署新的修订或重启现有版本: az containerapp revision restart -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> 仅更新机密不会触发新的修订。
机密在修订引用它时被删除 容器无法启动 部署删除对已删除机密的引用的新修订,然后停用旧修订。

Important

在容器应用中,机密的作用域限定在应用程序级别,而环境变量引用的作用域则限定在修订版本级别。 更改机密值不会自动对运行中的修订版本生效。 必须创建新的修订,或重启现有修订才能使更新的值生效。

密钥保管库 引用失败

在部署期间或应用运行时,密钥保管库支持的机密无法解析时,请使用此部分。

症状

  • 部署失败或机密值不可用。
  • 系统日志中提到了 密钥保管库 访问错误。
  • provisioningError提到针对 密钥保管库 进行身份验证或授权时失败。

查看位置:密钥保管库 访问诊断

在Azure门户中,转到“容器应用>设置>机密”(在密钥保管库参考上查找警告图标)。 然后转到容器应用>诊断并解决问题,然后搜索“密钥保管库”。

# List secrets and check for Key Vault reference status
az containerapp secret list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o json

# Verify managed identity is assigned
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>

常见原因和解决方法

原因 错误信号 解决方法
未启用托管身份 Managed identity not configured 启用系统分配的或用户分配的托管标识: az containerapp identity assign -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --system-assigned
缺少 RBAC 角色 Authorization failedAccess denied 向 密钥保管库 上的托管标识授予 密钥保管库 机密用户角色:az role assignment create --role "密钥保管库 Secrets User" --assignee <IDENTITY_PRINCIPAL_ID> --scope <KEYVAULT_RESOURCE_ID>
密钥保管库防火墙阻止访问 连接超时, ForbiddenByFirewall 将容器应用环境的出站 IP 添加到密钥保管库防火墙,或配置专用终结点。 如果对 Azure 防火墙 使用 UDR,则还要添加AzureKeyVault服务标记和 login.microsoft.com FQDN。
密钥保管库 中禁用机密 SecretDisabled 在 密钥保管库 中启用机密:Azure 门户 > 密钥保管库 > 机密 > 选择机密 > 启用。
格式错误的 密钥保管库 URI SecretNotFoundInvalidUri 验证 URI 格式: https://<vault>.vault.azure.net/secrets/<secret-name>https://<vault>.vault.azure.net/secrets/<secret-name>/<version>
RBAC 角色传播延迟 约 5 分钟后即可正常工作 传播 RBAC 更改最多可能需要 10 分钟。 标识令牌缓存最多可以保留 24 小时。 等待并重试,或部署新的修订。

托管标识配置错误

如果你的应用已配置为使用托管标识,但对 Azure 服务的身份验证仍然失败,请参阅本节。

症状

  • 应用程序代码在调用Azure服务时接收 401(未授权)或 403(禁止访问)。
  • 托管标识令牌获取失败。

查看位置:标识和授权诊断

在 Azure 门户中,转到容器应用>设置标识>(验证系统分配是否 On 或是否列出了用户分配的标识)。 然后检查目标资源的 IAM/访问控制边栏选项卡,了解角色分配。

# Verify identity configuration
az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME>

# Check role assignments for the identity's principal ID
az role assignment list --assignee <PRINCIPAL_ID> --all -o table

常见原因和解决方法

原因 错误信号 解决方法
未分配标识 SDK 引发 ManagedIdentityCredential 错误 分配标识:az containerapp identity assign -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --system-assigned
使用了错误的标识类型(系统分配的还是用户分配的) 目标资源上返回 403 如果使用用户分配的标识,请在代码中指定客户端 ID: DefaultAzureCredential(managed_identity_client_id="<CLIENT_ID>")
目标资源上缺少角色分配 403 在目标资源上分配所需角色(例如,存储帐户上的存储 Blob 数据参与者)。
Init 容器需要标识,但标识不可用 Init 容器失败并出现身份验证错误 在纯消耗型和专用工作负载配置文件环境中,初始化容器 无法使用 托管标识。 将依赖标识的逻辑移至主容器,或使用工作负载配置文件消耗环境,并在标识上设置 lifecycle: Init
角色更改后令牌缓存过期 修复后,403 错误仍会持续几分钟 标识令牌缓存最多可以保留 24 小时。 部署新版本以强制刷新令牌。

Tip

容器应用公开一个内部可访问的 REST 终结点,用于获取托管标识令牌。 不要直接调用此终结点,而是使用 Azure Identity SDKDefaultAzureCredential)在环境中获得一致的体验。

初始化计时问题

当 init 容器阻止启动,或在主容器开始提供服务之前发生故障时,请使用本部分。

症状

  • 应用永远不会达到运行状态。
  • 初始化容器似乎卡住了或失败。
  • 系统日志显示正在运行但从未完成的初始化容器。

查看位置:Init 容器诊断

在 Azure 门户中,转到“容器应用>修订”,选择该修订,然后打开“事件”选项卡。查找初始化容器事件。

# Check revision running state
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "{running:properties.runningState, details:properties.runningStateDetails}" -o json

# Check init container logs
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --container <INIT_CONTAINER_NAME> --tail 100

# System logs for platform events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

常见原因和解决方法

原因 错误信号 解决方法
Init 容器依赖于还不可用的服务 Init 容器日志中的连接被拒绝或超时 在 init 容器中添加重试逻辑或就绪情况检查。 不要假设依赖服务在初始化时可用。
初始化容器始终不退出 修订保留在 Provisioning 确保 init 容器运行有限命令,并使用代码 0 退出。 无限期运行的 Init 容器会阻止主容器启动。
Init 容器需要托管标识 从 Init 容器返回 401 或 403 在仅限消耗和专用工作负载配置文件环境中,托管标识不适用于 Init 容器。 使用工作负载配置文件消耗环境,或将依赖标识的工作移动到主容器。
Init 容器映像拉取失败 与图像拉取失败相同的症状 应用相同的注册表身份验证和映像标记检查。
操作顺序:密钥尚未同步 Init 容器读取空机密 密钥保管库 机密同步是异步进行的。 如果初始化容器依赖 密钥保管库 引用的机密,则该机密值可能尚不可用。 使用直接密钥来满足初始化时的依赖项,或添加重试逻辑。

健康探测器故障

当修订成功部署,但被探测检查判定为运行不正常或降级时,使用本节内容。

症状

  • 修订版本已完成预配,但运行状态为 Degraded
  • 系统日志显示包含探测失败详细信息的 Unhealthy 事件。
  • 该应用在本地可以正常运行,但在 ACA 中未通过运行状况检查。

查看位置:探测运行状况诊断

在 Azure 门户中,转到容器应用>应用程序>容器>运行状况探测(验证探测配置)。 然后转到 “容器应用>修订”,选择修订,然后打开“事件”。

# Check the revision's probe configuration
az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> \
  --query "properties.template.containers[].probes" -o json

# System logs for probe failure events
az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50

常见原因和解决方法

原因 错误信号 解决方法
探测端口与应用端口不匹配 探测返回连接被拒绝 设置探测端口以匹配应用的侦听端口和入口 targetPort
应用启动时间过长 在应用准备就绪之前探测失败,修订将 Degraded 增加运行情况和就绪情况探测的 initialDelaySeconds。 常见于Java应用。
探测路径返回非 200 探测失败并出现 HTTP 错误 确保健康检查端点返回 200 状态码。 对于 HTTP 探测,请验证路径是否存在并正确响应。
应用仅在 init 后绑定时进行 TCP 探测 探针在应用开始监听之前连接 使用具有较高 failureThreshold 的启动探测,给应用留出绑定端口的时间。

默认探测值

启用入口且未配置探测时,ACA 会应用以下默认值:

财产 Startup 活跃性 就绪情况
Protocol TCP TCP TCP
港口 入口目标端口 入口目标端口 入口目标端口
初始延迟 1s 1s 3 秒
期限 1s 1s 5s
失败阈值 240 48 不适用

入口和流量路由问题

当应用正在运行,但由于入口或修订版本流量设置不正确而导致请求失败时,请使用本节。

症状

  • 应用正在运行且运行正常,但 HTTP 请求返回错误(404,502)或无响应。
  • 该应用通过 az containerapp exec 可以正常工作,但通过公共 URL 则无法正常工作。

查看位置:流入量和流量诊断

在Azure门户中,转到“容器应用>设置>入口”。 然后转到容器应用>应用程序>修订(检查流量拆分)。

# Check ingress configuration and traffic split
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "{ingress:properties.configuration.ingress, latestReady:properties.latestReadyRevisionName}" -o json

# Verify the FQDN
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --query "properties.configuration.ingress.fqdn" -o tsv

常见原因和解决方法

原因 错误信号 解决方法
未启用 Ingress 未分配 FQDN,无法访问应用 启用入口:az containerapp ingress enable -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type external --target-port 8080 --transport auto
目标端口不匹配 502 错误的网关 targetPort 设置为与你的应用监听的端口一致。
最新版本的流量权重为 0% 旧修订提供流量 更新流量分配:az containerapp ingress traffic set -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision-weight latest=100
IP 限制阻止客户端 403 检查入口设置下的 IP 安全限制。
传输错误(HTTP 与 TCP) 连接错误 验证入口类型是否与应用的协议匹配。

容器注册表身份验证

当映像拉取失败时,请使用此部分,因为应用无法向容器注册表进行身份验证。

症状

  • 部署失败,提示 UNAUTHORIZED: authentication required
  • 此错误通常会屏蔽其他问题(如映像标记错误),因为注册表拒绝请求,然后才能检查标记。

在哪里查看:注册表身份验证诊断

在Azure门户中,转到“容器应用>设置>容器”(检查注册表设置)。 然后转到 容器应用>诊断并解决问题,并搜索“注册表”。

# Check configured registries
az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> \
  --query "properties.configuration.registries" -o json

# Verify ACR credentials work
az acr login --name <AZURE_CONTAINER_REGISTRY_NAME>
docker pull <AZURE_CONTAINER_REGISTRY_NAME>.azurecr.io/<REPOSITORY_NAME>:<TAG>

常见原因和解决方法

原因 错误信号 解决方法
未配置注册表凭据 UNAUTHORIZED 添加注册表凭据: az containerapp registry set -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --server <AZURE_CONTAINER_REGISTRY_NAME>.azurecr.io --identity system
在 ACR 上禁用管理员凭据 通过管理员用户使用 UNAUTHORIZED 启用管理员用户: az acr update -n <AZURE_CONTAINER_REGISTRY_NAME> --admin-enabled true. 首选:改用托管标识进行 ACR 拉取。
托管标识缺少 AcrPull 角色 UNAUTHORIZED 分配 AcrPull 角色: az role assignment create --role AcrPull --assignee <PRINCIPAL_ID> --scope <ACR_RESOURCE_ID>
错误的服务器主机名 name unknown 验证注册表服务器是否与 ACR 匹配: <your-acr>.azurecr.io

诊断工作流摘要

不确定失败的情况时,请使用此序列:

  1. 运行 az containerapp show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o json。 检查provisioningStateprovisioningErrorlatestRevisionName

  2. 运行 az containerapp revision list -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> -o table。 如果列表为空,则失败是映像拉取或模板验证问题(映像拉取失败和容器注册表身份验证)。 如果存在修订,请继续执行步骤 3。

  3. 运行 az containerapp revision show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --revision <REV> -o json。 检查 healthStaterunningStaterunningStateDetailsprovisioningError

  4. 运行 az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --type system --tail 50 以查看平台级事件,例如探测失败、标识错误和机密同步问题。

  5. 运行 az containerapp logs show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> --tail 100 以查看应用程序 stdout/stderr,包括堆栈跟踪、配置错误和连接失败。

  6. 运行 az containerapp identity show -g <RESOURCE_GROUP_NAME> -n <CONTAINER_APP_NAME> 以验证标识配置(如果前面步骤中出现与身份验证相关的错误)。

在门户中使用“诊断并解决问题”功能

容器应用门户包含一个诊断和解决问题边栏,并提供自动诊断功能:

  1. 在 Azure 门户中转到你的容器应用。
  2. 从左侧导航中选择“ 诊断”并解决问题
  3. 使用搜索框查找特定诊断(例如,“映像拉取”、“运行状况探测”或“流入量”)。
  4. 选择故障排除类别图块,开始引导式分析。

此边栏选项卡是引导式诊断的建议起点。 本文中可能未涵盖每个方案,但会针对常见问题提供自动检查。

用于更深入调查的 Log Analytics 查询

如果 CLI 输出和门户诊断不够,请直接在 Log Analytics 中查询基础日志。 以下两个查询涵盖了平台级故障和入口级 HTTP 错误的最常见起点。

查找系统级故障

ContainerAppSystemLogs_CL
| where RevisionName_s == "<REV>"
| where Log_s contains "BackOff" or Log_s contains "Failed" or Log_s contains "Error"
  or Reason_s == "Unhealthy"
| project TimeGenerated, Reason_s, Log_s
| order by TimeGenerated desc
| take 50

此查询显示图像拉取错误、探测失败、预配错误和其他平台事件。

查找 HTTP 错误(需要启用 HTTP 日志)

入口层会生成 HTTP 日志,而你可以选择启用它们。 通过容器应用托管环境中的Azure Monitor诊断设置启用这些日志。 启用它们后,表ContainerAppHTTPLogs将显示在Log Analytics中。 可能需要几分钟才能显示该表。

ContainerAppHTTPLogs
| where TimeGenerated > ago(1h)
| where StatusCode >= 400
| project TimeGenerated, ContainerAppName, RevisionName, Method, Path,
  StatusCode, ResponseCodeDetails, RequestDuration, RequestId
| order by TimeGenerated desc
| take 100

此查询筛选入口层 HTTP 日志,以仅显示过去一小时内失败的请求(状态代码 400 或更高版本)。 它返回时间戳、应用和修订名称、HTTP 方法和路径、错误状态代码、一个ResponseCodeDetails字段,该字段指示错误源自容器()还是平台(via_upstreamroute_not_foundconnection_timeout请求持续时间以及可用于与应用程序日志关联的唯一请求 ID)。

若要了解更多查询(包括慢速请求分析、按修订版本统计的错误率、单个请求跟踪以及失败次数最多的终结点),请参阅使用 Log Analytics 监视 Azure 容器应用 中的日志