500 内部服务器错误

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

视频

观看以下视频，详细了解如何解决 500 内部服务器错误。

视频 说明
简介 简要介绍了 500 内部服务器错误和可能的原因。还演示了实时 500 内部服务器错误，以及排查和解决该错误的步骤。
处理服务调出和提取变量错误 演示了由服务调出和提取变量政策导致的两个 500 内部服务器错误，并展示了如何排查和解决这些错误。
处理 JavaScript 政策错误 显示由 JavaScript 政策导致的 500 内部服务器错误，以及排查和解决此错误的步骤。
处理来自后端服务器的故障 显示了由后端服务器故障导致的 500 内部服务器错误示例，并显示了解决这些错误的步骤。

问题

客户端应用收到 HTTP 状态代码为 500 且消息为 "Internal Server Error" 的响应，以响应 API 调用。500 内部服务器错误可能是由 Edge 中任何政策的执行期间发生的错误或目标/后端服务器上的错误引起的。

HTTP 状态代码 500 是一种通用错误响应。这意味着服务器遇到了意外情况，导致无法完成请求。当没有其他合适的错误代码时，服务器通常会返回此错误。

错误消息

您可能会收到以下错误消息：

HTTP/1.1 500 Internal Server Error

在某些情况下，您可能会看到另一条包含更多详细信息的错误消息。以下是错误消息示例：

{
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.ExecutionFailed"
      },
      "faultstring":"Execution of ServiceCallout callWCSAuthServiceCallout failed. Reason: ResponseCode 400 is treated as error"
   }
}

可能的原因

500 内部服务器错误可能是由多种不同的原因造成的。在 Edge 中，根据错误发生的位置，原因可分为两大类：

原因 详细信息 针对以下情况提供了详细的问题排查步骤
Edge 政策中的执行错误 API 代理中的政策可能会因某种原因而失败。 Edge Private Cloud 和 Public Cloud 用户
后端服务器错误 后端服务器可能会因某些原因而发生故障。 Edge Private Cloud 和 Public Cloud 用户

边缘政策中的执行错误

API 代理中的政策可能会因某种原因而失败。本部分介绍如何在执行政策期间发生 500 内部服务器错误时排查问题。

诊断

面向私有云和公共云用户的诊断步骤

如果您有相应错误的轨迹界面会话，请执行以下操作：

  1. 验证错误是否由政策执行引起。如需了解详情，请参阅确定问题来源。
  2. 如果错误发生在政策执行期间，请继续。如果错误是由后端服务器引起的，请参阅后端服务器中的错误。
  3. 在轨迹中选择失败并显示 500 内部服务器错误的 API 请求。
  4. 检查请求，然后选择失败的特定政策或轨迹中紧随失败政策之后的名为“Error”的流程。
  5. 通过查看“属性”部分下的“错误”字段或“错误”内容，详细了解该错误。
  6. 根据您收集的有关错误的详细信息，尝试确定错误的原因。

仅限私有云用户的诊断步骤

如果您没有轨迹界面会话，请执行以下操作：

  1. 验证错误是否发生在政策执行期间。如需了解详情，请参阅确定问题来源。
  2. 如果错误是由政策执行引起的，请继续。如果错误发生在政策执行期间，则继续。如果错误是由后端服务器引起的，请前往后端服务器中的错误。
  3. 按照确定问题来源中的说明使用 NGINX 访问日志，以确定 API 代理中失败的政策以及唯一的请求消息 ID
  4. 检查消息处理器日志 (/opt/apigee/var/log/edge-message-processor/logs/system.log)，并在其中搜索唯一的请求消息 ID。
  5. 如果您找到了唯一请求消息 ID，请查看是否可以获取有关失败原因的更多信息。

分辨率

如果您已确定政策存在问题的原因，请尝试通过修正政策并重新部署代理来解决问题。

以下示例说明了如何确定不同类型问题的原因和解决方案。

如果您在排查 500 内部服务器错误时需要进一步的帮助，或者怀疑这是 Edge 中的问题，请与 Apigee 支持团队联系。

示例 1：由于后端服务器出错，服务调出政策失败

如果对后端服务器的调用在 Service Callout 政策中失败并显示任何错误（例如 4XX 或 5XX），则会被视为 500 内部服务器错误。

  1. 以下示例展示了在服务调出政策中，后端服务因 404 错误而失败的情况。系统会向最终用户发送以下错误消息： 
    {
"fault":
     { "detail":
           { "errorcode":"steps.servicecallout.ExecutionFailed"
           },"faultstring":"Execution of ServiceCallout service_callout_v3_store_by_lat_lon
 failed. Reason: ResponseCode 404 is treated as error"
          }
     }
}
  2. 以下跟踪记录界面会话显示了因服务调出政策中的错误而导致的 500 状态代码：

  3. 在此示例中，“error”属性将服务调出政策失败的原因列为 “ResponseCode 404 is treated as error”。如果通过服务调出政策中的后端服务器网址访问的资源不可用，则可能会发生此错误。
  4. 检查后端服务器上资源的可用性。该文件可能暂时/永久无法访问，或者可能已移至其他位置。

