500 內部伺服器錯誤

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

影片

請觀看以下影片，進一步瞭解如何解決 500 個內部伺服器錯誤。

影片 說明
說明 介紹 500 個內部伺服器錯誤及可能原因。另外也會示範即時的 500 內部伺服器錯誤，以及疑難排解和解決錯誤的步驟。
處理服務呼叫和擷取變數錯誤 說明因服務呼叫和擷取變數政策而造成的 500 個內部伺服器錯誤，並說明如何疑難排解及解決這些錯誤。
處理 JavaScript 政策錯誤 顯示 JavaScript 政策造成的 500 內部伺服器錯誤，以及排解這項錯誤的步驟。
處理後端伺服器發生的失敗問題 顯示因後端伺服器發生錯誤而導致的 500 個內部伺服器錯誤示例，並顯示錯誤解決步驟。

問題

用戶端應用程式會取得 500 的 HTTP 狀態碼和訊息「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 中，系統會根據錯誤發生的位置，將原因分為兩類：

原因 詳細資料 詳細的疑難排解步驟
邊緣政策中的執行錯誤 API Proxy 中的政策可能會因某些原因而失敗。 邊緣私有雲和公有雲使用者
後端伺服器發生錯誤 後端伺服器可能會因某些原因而失敗。 邊緣私有雲和公有雲使用者

Edge 政策中的執行錯誤

API Proxy 中的政策可能會因某些原因而失敗。本節說明如何在政策執行期間發生 500 內部伺服器錯誤時，如何排解問題。

診斷

私人和公有雲使用者的診斷步驟

如果有錯誤的追蹤 UI 工作階段，則：

  1. 確認這項錯誤是因執行政策而造成。詳情請參閱判斷問題來源。
  2. 如果政策執行期間發生錯誤，請繼續操作。如果錯誤是由後端伺服器造成，請參閱後端伺服器發生錯誤一節。
  3. 選取追蹤記錄中失敗的 API 要求 (追蹤記錄中有 500 個內部伺服器錯誤)。
  4. 檢查要求，並選取失敗的特定政策，或在追蹤記錄失敗後立即看到名為「Error」的流程。
  5. 如要進一步瞭解錯誤，請查看「屬性」部分或「錯誤」內容下方的「錯誤」欄位。
  6. 運用收集到的錯誤詳細資訊，嘗試判斷原因。

僅限私人雲端使用者的診斷步驟

如果您沒有追蹤記錄 UI 工作階段，請按照下列步驟操作：

  1. 驗證執行政策期間是否發生錯誤。詳情請參閱判斷問題來源。
  2. 如果這項錯誤是因執行政策而造成，請繼續操作。如果政策執行期間發生錯誤，請繼續操作。如果錯誤是由後端伺服器造成，請參閱後端伺服器發生錯誤一節。
  3. 使用 NGINX 存取記錄檔，詳情請參閱「判斷問題來源」一節的說明，判斷 API Proxy 中的失敗政策，以及不重複的要求訊息 ID
  4. 查看訊息處理器記錄檔 (/opt/apigee/var/log/edge-message-processor/logs/system.log)，並在其中搜尋專屬要求訊息 ID。
  5. 如果您找到了專屬的要求訊息 ID，看看是否可以取得更多失敗原因的相關資訊。

解析度

如果您已確定政策問題的原因，請修正政策並重新部署 Proxy，嘗試修正問題。

以下範例說明如何判斷不同類型的問題的原因和解決方法。

如果您在排解 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. 下列追蹤 UI 工作階段顯示因服務呼叫政策發生錯誤而造成的 500 狀態碼：

  3. 在此範例中，「error」屬性會列出導致服務呼叫政策失敗的原因，並提供「ResponseCode 404 視為錯誤」。如果透過服務呼叫政策中的後端伺服器網址存取資源，就有可能發生這個錯誤。
  4. 在後端伺服器上檢查資源是否可用。原因可能是暫時/永久無法使用，或是已移至其他位置。

範例 1

  1. 在後端伺服器上檢查資源是否可用。原因可能是暫時/永久無法使用，或是已移至其他位置。
  2. 修正服務呼叫政策中的後端伺服器網址，使其指向有效且現有的資源。
  3. 如果該項資源暫時無法使用，請在可用資源時嘗試提出 API 要求。

示例 2：擷取變數政策失敗

接著來看看另一個例子，其中有 500 個內部伺服器錯誤是因「擷取變數」政策中的錯誤所造成，並瞭解如何排解問題。

  1. 下列 UI 工作階段追蹤記錄因「擷取變數」政策發生錯誤而顯示 500 狀態碼：

  2. 選取「擷取變數」政策失敗，向下捲動並查看「錯誤內容」部分瞭解詳情：

  3. 「錯誤內容」表示「擷取變數」政策無法使用 "service callout.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 指令發出「連線逾時」錯誤，如下所示： 
    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：Java 呼叫政策中的失敗情形

讓我們再看看另一個例子，其中「500 內部伺服器錯誤」是 Java 呼叫政策發生錯誤所造成，以及如何排解問題。

  1. 以下 UI 追蹤顯示因 Java 呼叫政策發生錯誤而導致的 500 狀態碼：

  2. 選取名為「Error」的流程，接著選取失敗的 Java 呼叫政策，即可取得錯誤詳細資料，如下圖所示：

  3. 在這個範例中，「Properties」部分底下的 "error" 屬性顯示，這是因為您在從 Java 呼叫政策中連線至 Oracle 資料庫時使用過期的密碼而導致失敗。您自己的 Java 呼叫會有所不同，而會在 error 屬性中填入不同訊息。
  4. 查看 Java 呼叫政策程式碼，並確認需要採用的正確設定。

