502 网关无效 - 解压缩失败响应

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

问题

客户端应用收到 HTTP 状态代码 502 Bad Gateway 且错误代码为 messaging.adaptors.http.flow.DecompressionFailureAtResponse，作为对 API 调用的响应。

错误消息

客户端应用会获得以下响应代码： 

HTTP/1.1 502 Bad Gateway

此外，您可能还会看到类似于如下所示的错误消息： 

{
   "fault":{
      "faultstring":"Decompression failure at response",
      "detail":{
         "errorcode":"messaging.adaptors.http.flow.DecompressionFailureAtResponse"
      }
   }
}

可能的原因

只有在以下情况下，才会发生此错误：

  • HTTP 响应（来自后端/目标服务器）标头 Content-Encoding 中指定的编码有效且 受 Apigee Edge 支持，

    • 但是

  • 后端/目标服务器作为 HTTP 响应的一部分发送的载荷格式与 Content-Encoding 标头中指定的编码格式不匹配

这是因为 Apigee Edge 无法使用指定编码对载荷进行解码，因为载荷格式与 Content-Encoding 标头中指定的编码格式不同。

下面列举了一些受支持的 Content-Encoding 值示例，以及在这些情况下 Apigee Edge 对载荷表示法的预期：

场景 Content-Encoding 载荷表示法
单一编码 gzip

Unix gzip 格式。

请参阅 RFC1952 GZIP 格式。
单一编码 压缩

此格式搭配使用 zlib 结构和 deflate 压缩算法。

请参阅 RFC1950 和 RFC1951.
多种编码

多种编码

例如，如果编码进行了两次，则可能发生以下情况：

  • gzip、deflate
  • gzip、gzip
  • deflate、gzip
  • deflate、deflate
 按照标头中显示的指定顺序对载荷应用多种编码。

导致此错误的可能原因如下：

原因 说明 适用的问题排查说明
响应载荷格式与 Content-Encoding 不匹配 后端/目标服务器发送的响应载荷格式未编码或与 Content-Encoding 标头中指定的编码不匹配。 Edge 公有云和私有云用户

常见诊断步骤

使用以下工具/技巧之一来诊断此错误：

API 监控

要使用 API Monitoring 诊断错误，请执行以下操作：

  1. 以拥有 适当角色的用户身份 登录 Apigee Edge 界面。

  2. 切换到您要调查问题的组织。

  3. 前往 Analyze > API Monitoring > Investigate 页面。
  4. 选择您发现错误的具体时间范围。
  5. 确保将代理过滤器设置为全部。
  6. 根据时间绘制故障代码。

  7. 选择具有错误代码 messaging.adaptors.http.flow.DecompressionFailureAtResponse 的单元格，如下所示：

    （ 查看大图）

  8. 错误代码 messaging.adaptors.http.flow.DecompressionFailureAtResponse 的相关信息如下所示：

    （ 查看大图）

  9. 点击查看日志，然后展开失败并显示 502 错误的行。

    （ 查看大图）

  10. 在日志窗口中，请注意以下详细信息：
    • 状态代码：502
    • 错误来源：target
    • 错误代码：messaging.adaptors.http.flow.DecompressionFailureAtResponse。
  11. 如果故障来源的值为 target，则表示响应载荷格式与后端服务器的响应标头 Content-Encoding 中指定的 支持的编码不匹配。

跟踪工具

