排查 Azure 容器应用中的启动失败

首次将容器化应用程序部署到 Azure 容器应用有时可能会导致应用无法启动。 使用本指南来了解如何诊断和修复容器未启动时的常见问题。

检查部署状态和修订状态

验证容器应用部署的状态。

1. 打开 Azure 门户，然后转到容器应用。

2. 在“应用”下，选择“修订和副本”。

3. 在列表中查找修订，并查看“运行状态”。

   如果看到“失败”或“降级”状态，则部署未成功。 若要查找部署失败问题，可以查看应用程序和系统日志。

查看应用程序和系统日志

如果容器未启动，日志是诊断信息的最佳来源。 有两种类型的日志、系统和应用程序日志。 系统日志显示 Azure 容器应用的平台活动，其中应用程序日志显示记录到 stdout 和 stderror 的内容。

首先查看以下消息之一的系统日志：

消息	含义
装载卷 <VOLUME_NAME> 时出错。	系统尝试装载卷时遇到问题。
预配修订 <REVISION_NAME> 时出错。 ErrorCode: [ErrImagePull]	由于拉取容器映像时出错，系统无法启动修订。 此错误可能来自无法访问的映像或错误的映像引用。
预配修订 <REVISION_NAME> 时出错。 ErrorCode: [Time-out]	由于容器中长时间的启动时间或问题，可能会超时。
预配修订 <REVISION_NAME> 时出错。 ErrorCode: [ContainerCrashing]	修订的容器反复崩溃。
错误：入口路由未就绪	系统遇到入口路由未就绪的问题，导致副本修订失败。
已超出部署进度截止时间。 0/1 副本准备就绪。	部署超出了进度允许的时间，导致没有副本准备就绪。 这种情况通常表示容器启动或运行状况检查出现问题。
请求返回状态 403	容器应用终结点响应 HTTP 错误 403（访问被拒绝）的请求，表明存在潜在的网络配置问题。
错误：ContainerCrashed	容器崩溃，可能是应用程序错误或配置错误。
提取缩放程序指标时出错	确保应用程序可以连接到缩放信号的源。

使用日志线索，检查容器无法运行的原因：

可能的原因	DESCRIPTION	可能的修复方法
映像或注册表问题	如果日志指示无法拉取映像，例如“映像拉取失败”或身份验证错误，则容器从未启动。 确保容器应用配置中的映像名称和标记正确。 如果使用专用注册表或 Azure 容器注册表 (ACR)，请验证 Azure 容器应用是否可以访问注册表。 对于 ACR，可能需要启用托管标识身份验证或提供注册表凭据。	确认映像存在于指定的标记处，并且可访问。 可以从计算机尝试手动 docker pull <IMAGE> 来验证凭据。 或者，尝试从内部部署调试容器并尝试连接。
应用程序崩溃，退出代码不为 0	如果容器使用非零退出代码退出，则应用程序代码中未经处理的异常或错误通常是问题。 检查在崩溃之前，应用程序日志中是否有任何异常或错误消息。 常见原因包括缺少文件或依赖项、运行时异常或配置错误的框架。	如果可能，请在本地重现问题。 使用 Docker (docker run --rm <IMAGE>) 在本地运行同一映像，以查看应用程序是否退出或出错。修复任何应用程序级错误（例如，在映像中包含所有必要的依赖项并处理所有异常），然后重新部署容器。
启动命令和入口点	如果重写启动命令，或者 Dockerfile 的入口点未正确启动应用，则容器可以启动，然后立即退出。 默认情况下，Azure 容器应用使用映像中定义的入口点/CMD 运行容器。 验证映像的启动命令是否会实际启动预期服务。 例如，对于 Node.js 应用，请确保 Docker CMD 运行服务器（而不仅仅是退出）。	仔细检查 Dockerfile 的入口点/CMD。 如果在 Azure 中使用自定义命令（通过 YAML 或 CLI），请确保正确。 可以通过 CLI 或 Azure 门户更新容器应用的启动命令。 在门户中，转到容器，选择“编辑容器”，然后编辑命令和参数。
运行状况探测失败	如果启用了 HTTP 入口且未指定自定义探测，Azure 容器应用会自动添加实时和就绪情况探测。 常见的方案是应用实际正在运行，但运行状况检查失败，导致平台重启容器或将修订标记为不正常。 例如，如果应用侦听非默认端口或启动时间较长，则默认探测可能会失败。	确保容器的目标端口与应用程序侦听的端口匹配。 如果应用需要更多时间来初始化，请配置启动或运行情况探测，并延长初始延迟。 在 Azure 门户中，查看“容器”>“运行状况探测”，或通过 CLI YAML。 如果应用不提供 HTTP（例如后台辅助角色），请考虑禁用入口或使用内部入口，以便不强制实施 HTTP 探测。 或者，暂时关闭外部入口可以阻止持续重启的容器。
缩放程序信号连接	如果使用缩放规则缩放应用程序，请确保应用程序可以连接到缩放信号的源。 此消息表示需要通过网络访问任何数据库、事件中心或其他容器应用，并可访问查询。	在本地运行容器，先验证服务在开发上下文中是否可访问。
资源约束（内存/CPU）	容器应用运行时可以终止内存不足或 CPU 资源的容器。 检查系统日志中是否存在内存不足 (OOM) 错误或限制。	将应用的资源需求与为容器应用配置的限制进行比较。