示例 1 解决方案

  1. 检查后端服务器上资源的可用性。该文件可能暂时/永久无法访问，或者可能已移至其他位置。
  2. 修正 Service Callout 政策中的后端服务器网址，使其指向有效且现有的资源。
  3. 如果资源只是暂时不可用，请在资源可用后尝试发出 API 请求。

示例 2：提取变量政策失败

现在，我们来看另一个示例，其中 500 内部服务器错误是由“提取变量”政策中的错误引起的，并了解如何排查和解决该问题。

  1. 界面会话中的以下轨迹显示，由于提取变量政策中存在错误，因此状态代码为 500：

  2. 选择失败的“提取变量”政策，向下滚动并查看“错误内容”部分，了解更多详情：

  3. 错误内容表明，提取变量政策中没有 "serviceCallout.oamCookieValidationResponse" 变量。正如变量名称所指示的那样，它应包含前面“服务调用”政策的响应。
  4. 在轨迹中选择服务调出政策，您可能会发现“serviceCallout.oamCookieValidationResponse”变量未设置。这表示对后端服务的调用失败，导致响应变量为空。
  5. 尽管服务调出政策失败，但由于服务调出政策中的“continueOnError”标志设置为 true，因此服务调出政策之后的政策仍会继续执行，如下所示：

    <ServiceCallout async="false" continueOnError="true" enabled="true" name="Callout.OamCookieValidation">
  <DisplayName>Callout.OamCookieValidation</DisplayName>
  <Properties />
  <Request clearPayload="true" variable="serviceCallout.oamCookieValidationRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  </Request>
  <Response>serviceCallout.oamCookieValidationResponse</Response>
  <HTTPTargetConnection>
    <Properties />
    <URL>http://{Url}</URL>
  </HTTPTargetConnection>
</ServiceCallout>
  6. 请注意此特定 API 请求的唯一消息 ID “X-Apigee.Message-ID”，如下所示：
    1. 从请求中选择“记录的 Analytics 数据”阶段。
    2. 向下滚动，然后记下 X-Apigee.Message-ID 的值。

  7. 查看消息处理器日志 (/opt/apigee/var/log/edge-message-processor/system.log)，然后搜索在第 6 步中记下的唯一消息 ID。对于特定 API 请求，观察到以下错误消息： 
    2017-05-05 07:48:18,653 org:myorg env:prod api:myapi rev:834 messageid:rrt-04984fed9e5ad3551-c-wo-32168-77563  NIOThread@5 ERROR HTTP.CLIENT - HTTPClient$Context.onTimeout() : ClientChannel[C:]@149081 useCount=1 bytesRead=0 bytesWritten=0 age=3002ms lastIO=3002ms .onConnectTimeout connectAddress=mybackend.domain.com/XX.XX.XX.XX:443 resolvedAddress=mybackend.domain.com/XX.XX.XX.XX

    上述错误表明，在连接到后端服务器时，由于连接超时错误，服务调用政策失败。

  8. 如需确定连接超时错误的原因，请从消息处理器向后端服务器执行 telnet 命令。telnet 命令返回“Connection timed out”（连接超时）错误，如下所示： 
    telnet mybackend.domain.com 443
Trying XX.XX.XX.XX...
telnet: connect to address XX.XX.XX.XX: Connection timed out

    此错误通常在以下情况下出现：

    • 后端服务器未配置为允许来自 Edge Message Processor 的流量。
    • 如果后端服务器未监听特定端口。

    在上述示例中，虽然提取变量政策失败了，但实际原因是 Edge 无法连接到服务调用政策中的后端服务器。此故障的原因是，后端服务器未配置为允许来自 Edge 消息处理器的流量。

    您自己的提取变量政策的行为会有所不同，并且可能会因其他原因而失败。您可以检查错误属性中的消息，根据提取变量政策失败的原因相应地排查问题。

示例 2 解决方案

  1. 适当修正提取变量政策中的错误或失败原因。
  2. 在上述示例中，解决方案是修正网络配置，以允许从边缘消息处理器到后端服务器的流量。这是通过在特定后端服务器上将消息处理器的 IP 地址列入许可名单来实现的。例如，在 Linux 上，您可以使用 iptables 允许后端服务器上的消息处理器 IP 地址的流量。

示例 3：JavaCallout 政策中的失败

现在，我们再来看一个示例，其中 500 内部服务器错误是由 Java 标注政策中的错误引起的，并了解如何排查和解决该问题。

  1. 以下界面轨迹显示了因 Java Callout 政策中的错误而导致的 500 状态代码：

  2. 选择名为 “Error”的流程，然后选择失败的 Java 调出政策，以获取错误详情，如下图所示：

  3. 在此示例中，Properties 部分下的 “error”属性显示，失败的原因是在 JavaCallout 政策中连接到 Oracle 数据库时使用了过期的密码。您自己的 Java callout 的行为会有所不同，并且会在 error 属性中填充不同的消息。
  4. 检查 JavaCallout 政策代码，并确认需要使用的正确配置。

