500 內部伺服器錯誤

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

影片

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

影片 說明
簡介 簡介 500 Internal Server Error，並說明可能原因。同時展示即時 500 內部伺服器錯誤，以及排解和解決錯誤的步驟。
處理服務呼叫和擷取變數錯誤 示範由服務呼叫和擷取變數政策造成的兩個 500 內部伺服器錯誤，並說明如何排解及解決這些錯誤。
處理 JavaScript 政策錯誤 顯示因 JavaScript 政策而導致的 500 Internal Server Error，以及解決這個錯誤的步驟。
處理後端伺服器故障 顯示後端伺服器故障導致的 500 內部伺服器錯誤範例，並說明解決錯誤的步驟。

問題

用戶端應用程式會收到 HTTP 狀態碼 500，以及「Internal Server Error」訊息，做為 API 呼叫的回應。500 Internal Server 錯誤可能是 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 Proxy 中的政策可能會因某種原因而失敗。 Edge 私有和公有雲使用者
後端伺服器發生錯誤 後端伺服器可能會因故發生錯誤。 Edge 私有和公有雲使用者

Edge 政策執行錯誤

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

診斷

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

如果錯誤有追蹤 UI 工作階段，請按照下列步驟操作：

  1. 確認錯誤是否是由政策執行所致。詳情請參閱「判斷問題來源」。
  2. 如果錯誤發生在政策執行期間，請繼續。如果錯誤是由後端伺服器所致，請參閱「後端伺服器發生錯誤」。
  3. 在追蹤記錄中，選取因發生 500 內部伺服器錯誤而失敗的 API 要求。
  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. 以下範例顯示後端服務在 Service Callout 政策中發生 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 is treated as error」。如果透過服務呼叫政策中的後端伺服器網址存取的資源無法使用，就可能發生這個錯誤。
  4. 檢查後端伺服器上的資源是否可用。該檔案可能暫時/永久無法存取，或是已移至其他位置。

範例 1 解決方案

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

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

現在來看另一個範例，其中 500 內部伺服器錯誤是由「擷取變數」政策中的錯誤所導致，並瞭解如何排解及解決問題。

  1. UI 工作階段中的下列追蹤記錄顯示 500 狀態碼，這是因為「Extract Variables」政策發生錯誤：

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

  3. 錯誤內容表示「serviceCallout.oamCookieValidationResponse」變數在「擷取變數」政策中無法使用。如變數名稱所示，這個變數應保留先前服務呼叫政策的回應。
  4. 在追蹤記錄中選取「Service Callout」政策，您可能會發現「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. 在上圖所示的範例中，解決方法是修正網路設定，允許 Edge 訊息處理器將流量傳送至後端伺服器。方法是在特定後端伺服器上，將訊息處理器的 IP 位址加入許可清單。舉例來說，在 Linux 上，您可以使用 iptables 允許後端伺服器上的訊息處理器 IP 位址傳送流量。

範例 3：JavaCallout 政策失敗

現在再來看一個例子，瞭解 Java Callout 政策發生錯誤導致 500 Internal Server Error 時，如何排解及解決問題。

  1. 下列 UI 追蹤記錄顯示，由於 Java Callout Policy 發生錯誤，因此出現 500 狀態碼：

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

  3. 在本例中，「屬性」部分下的「error」屬性顯示，失敗的原因是在從 JavaCallout 政策連線至 Oracle 資料庫時，使用了過期的密碼。您自己的 Java 呼叫會以不同方式運作，並在 error 屬性中填入不同的訊息。
  4. 檢查 JavaCallout 政策程式碼，確認需要使用的正確設定。

範例 3：解決方案

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

後端伺服器發生錯誤

500 Internal Server Error 也可能源自後端伺服器。本節說明如何排解後端伺服器造成的錯誤。

診斷

所有使用者的診斷步驟

其他後端錯誤的原因可能大相逕庭。您必須個別診斷每種情況。

  1. 確認錯誤是否是由後端伺服器所導致。詳情請參閱「判斷問題來源」。
  2. 如果錯誤是由後端伺服器所致，請繼續操作。如果錯誤發生在政策執行期間，請參閱「Edge 政策執行錯誤」。
  3. 請視您是否能存取失敗 API 的追蹤工作階段，或後端是否為 Node.js 伺服器，按照下列步驟操作：

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

  1. 如果失敗的要求沒有 UI 追蹤記錄，請檢查後端伺服器記錄，瞭解錯誤詳情。
  2. 如有可能，請在後端伺服器上啟用偵錯模式，進一步瞭解錯誤和原因。

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

如果您有追蹤工作階段，請按照下列步驟診斷問題。

  1. 在「追蹤」工具中，選取因 500 內部伺服器錯誤而失敗的 API 要求。
  2. 從失敗的 API 要求中選取「Response received from target server」(從目標伺服器收到的回應) 階段，如下圖所示：

  3. 查看「回應內容」部分，瞭解錯誤詳細資料。

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

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

  1. 如果後端是 Node.js 後端伺服器，請在 Edge UI 中檢查特定 API Proxy 的 Node.js 記錄 (公開和私有雲使用者都可以檢查 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 Internal Server Error。

在 UI 中使用 Trace

附註：公有雲和私有雲使用者都可以執行本節中的步驟。

  1. 如果問題仍未解決，請在 UI 中為受影響的 API 啟用追蹤功能。
  2. 擷取追蹤記錄後，請選取回應代碼為 500 的 API 要求。
  3. 瀏覽失敗 API 要求的各個階段，並檢查哪個階段傳回 500 Internal Server Error：
    1. 如果政策執行期間發生錯誤，請參閱「Edge 政策中的執行錯誤」。
    2. 如果後端伺服器傳回 500 Internal Server，請繼續參閱「後端伺服器發生錯誤」。

使用 API Monitoring

附註：本節中的步驟僅適用於公有雲使用者。

API 監控功能可協助您快速找出問題領域，診斷錯誤、效能和延遲問題及其來源，例如開發人員應用程式、API Proxy、後端目標或 API 平台。

逐步瞭解範例情境，瞭解如何使用 API 監控功能排解 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. 如果是政策錯誤，請前往「Edge 政策中的執行錯誤」。
    2. 如果是目標伺服器錯誤，請前往「後端伺服器發生錯誤」。