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

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

问题

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

此错误响应表示在 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 网关超时响应的典型原因是：

原因 说明 问题排查说明
后端服务器做出 504 Gateway Timeout 响应 后端服务器超时，并向消息处理器返回“504 网关超时”响应。 Edge 私有云和公有云用户

后端服务器做出 504 Gateway Timeout 响应

后端服务器可能会以 HTTP 响应代码 504 Gateway Timeout 作为响应。

诊断

本部分介绍了如何正确诊断 504 网关超时。并列出了适用于私有云和公有云用户的过程。

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

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

    界面上的阶段详情

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

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

    跟踪记录中的分析详情

    “Phase Details”的 Response Headers 部分显示 X-Apigee-fault-code 和 X-Apigee-fault-source 的值，如下图所示：

    界面上的分析阶段详情

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

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

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

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

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

过程 3：检查 NGINX 访问日志（仅限 Private Cloud 用户）

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 目标
    X-Apigee-fault-code messaging.adaptors.http.flow.ErrorResponseCode
  4. 查看受影响的 API 代理，检查是否存在代理链接，即后端服务器/目标端点正在调用 Apigee 中的另一个代理。如果 API 代理使用的是代理链接 ，请针对每个链接的代理重复上述步骤，以诊断 504 网关超时错误响应的原因。链式代理中发生的 504 网关超时在其他阶段可以使用此 playbook 诊断。
  5. 如果没有 代理链接，并且 504 错误响应来自后端服务器，请继续执行解决方法。

过程 4：使用 API 监控（仅限公有云用户）

借助 API 监控功能，您可以快速隔离有问题的方面，从而诊断错误、性能和延迟问题及其来源，例如开发者应用、API 代理、后端目标或 API 平台。

通过一个示例场景演示了如何使用 API Monitoring 排查 API 的 5xx 问题。例如，您可以设置提醒，在 504 状态代码的数量超过特定阈值时通知管理员。

分辨率

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

收集诊断信息

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

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

  • 组织名称
  • 环境名称
  • API 代理名称
  • 用于重现 504 错误响应的完整 curl 命令
  • 包含收到 504 Gateway Timeout 错误响应的 API 请求的跟踪文件

如果您是 Private Cloud 用户，请提供以下信息：

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