示例 3 解决方案

请相应地修正 Java callout 代码或配置，以避免出现运行时异常。在上述 Java 调用失败示例中，需要使用正确的密码连接到 Oracle 数据库才能解决问题。

后端服务器错误

500 内部服务器错误也可能源自后端服务器。本部分介绍了如何排查后端服务器出现的错误。

诊断

面向所有用户的诊断步骤

其他后端错误的原因可能千差万别。您需要单独诊断每种情况。

  1. 验证错误是否由后端服务器引起。如需了解详情，请参阅确定问题来源。
  2. 如果错误是由后端服务器引起的，请继续。如果错误发生在政策执行期间，请参阅 Edge 政策中的执行错误。
  3. 请根据您是否可以访问失败 API 的 Trace 会话，或者后端是否为 Node.js 服务器，按照以下步骤操作：

如果您没有失败的 API 调用的 Trace 会话：

  1. 如果界面轨迹不适用于失败的请求，请检查后端服务器日志以获取有关错误的详细信息。
  2. 如果可以，请在后端服务器上启用调试模式，以详细了解错误和原因。

如果您确实有失败的 API 调用的跟踪会话：

如果您有轨迹会话，以下步骤将有助于您诊断问题。

  1. 在 Trace 工具中，选择失败并显示 500 内部服务器错误的 API 请求。
  2. 从失败的 API 请求中选择“从目标服务器收到的响应”阶段，如下图所示：

  3. 查看“响应内容”部分，了解有关错误的详细信息。

  4. 在此示例中，作为 SOAP 封装的响应内容显示了错误字符串“Not Authorized”消息。此问题最可能的原因是用户未将正确的凭据（用户名/密码、访问令牌等）传递给后端服务器。通过将正确的凭据传递给后端服务器，可以解决此问题。

如果后端是 Node.js 服务器：

  1. 如果后端是 Node.js 后端服务器，请在 Edge 界面中检查特定 API 代理的 Node.js 日志（公共云和私有云用户都可以检查 Node.js 日志）。如果您是 Edge Private Cloud 用户，还可以查看消息处理器日志 (/opt/apigee/var/log/edge-message-processor/logs/system.log)，详细了解该错误。

    Edge 界面中的 NodeJS 日志选项 - API 代理的“概览”标签页

解决方法

  1. 确定错误原因后，请在后端服务器中解决相应问题。
  2. 如果是 Node.js 后端服务器：
    1. 检查错误是否由您的自定义代码抛出，并尽可能解决该问题。
    2. 如果错误不是由您的自定义代码抛出的，或者您需要帮助，请与 Apigee 支持团队联系。

如果您在排查 500 内部服务器错误时需要进一步的帮助，或者怀疑这是 Edge 中的问题，请与 Apigee 支持团队联系。

确定问题来源

请使用以下任一过程来确定 500 内部服务器错误是在 API 代理中的政策执行期间还是由后端服务器抛出的。

在界面中使用 Trace

注意：本部分中的步骤可由公共云和私有云用户执行。

  1. 如果问题仍然存在，请在界面中为受影响的 API 启用轨迹。
  2. 捕获轨迹后，选择显示响应代码为 500 的 API 请求。
  3. 浏览失败的 API 请求的所有阶段，并检查哪个阶段返回了 500 内部服务器错误：
    1. 如果在执行政策期间抛出错误，请继续参阅 Edge 政策中的执行错误。
    2. 如果后端服务器已响应 500 Internal Server，请继续执行后端服务器中的错误。

使用 API Monitoring

注意：本部分中的步骤只能由公共云用户执行。

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

逐步了解示例场景，该场景演示了如何使用 API 监控功能排查 API 的 5xx 问题。 例如，您可能希望设置提醒，以便在 500 状态代码或 steps.servicecallout.ExecutionFailed 故障的数量超过特定阈值时收到通知。

使用 NGINX 访问日志

注意：本部分中的步骤仅适用于 Edge Private Cloud 用户。

您还可以参考 NGINX 访问日志，以确定在 API 代理中执行政策期间或由后端服务器是否抛出了 500 状态代码。如果过去曾发生过该问题或者该问题间歇性发生，并且您无法在界面中捕获跟踪记录，则此功能特别有用。您可以按照以下步骤从 NGINX 访问日志中确定此信息：

  1. 检查 NGINX 访问日志 (/opt/apigee/var/log/edge-router/nginx/ <org>~ <env>.<port#>_access_log)。
  2. 搜索特定时间段内特定 API 代理是否存在任何 500 错误。
  3. 如果存在任何 500 错误，请检查该错误是政策错误还是目标服务器错误，如下所示：

    显示政策错误的示例条目

    显示目标服务器错误的示例条目

  4. 确定是政策错误还是目标服务器错误后：
    1. 如果是政策错误，请继续执行Edge 政策中的执行错误。
    2. 如果是目标服务器错误，请继续执行后端服务器错误。