解析度範例 3

請適當修正 Java 呼叫程式碼或設定，避免發生執行階段例外狀況。在上方展示的 Java 呼叫失敗範例中，使用者必須使用正確的密碼連線至 Oracle 資料庫才能解決問題。

後端伺服器發生錯誤

後端伺服器也可能發生「500 內部伺服器錯誤」。本節說明如何排解來自後端伺服器的錯誤。

診斷

所有使用者的診斷步驟

其他後端錯誤的原因可能大不相同。您會需要單獨診斷各個情況。

  1. 驗證該錯誤是否由後端伺服器造成。詳情請參閱判斷問題來源。
  2. 如果錯誤是由後端伺服器造成，請繼續操作。如果政策執行期間發生錯誤，請參閱邊緣政策中的執行作業錯誤。
  3. 請根據您是否能夠存取失敗的 API 或後端是否為 Node.js 伺服器，執行下列步驟：

如果失敗的 API 呼叫沒有 Trace 工作階段：

  1. 如果失敗的要求沒有 UI 追蹤記錄，請查看後端伺服器記錄來取得錯誤的詳細資料。
  2. 如果可以，請在後端伺服器上啟用偵錯模式，取得更多錯誤和原因的詳細資料。

如果您有追蹤失敗的 API 呼叫的 Trace 工作階段：

如果您有 Trace 工作階段，可以按照下列步驟診斷問題。

  1. 在 Trace 工具中，選取失敗的 API 要求 (發生 500 個內部伺服器錯誤)。
  2. 從失敗的 API 要求中選取「Responsereceive from target server」階段，如下圖所示：

  3. 如要進一步瞭解錯誤詳情，請查看「回應內容」部分。

  4. 在此範例中，為 SOAP 信封的回應內容，會將錯誤字串顯示為「Not Authorized」(未授權) 訊息。這個問題最有可能的原因是使用者未將正確憑證 (使用者名稱/密碼、存取權杖等) 傳遞至後端伺服器。將正確的憑證傳遞至後端伺服器即可修正這個問題。

如果後端是 Node.js 伺服器：

  1. 如果後端是 Node.js 後端伺服器，請在 Edge UI 中檢查特定 API Proxy 的 Node.js 記錄 (公開和私有 Cloud 使用者都可以查看 Node.js 記錄)。如果您是 Edge Private Cloud 使用者，您也可以查看訊息處理者記錄檔 (/opt/apigee/var/log/edge-message-processor/logs/system.log)，進一步瞭解錯誤。

    Edge UI 中的 NodeJS 記錄選項 - API Proxy 的總覽分頁

解析度

  1. 找出錯誤原因後，請在後端伺服器中修正問題。
  2. 如果是 Node.js 後端伺服器：
    1. 請檢查自訂程式碼是否擲回錯誤，並盡可能修正問題。
    2. 如果錯誤並未從您的自訂程式碼擲回錯誤，或是需要協助，請與 Apigee 支援團隊聯絡。

如果您在排解 500 內部伺服器錯誤時需要進一步協助，或懷疑問題發生在 Edge 中，請與 Apigee 支援團隊聯絡。

判斷問題來源

請使用下列其中一個程序，判斷在 API Proxy 或後端伺服器執行政策時，是否發生了 500 內部伺服器錯誤。

在 UI 中使用 Trace

注意事項：本節所述步驟可由公開和私有雲使用者執行。

  1. 如果問題仍未解決，請在 UI 中為受影響的 API 啟用追蹤記錄。
  2. 擷取追蹤記錄後，請選取將回應代碼顯示為 500 的 API 要求。
  3. 瀏覽失敗 API 要求的所有階段，並檢查哪個階段傳回 500 Internal Server Error：
    1. 如果在執行政策時擲回錯誤，請參閱「邊緣政策的執行錯誤」一節。
    2. 如果後端伺服器回應了 500 個內部伺服器，請繼續參閱「後端伺服器發生錯誤」一節。

使用 API Monitoring

注意事項：本節中的步驟只能由公有雲使用者執行。

API 監控功能可讓您快速隔離問題區域，以診斷錯誤、效能與延遲問題及其來源 (例如開發人員應用程式、API Proxy、後端目標或 API 平台)。

逐步操作範例情境，示範如何使用 API Monitoring 排解 API 的 5xx 問題。舉例來說，您可以設定快訊，讓系統在 500 組狀態碼或 steps.servicecallout.ExecutionFailed 錯誤數量超過特定門檻時通知您。

使用 NGINX 存取記錄檔

注意：本節的步驟僅適用於 Edge Private Cloud 使用者。

您也可以參考 NGINX 存取記錄，以判斷 API Proxy 內部或後端伺服器執行政策時，是否擲回 500 狀態碼。如果問題過去發生，或是問題間歇性，導致您無法在 UI 中擷取追蹤記錄，此方法就能派上用場。請按照下列步驟操作，從 NGINX 存取記錄檔判斷這項資訊：

  1. 檢查 NGINX 存取記錄 (/opt/apigee/var/log/edge-router/nginx/ <org>~ <env>.<port#>_access_log )。
  2. 搜尋特定 API Proxy 在特定期間內是否發生 500 錯誤。
  3. 如果發生 500 錯誤，請檢查錯誤是否為政策或目標伺服器錯誤，如下所示：

    顯示政策錯誤的範例項目

    顯示目標伺服器錯誤的範例項目

  4. 確認政策本身是政策或目標伺服器錯誤後，請按照下列步驟操作：
    1. 如果發現政策錯誤，請參閱「邊緣政策中的執行錯誤」。
    2. 如果目標伺服器錯誤，請參閱「後端伺服器錯誤」一節。