来自后端服务器的 504 网关超时

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

问题

客户端应用在响应 API 调用时收到 HTTP 状态代码 504，并显示消息“网关超时”。

此错误响应表示客户端在执行 API 调用期间未及时收到来自 Apigee Edge 或后端服务器的响应。

错误消息

客户端应用会收到以下响应代码： 

HTTP/1.1 504 Gateway Timeout

此代码后面可能会显示类似于以下内容的错误消息： 

<html>
<head><title>504 Gateway Timeout</title></head>
<body bgcolor="white">
<center><h1>504 Gateway Timeout</h1></center>
</body>
</html>

什么原因会导致网关超时？

通过 Apigee Edge 发出的 API 请求的典型路径是客户端 -> 路由器 -> 消息处理器 -> 后端服务器，如下图所示：

API 请求路径

客户端应用、路由器和消息处理器配置了合适的超时值。Apigee Edge 期望在基于超时值的时间段内针对每个 API 请求获得响应。如果未在指定的时间段内收到响应，则返回 504 网关超时响应。

可能的原因

在 Apigee Edge 中，后端服务器返回 504 Gateway Timeout 响应的常见原因是：

原因 说明 问题排查说明
后端服务器返回 504 网关超时 后端服务器超时，并向消息处理器返回 504 Gateway Timeout 响应。 Edge Private 和 Public Cloud 用户

后端服务器返回 504 网关超时错误

后端服务器可能会返回 HTTP 响应代码 504 Gateway Timeout。

诊断

本部分介绍了如何正确诊断 504 网关超时错误。下面列出了私有云用户和公共云用户的操作步骤。

程序 1：使用 Trace（私有云和公有云用户）

  1. 在 Apigee 界面中为受影响的 API 启用 Trace。
  2. 向后端服务器发送请求。
  3. 如果失败的 API 请求在跟踪中显示来自后端服务器的 504 响应，则 504 网关超时的根本原因是后端服务器。
  4. 如需确定响应时间，请点击 Trace 中的从目标服务器收到响应阶段。在所示示例中，经过的时间为 60004 毫秒：

    界面中的阶段详细信息

    “阶段详情”部分提供了更多信息：

    • 它突出显示了从后端服务器收到的 504 Gateway Timeout 响应。
    • 响应内容部分会显示来自后端服务器的完整响应正文。如前所述，响应载荷的格式和内容可能会因后端服务器实现而异。
    • 响应标头 > 服务器部分可能会指明响应的来源。
  5. 如需查看 Google Analytics 数据并确认诊断结果，请点击 Trace 中的 Analytics Data Recorded（已记录 Google Analytics 数据）阶段，如下图所示：

    来自轨迹的分析详细信息

    “阶段详细信息”的响应标头部分会显示 X-Apigee-fault-code 和 X-Apigee-fault-source 的值，如下图所示：

    界面中的分析阶段详细信息

    如果这些字段包含下表所示的值，则 504 错误响应源自后端服务器：

    响应标头 值
    X-Apigee-fault-source target
    X-Apigee-fault-code messaging.adaptors.http.flow.ErrorResponseCode
  6. 检查是否存在 代理链。请按照以下步骤确定后端服务器是否在 Apigee 中调用另一个代理：
    1. 返回到已向目标服务器发送请求阶段，然后点击 Show Curl 按钮以查看后端服务器主机别名。
    2. 如果后端服务器主机别名指向虚拟主机别名，则存在代理链。针对每个链式代理重复上述步骤，以诊断 504 网关超时错误响应的原因。如果链式代理在请求/响应周期的其他阶段发生 504 网关超时，可以使用 此剧本进行诊断。
    3. 如果后端服务器主机别名指向后端服务器，请继续执行解决方案。

方法 2：直接调用后端服务器 API（公共云和私有云用户）

直接调用后端服务器，以确认通过 Apigee Edge 发出请求时是否也会遇到相同的 504 Gateway Timeout 响应行为。

  1. 确保您拥有所有必需的标头、查询参数和凭据，以便作为请求的一部分传递给后端服务器。
  2. 如果后端服务可公开访问，则可以使用 curl 命令、Postman 或任何其他 REST 客户端直接调用后端服务器 API。
  3. 如果后端服务器只能从消息处理器访问，请使用 curl 命令、Postman 或任何其他 REST 客户端直接从消息处理器调用后端服务器 API。
  4. 如果后端服务返回 504 Gateway Timeout 响应，请继续执行问题解决。

过程 3：检查 NGINX 访问日志（仅限私有云用户）

NGINX 访问日志有助于确定 504 错误响应是否由后端服务器发送。 如果问题过去曾发生过、间歇性发生或者无法在 Trace 中捕获，则此功能特别有用。请按以下步骤检查 NGINX 访问日志：

  1. 使用以下命令查看 NGINX 访问日志： 
    /opt/apigee/var/log/edge-router/nginx/ ORG ~ENV.PORT# _access_log
  2. 检查受影响的 API 代理是否存在 504 错误响应。您可以检查特定时间段（如果问题发生在过去），也可以确定请求是否仍因 504 错误响应而失败。
  3. 如果存在任何 504 错误响应，请确定该错误响应是否来自后端服务器。

    4. 下图是一个 NGINX 日志条目示例，其中显示了由目标服务器导致的 504 错误响应：

    nginx 日志示例

    如果 X-Apigee-fault-source 和 X-Apigee-fault-code 字段包含下表所示的值，则 504 响应源自后端服务器：

    响应标头 值
    X-Apigee-fault-source target
    X-Apigee-fault-code messaging.adaptors.http.flow.ErrorResponseCode
  4. 检查受影响的 API 代理，查看是否存在代理链，即后端服务器/目标端点正在调用 Apigee 中的另一个代理。如果 API 代理使用代理链 ，请针对每个链接的代理重复上述步骤，以诊断 504 Gateway Timeout 错误响应的原因。如果链式代理在其他阶段出现 504 网关超时，可以使用此剧本进行诊断。
  5. 如果没有 proxy chaining，并且 504 错误响应来自后端服务器，请继续执行问题解决。

步骤 4：使用 API 监控（仅限公共云用户）

借助 API Monitoring，您可以快速找出问题区域，以诊断错误、性能和延迟时间问题及其来源，例如开发者应用、API 代理、后端目标或 API 平台。

逐步完成一个示例场景，该场景演示了如何使用 API 监控功能排查 API 的 5xx 问题。例如，设置提醒，以便在 504 状态代码的数量超过特定阈值时通知管理员。

分辨率

使用上述诊断程序，您可以与后端服务器团队合作来修复后端服务器中的问题。这可能包括调整后端服务器中的超时或目标服务器前面的任何负载平衡器中的超时。

收集诊断信息

如果问题仍然存在，请与 Apigee 支持团队分享以下诊断信息。

如果您是公共云用户，请提供以下信息：

  • 组织名称
  • 环境名称
  • API 代理名称
  • 用于重现 504 错误响应的完整 curl 命令
  • 收到 504 网关超时错误响应的 API 请求的轨迹文件

如果您是私有云用户，请提供以下信息：

  • 失败请求的完整错误消息
  • 环境名称
  • API 代理软件包
  • 收到 504 网关超时错误响应的 API 请求的轨迹文件
  • NGINX 访问日志 
    /opt/apigee/var/log/edge-router/nginx/ ORG ~ENV.PORT# _access_log
  • 消息处理器日志 
    /opt/apigee/var/log/edge-message-processor/logs/system.log