如需使用跟踪工具诊断错误，请执行以下操作：

  1. 启用跟踪会话，并执行以下任一操作：
    1. 等待 502 Bad Gateway 错误发生，或者
    2. 如果您可以重现问题，请发出 API 调用并重现 502 Bad Gateway。

  2. 确保已启用 Show all FlowInfos：

  3. 选择其中一个失败响应并检查跟踪记录。
  4. 浏览跟踪记录的不同阶段，并找到发生故障的位置。

  5. 通常，您会在从目标服务器收到响应阶段后立即在流程中发现错误，如下所示：

    （ 查看大图）

  6. 请注意跟踪记录中的属性值：

    • 内容编码：gzip
    • 响应内容正文：{"fault":{"faultstring":"Decompression failure at response","detail":{"errorcode":"messaging.adaptors.http.flow.DecompressionFailureAtResponse"}}}

  7. 在 Response Received from target server 阶段之后紧接着转到错误阶段：

    （ 查看大图）

    请注意以下属性：

    • 错误：Decompression failure at response
    • error.class:：com.apigee.errors.http.server.BadGateway

    • error.cause:：Not in GZIP format

      error.cause 声明响应载荷不是 GZIP 格式。这意味着 Apigee Edge 希望响应载荷采用 Content-Encoding 标头中指定的 GZIP 格式（在上一步中确定）。因此，Apigee Edge 无法使用 gzip 解压缩载荷，并返回错误 Decompression failure at response。

    请注意，在这种情况下，来自目标/后端服务器的响应为 200；但是，客户端应用将收到 502 响应，因为 Apigee Edge 会返回此错误。

  8. 进入跟踪记录中的 Response Sent to Client 阶段，然后点击该阶段。

    （ 查看大图）

    请注意跟踪记录中的以下详细信息：

    • 状态代码：502 Bad Gateway。
    • 错误内容： {"fault":{"faultstring":"Decompression failure at response","detail":{"errorcode":"messaging.adaptors.http.flow.DecompressionFailureAtResponse"}}}

  9. 进入跟踪记录中的 AX（已记录的 Analytics 数据）阶段并点击该阶段。

  10. 向下滚动到 Phase Details（阶段详细信息）和 Error Headers（错误标头）部分，并确定 X-Apigee-fault-code 和 X-Apigee-fault-source 的值，如下所示：

    （ 查看大图）

  11. 您将看到 X-Apigee-fault-code 和 X-Apigee-fault-source 的值为 messaging.adaptors.http.flow.DecompressionFailureAtResponse 和 target，这表明响应载荷格式与 Content-Encoding 标头中指定的编码不匹配。
    响应标头 值
    X-Apigee-fault-code messaging.adaptors.http.flow.DecompressionFailureAtResponse
    X-Apigee-fault-source target

NGINX

如需使用 NGINX 访问日志诊断错误，请执行以下操作：

  1. 如果您是 Private Cloud 用户，则可以使用 NGINX 访问日志来确定有关 HTTP 502 错误的关键信息。

  2. 检查 NGINX 访问日志：

    /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

    其中：将 ORG、ENV 和 PORT# 替换为实际值。

  3. 搜索以查看在特定持续时间内是否存在任何 502 错误（如果问题是在过去发生的），或者是否有任何响应仍然失败并显示 502。

  4. 如果您确实发现任何 502 错误且 X-Apigee-fault-code 与 messaging.adaptors.http.flow.DecompressionFailureAtResponse 的值匹配，请确定 X-Apigee-fault-source 的值。

    NGINX 访问日志中的 502 错误示例：

    NGINX 访问日志中的上述示例条目具有 X-Apigee-fault-code 和 X-Apigee-fault-code 的以下值：

    响应标头 值
    X-Apigee-fault-code messaging.adaptors.http.flow.DecompressionFailureAtResponse
    X-Apigee-fault-source target

原因：响应载荷格式与 Content-Encoding 不匹配

默认情况下，如果响应标头 Content-Encoding 包含有效且 支持的编码，则 Apigee Edge 始终会解压缩载荷。因此，响应载荷的格式应与响应标头 Content-Encoding 中指定的编码一致。如果不相符，会收到此错误。