验证环境变量和配置

配置不当的设置是启动问题的常见原因，尤其是在从本地开发迁移到 Azure 时：

• 环境变量：确保在容器应用配置中设置所有必需的环境变量。 缺少环境变量（例如，应用所需的数据库连接字符串或 API 密钥）可能会导致应用在启动时崩溃。

• 机密引用：如果配置了机密（单独存储的安全值），请确保容器的环境变量正确引用机密。 容器设置中的机密名称必须与机密下定义的名称匹配。 如果一个机密在环境变量中没有相应的引用（或者反过来，环境变量中有引用但没有对应的机密），这意味着你的应用程序可能无法获取到它所需要的值。

• 配置文件和应用设置：如果应用程序依赖于配置文件，请确保它们包含在映像和正确的路径中。 有时，由于本地配置文件，应用可能会在本地启动，但该文件未复制到 Docker 映像中。 重新生成包含这些资源的映像。 另请检查任何特定于框架的设置（例如，ASP.NET Core 可能需要 ASPNETCORE_URLS，或者 Django 可能需要某些环境变量），并确保为容器设置它们。

• 重复或无效的设置：如果存在配置错误（例如重复的环境变量名称），Azure 容器应用（尤其是通过 IaC 模板部署时）可能无法启动。

检查网络和入口设置

网络配置错误可以防止容器启动或变得可访问：

• 入口配置：如果应用应在外部访问，则应启用并适当设置入口（外部用于公共 HTTP 访问或内部仅用于环境内部访问）。 验证目标端口是否正确。 目标端口必须与应用程序的侦听端口匹配。

• VNet 集成和 DNS：如果容器应用环境与虚拟网络集成，请确保其具有对所需终结点的 DNS 访问权限。 一个常见问题是使用自定义 DNS 或受限的出站访问来阻止容器拉取映像或访问外部服务。 例如，如果使用专用 ACR，请确认环境可以解析并连接到注册表。 可能需要设置环境的 DNS 设置或出站流量规则，以允许注册表和 Internet 访问。 如果使用托管标识，令牌终结点 login.microsoft.com 或 <REGION>.login.microsoft.com 需要是可访问的，则可能还需要更新 DNS 设置。 有关需要访问哪些主机的详细信息，请参阅使用 Azure 防火墙配置 UDR。

• 外部依赖项：如果应用程序需要调用外部服务（例如数据库、API 或缓存），请验证对资源的网络访问权限。 检查是否已正确设置所需的服务连接器或虚拟网络对等互连。 例如，如果应用应该连接到虚拟网络中的 Azure 数据库，请确保容器应用位于同一虚拟网络中或具有适当的防火墙规则。 与外部资源连接失败有时会导致应用在启动时挂起或引发异常。 该解决方案可能正在配置环境的出站流量或调整目标服务的防火墙规则。

防止启动问题的最佳做法

解决直接问题后，请考虑以下做法，以避免将来出现类似的部署问题：

• 使用容器设置在本地测试：始终在本地（或在过渡环境中）测试容器映像，其中包含计划用于生产中的相同环境变量和配置。 这种做法可以捕获在部署之前缺少依赖项或配置的问题。 如果映像无法立即在计算机上运行或退出，请先修复此问题。 确保容器按预期运行 Docker 运行有助于将应用程序问题与 Azure 配置问题隔离开来。

• 确保容器映像辅助功能：使用一致的映像命名和版本控制（包括标记），并避免将 latest 标记用于生产部署。 如果使用 ACR，请启用持续部署或使用 Azure 容器应用内置注册表集成来最大程度地减少身份验证问题。 定期验证容器应用的托管标识或凭据是否可以从注册表拉取（尤其是在任何密码或令牌轮换之后）。

• 包括所有必需配置：确保容器中提供所有必要的应用设置。 这种做法包括环境变量、机密值、配置文件和任何启动命令参数。 使用基础结构即代码（Azure CLI、Bicep 或 ARM 模板）部署容器应用很有帮助，以便配置可重复且不容易出现手动错误（例如拼写错误或缺少设置）。 例如，仔细检查是否在容器应用设置中考虑应用的 .env 文件中的所有密钥。

• 适当的运行状况探测配置：配置适合应用程序行为的运行状况探测。 如果你知道你的应用需要时间来预热，请设置启动或准备情况探测，并有充足的初始延迟，以防止过早重启。 如果应用在 HTTP 终结点上未响应，请禁用入口或使用 TCP 运行状况检查，而不是 HTTP。 定义实时探测以自动从挂起的进程恢复，但不要太积极，以免它们根本不允许应用完全启动。

• 监视资源使用情况：选择符合应用需求的 CPU 和内存分配。 监视使用情况（通过 Azure Monitor 中的容器应用指标），以达到峰值或稳步攀升。 如果应用容易遇到内存不足错误或被终止，请增大内存限制或调查应用程序中是否存在内存泄漏。 同样地，确保没有达到 CPU 限制，因为这可能会减慢启动速度。