500 内部服务器错误

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

视频

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

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

问题

客户端应用收到 HTTP 状态代码 500 以及消息“内部服务器错误”，作为对 API 调用的响应。500 内部服务器错误可能是由在边缘内执行任何政策期间发生错误或目标/后端服务器错误导致的。

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 中，根据错误的发生位置，原因可以分为两大类：

原因	详细说明	我们提供了详细的问题排查步骤
边缘政策中的执行错误	API 代理中的 Policy 可能会因某种原因而失败。	Edge Private 和公有云用户
后端服务器出错	后端服务器可能由于某种原因而发生故障。	Edge Private 和公有云用户

边缘政策中的执行错误

API 代理中的 Policy 可能会因某种原因而失败。本部分介绍如何在执行政策期间发生 500 Internal Server Error 时排查问题。

诊断

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

如果您有错误的跟踪界面会话，则：

1. 验证错误是否是由执行政策引起的。有关详情，请参阅确定问题的根源。
2. 如果在政策执行期间发生错误，请继续。如果错误是由后端服务器引起的，请转到后端服务器出错。
3. 选择失败且跟踪记录中返回 500 Internal Server Error 的 API 请求。
4. 检查请求，并选择失败的特定政策，或名为“错误”的流程，紧跟在跟踪记录中失败的政策后面。
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：由于后端服务器出错，服务调用程序政策失败

如果对后端服务器的调用在服务调用方政策内失败，并显示任何错误（例如 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 was 横幅广告”视为错误。如果通过服务调用程序政策中的后端服务器网址访问的资源不可用，则可能会发生此错误。
4. 检查后端服务器上的资源可用性。它可能暂时无法使用/永久可用，或可能已移动到其他位置。

示例 1 分辨率

1. 检查后端服务器上的资源可用性。它可能暂时无法使用/永久可用，或可能已移动到其他位置。
2. 修正服务宣传信息政策中的后端服务器网址，使其指向有效的现有资源。
3. 如果资源只是暂时不可用，请尝试在资源可用后发出 API 请求。

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

现在，我们再看一个示例。在该示例中，“提取变量”政策中存在错误导致了 500 Internal Server Error，并了解如何排查和解决问题。

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. 从请求中选择“Google 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 命令给出了“连接超时”错误，如下所示：

   telnet mybackend.domain.com 443
   Trying XX.XX.XX.XX...
   telnet: connect to address XX.XX.XX.XX: Connection timed out
   

   通常，在以下情况下，会发现此错误：

   • 后端服务器未配置为允许来自边缘消息处理器的流量。
   • 后端服务器未在特定端口上进行监听。

   在上面的说明示例中，尽管提取变量政策失败，但实际原因是 Edge 无法连接到服务调用程序政策中的后端服务器。造成此失败的原因是后端服务器未配置为允许来自边缘消息处理器的流量。

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

示例 2 分辨率

1. 妥善修复“提取变量”政策中的错误或失败原因。
2. 在上面的说明示例中，解决方案是校正网络配置，以允许来自边缘消息处理器的流量传输到后端服务器。这是通过将消息处理器的 IP 地址添加到特定后端服务器上的许可名单来完成的。例如，在 Linux 上，您可以使用 iptables 以允许来自后端服务器上的消息处理器 IP 地址的流量。

示例 3：JavaCallout 政策中的失败

现在，我们再看一个示例。在该示例中，Java 调用程序政策中存在错误导致了 500 Internal Server Error，并了解如何排查和解决问题。

1. 以下界面跟踪记录由于 Java 调用程序政策中的错误而显示了 500 状态代码：

   

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

   

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

示例 3 分辨率

适当修复 Java 调用程序代码或配置，以避免运行时异常。在上述 Java 调用程序故障示例中，需要使用正确的密码连接到 Oracle 数据库才能解决此问题。

后端服务器出错

后端服务器也可能产生“500 内部服务器错误”。本部分介绍了在后端服务器出现错误时如何排查问题。

诊断

适用于所有用户的诊断步骤

导致其他后端错误的原因可能有很大差异。您需要单独诊断每种情况。

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

如果您没有为失败的 API 调用打开跟踪会话：

1. 如果界面跟踪记录无法用于失败的请求，请检查后端服务器日志，获取有关错误的详细信息。
2. 如果可能，请在后端服务器上启用调试模式，以获取关于错误和原因的更多详细信息。

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

如果您有跟踪会话，以下步骤将帮助您诊断问题。

1. 在跟踪工具中，选择因 500 内部服务器错误而失败的 API 请求。
2. 从失败的 API 请求中选择从目标服务器接收的响应阶段，如下图所示：

   

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

   

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

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

1. 如果后端是 Node.js 后端服务器，请在边缘界面中查看特定 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 支持团队联系。

确定问题的根源

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

在界面中使用 Trace

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

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

使用 API 监控

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

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

通过一个示例场景演示了如何使用 API Monitoring 排查 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. 如果这是政策错误，请继续参阅边缘政策中的执行错误。
   2. 如果是目标服务器错误，请继续参阅后端服务器中的错误。