诊断

  1. 按照常见诊断步骤中所述，使用 API 监控、Trace 工具或 NGINX 访问日志确定观察到的错误的故障代码和故障来源。
  2. 如果故障代码为 messaging.adaptors.http.flow.DecompressionFailureAtResponse 且故障来源的值为 target，则表示后端/目标服务器发送的响应载荷格式与响应标头 Content-Encoding 中指定的 支持编码不匹配。

  3. 您可以使用以下某种方法在 HTTP 响应中确定不匹配情况：

    错误消息

    如需使用错误消息进行验证，请执行以下操作：

    1. 如果您有权访问从 Apigee Edge 收到的完整错误消息，请参阅 faultstring。

      示例错误消息：

      "faultstring":"Decompression failure at response"
    2. 在上述错误消息中，它显示了 "Decompression failure at response"，这表示无法使用 Content-Encoding 标头中指定的编码解压缩响应。

    跟踪记录

    如需使用 Trace 进行验证，请执行以下操作：

    1. 按照常见诊断步骤中的说明，使用 Trace 确定 Content-Type 和 error.cause。

    2. 示例轨迹中的值如下所示：

      • 内容编码：gzip
      • error.cause:：Not in GZIP format

      响应标头 Content-Encoding 中的值是 gzip；但是，响应载荷不是 GZIP 格式（如 error.cause 所示）。因此，Apigee Edge 会返回 502 Bad Gateway 和错误代码 messaging.adaptors.http.flow.DecompressionFailureAtResponse。

    实际请求

    如需使用实际请求进行验证，请执行以下操作：

    如果您有权访问向目标/后端服务器应用发出的实际请求，请执行以下步骤：

    1. 如果您是公有云/私有云用户，请从后端服务器本身或您获准向后端服务器发出请求的任何其他机器中直接向后端服务器发出请求。
    2. 如果您是 Private Cloud 用户，还可以从某个消息处理器向后端服务器发出请求。
    3. 检查后端服务器发送的响应并确定在响应标头 Content-Encoding. 中传递的值
    4. 确定作为请求一部分发送的载荷格式。
    5. 如果 Content-Encoding 标头的值在 支持的编码列表中，但响应载荷的格式与 Content-Encoding 标头中指定的编码不匹配，那么这就是问题的原因。

      示例：

      curl -v https://HOSTALIAS/test


      ***trimmed***
>
< HTTP/1.1 200 OK
< Accept-Ranges: bytes
< Content-Encoding: gzip
< Date: Mon, 02 Aug 2021 08:17:35 GMT
< Transfer-Encoding: chunked
<
< response_payload.zip Response Body(not in GZIP format)>

      上面的示例响应会将值 gzip 发送到 Content-Encoding 标头，该标头是 Apigee Edge 中 支持的编码。不过，response_payload.zip 是以 zip 文件的形式发送的。因此，此响应将失败并显示 502 Bad Gateway 错误，错误代码为：messaging.adaptors.http.flow.DecompressionFailureAtResponse。

    消息处理器日志

    如需使用消息处理器日志进行验证，请执行以下操作：

    如果您是 Private Cloud 用户，则可以使用消息处理器日志来确定有关 HTTP 502 错误的关键信息。

    1. 检查消息处理器日志：

      /opt/apigee/var/log/edge-message-processor/logs/system.log

    2. 搜索以查看在特定持续时间内是否存在任何 502 错误（如果问题是在过去发生的），或者是否有任何响应仍然失败并显示 502。您可以使用以下搜索字符串：

      grep -ri "ZipException"

    3. 您会发现，system.log 中的一些行与以下内容类似：

      情景 #1

      场景 1：当 API 响应包含标头 Content-Encoding: gzip 时

      2021-08-02 06:50:25,433  NIOThread@2 ERROR HTTP.CLIENT -
HTTPClient$Context.onInputException() :  ClientInputChannel(ClientChannel[Connected:
Remote:3.8.1.1:9000 Local:10.0.115.32:41298]@38140 useCount=1 bytesRead=0
bytesWritten=203 age=469ms  lastIO=0ms  isOpen=true).onExceptionRead exception: {}
java.util.zip.ZipException: Not in GZIP format
---trimmed--
2021-08-02 06:50:25,433  NIOThread@2 INFO  HTTP.CLIENT -
HTTPClient$Context.logContextDetails() : Request details : host=null
path=/folder/testFile method=GET. Channel details : Bytes read=0
2021-08-02 06:50:25,434  NIOThread@2 ERROR ADAPTORS.HTTP.FLOW -
AbstractResponseListener.onException() : AbstractResponseListener.onError(HTTPResponse@4806fdab, Not in GZIP format)
2021-08-02 06:50:25,434  NIOThread@2 INFO  HTTP.SERVICE -
ExceptionHandler.handleException() : Exception
java.util.zip.ZipException: Not in GZIP format
occurred while writing to channel null
2021-08-02 06:50:25,434  NIOThread@2 INFO  HTTP.SERVICE -
ExceptionHandler.handleException() : Exception trace:
java.util.zip.ZipException: Not in GZIP format

      上述错误消息中的 java.util.zip.ZipException: Not in GZIP format 行表示虽然 Content-Encoding 指定为 gzip，但响应载荷并未以 GZIP 格式发送。因此，Apigee Edge 会抛出异常，并向客户端应用返回包含错误代码 messaging.adaptors.http.flow.DecompressionFailureAtResponse 的 502 状态代码。

      情景 #2

      场景 2：当 API 响应包含标头 Content-Encoding: deflate 时

      2021-08-02 06:35:21,215  NIOThread@0 ERROR HTTP.CLIENT -
HTTPClient$Context.onInputException() :  ClientInputChannel(ClientChannel[Connected:
Remote:3.8.1.1:9000 Local:192.168.194.140:35224]@36014 useCount=1 bytesRead=0
bytesWritten=202 age=439ms  lastIO=2ms  isOpen=true).onExceptionRead exception: {}
java.util.zip.ZipException: incorrect header check
---trimmed----
Caused by:
java.util.zip.DataFormatException: incorrect header check
---trimmed---
2021-08-02 06:35:21,215  NIOThread@0 INFO  HTTP.CLIENT -
HTTPClient$Context.logContextDetails() : Request details :
host=null path=/folder/testFile method=GET. Channel details : Bytes read=0
2021-08-02 06:35:21,216  NIOThread@0 ERROR ADAPTORS.HTTP.FLOW -
AbstractResponseListener.onException() : AbstractResponseListener.onError(HTTPResponse@3966e277,
incorrect header check)
2021-08-02 06:35:21,216  NIOThread@0 INFO  HTTP.SERVICE -
ExceptionHandler.handleException() : Exception
java.util.zip.ZipException: incorrect header check occurred while writing to channel null
2021-08-02 06:35:21,217  NIOThread@0 INFO  HTTP.SERVICE -
ExceptionHandler.handleException() : Exception trace:
java.util.zip.ZipException: incorrect header check

      上述错误消息中的 java.util.zip.ZipException: incorrect header check 和 Caused by: java.util.zip.DataFormatException: incorrect header check 行表示响应载荷并非以 deflate 格式发送，且与 deflate 的 Content-Encoding 标头中指定的编码不匹配。因此，Apigee Edge 会抛出异常，并向客户端应用返回包含错误代码 messaging.adaptors.http.flow.DecompressionFailureAtResponse 的 502 状态代码。

分辨率

  1. 如果 Apigee Edge 和后端服务器中的 API 代理流程不需要压缩的响应载荷，则不要传递标头 Content-Encoding。如果需要压缩响应载荷，请转到第 2 步。
  2. 如果需要压缩响应载荷，请确保后端服务器始终发送以下内容：
    • 任何 支持的编码作为响应中 Content-Encoding 标头的值
    • Apigee Edge 中支持的格式的响应载荷与 Content-Encoding 标头中指定的编码格式一致
  3. 在上述示例中，响应载荷采用 ZIP 格式，但响应标头指定了 Content-Encoding: gzip。若要解决此问题，您可以采用 Content-Encoding: gzip 格式发送响应标头，并以 gzip 格式发送响应载荷： 
    curl -v https://HOSTALIAS/v1/test

    >
< HTTP/1.1 200 OK
< Accept-Ranges: bytes
< Content-Encoding: gzip
< Date: Mon, 02 Aug 2021 08:17:35 GMT
< Transfer-Encoding: chunked
<
< response_payload.gz Response Body(in GZIP format)>

规范

根据以下 RFC 规范，Apigee Edge 返回状态代码 502 Bad Gateway 和错误代码 messaging.adaptors.http.flow.DecompressionFailureAtResponse：

规范
RFC 7231，第 6.5.1 节
RFC 7231，第 3.1.2.2 节

如果您仍然需要 Apigee 支持部门的任何帮助，请参阅 必须收集诊断信息。

必须收集的诊断信息

收集以下诊断信息，然后联系 Apigee Edge 支持团队：

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

  • 组织名称
  • 环境名称
  • API 代理名称
  • 完成用于重现 502 错误的 curl 命令
  • API 响应的跟踪文件

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

  • 观察到失败响应的完整错误消息
  • 环境名称
  • API 代理软件包
  • API 响应的跟踪文件

  • NGINX 访问日志 /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

    其中：将 ORG、ENV 和 PORT# 替换为实际值。

  • 消息处理器系统日志 /opt/apigee/var/log/edge-message-processor/logs/system.log