504 閘道逾時

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

問題

用戶端應用程式會收到 HTTP 狀態碼 504，以及訊息 Gateway Timeout，做為 API 呼叫的回應。

HTTP 狀態碼 - 504 Gateway Timeout 錯誤表示用戶端在執行 API 時，未及時收到 Edge Gateway 或後端伺服器的回應。

錯誤訊息

用戶端應用程式會收到下列回應代碼：

HTTP/1.1 504 Gateway Timeout

在某些情況下，您也可能會看到下列錯誤訊息：

{
   "fault": {
      "faultstring": "Gateway Timeout",
      "detail": {
           "errorcode": "messaging.adaptors.http.flow.GatewayTimeout"
       }
    }
}

什麼原因會導致閘道逾時？

透過 Edge 平台發出 API 要求的典型路徑為「用戶端 -> 路由器 -> 訊息處理器 -> 後端伺服器」，如下圖所示：

用戶端應用程式、路由器和 Edge 平台內的訊息處理器，都會設定適當的逾時值。根據逾時值，Edge 平台預期每個 API 要求都會在特定時間內傳送回應。如果沒有在指定的時限內收到回應，系統會傳回 504 Gateway Timeout Error。

下表提供 Edge 中可能發生逾時的詳細資訊：

逾時 詳細資料
訊息處理器發生逾時狀況
  • 後端伺服器未在訊息處理器的指定逾時期間內，回應訊息處理器。
  • 訊息處理器逾時，並將回應狀態 504 Gateway Timeout 傳送至路由器。
路由器發生逾時
  • 訊息處理器未在路由器上指定的逾時期間內回應路由器。
  • 路由器逾時，並將回應狀態 504 Gateway Timeout 傳送至用戶端應用程式。
用戶端應用程式發生逾時
  • 路由器未在路由器上指定的逾時期間內回應用戶端應用程式。
  • 用戶端應用程式逾時，並向使用者顯示 504 Gateway Timeout 的回應狀態。

可能原因

在 Edge 中，504 Gateway Timeout 錯誤的常見原因如下：

原因 詳細資料 獲得步數的活動
後端伺服器速度緩慢 由於負載過高或效能不佳，處理 API 要求的後端伺服器速度過慢。 公有雲和私有雲使用者
Edge 處理 API 要求的速度緩慢 Edge 負載過高或效能不佳，導致處理 API 要求的時間過長。

後端伺服器速度緩慢

如果後端伺服器速度很慢，或處理 API 要求需要很長時間，您就會收到 504 Gateway Timeout 錯誤。如上一節所述，發生逾時問題的原因可能是下列任一情況：

  1. 後端伺服器尚未回應，訊息處理器就已逾時。
  2. 路由器在訊息處理器/後端伺服器回應前逾時。
  3. 在路由器/訊息處理器/後端伺服器回應之前，用戶端應用程式逾時。

下列各節將說明如何診斷及解決這些情境下的問題。

情境 #1 後端伺服器回應前，訊息處理器逾時

診斷

您可以按照下列程序，診斷 504 Gateway Timeout 錯誤是否因後端伺服器速度緩慢而發生。

程序 #1：使用 Trace

如果問題仍未解決 (仍發生 504 錯誤)，請按照下列步驟操作：

  1. 在 Edge UI 中追蹤受影響的 API。請等待錯誤發生，或如果您有 API 呼叫，請發出一些 API 呼叫，重現 504 Gateway Timeout 錯誤。
  2. 發生錯誤後，請檢查顯示回應代碼為 504 的特定要求。
  3. 檢查每個階段經過的時間，並記下最耗時的階段。
  4. 如果在下列其中一個階段結束後，立即觀察到經過時間最長的錯誤，表示後端伺服器速度緩慢，或處理要求需要很長時間：
    • 要求已傳送至目標伺服器
    • ServiceCallout 政策

以下是追蹤記錄範例，顯示後端伺服器在 55 秒後仍未回應，導致發生 504 Gateway Timeout 錯誤：

在上述追蹤記錄中，由於後端伺服器未回應，訊息處理器在 55002 毫秒後逾時。

程序 2：使用訊息處理工具記錄檔

  1. 檢查訊息處理器的記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log)

  2. 如果在特定時間發現特定 API Proxy 要求的 Gateway Timeout 和 onTimeoutRead 錯誤，表示訊息處理器已逾時。

    訊息處理器記錄範例，顯示閘道逾時錯誤

    2015-09-29 20:16:54,340 org:myorg env:staging api:profiles rev:13 NIOThread@1
ERROR ADAPTORS.HTTP.FLOW - AbstractResponseListener.onException() :
AbstractResponseListener.onError(HTTPResponse@4d898cf1, Gateway
Timeout)
2015-09-29 20:16:57,361 org:myorg env:staging api:profileNewsletters rev:8
NIOThread@0 ERROR HTTP.CLIENT - HTTPClient$Context$3.onTimeout() :
SSLClientChannel[C:XX.XX.XX.XX:443 Remote
host:192.168.38.54:38302]@120171 useCount=2 bytesRead=0
bytesWritten=824 age=55458ms lastIO=55000ms .onTimeoutRead

    在上述訊息處理器記錄中，您會發現 IP 位址為 XX.XX.XX.XX 的後端伺服器在 55 秒後仍未回應 (lastIO=55000ms)。因此，訊息處理器逾時並傳送 504 Gateway Timeout 錯誤。

    請參閱：如何控管訊息處理器的逾時？

    • 如何控管訊息處理工具的逾時時間？訊息處理器通常會透過 HTTPTransport.io.timeout.millis 屬性，設定 55 秒的預設逾時值。這個逾時值適用於訊息處理器所服務機構的所有 API Proxy。
      • 如果後端伺服器未在 55 秒內回應，訊息處理器就會逾時，並將 504 Gateway Timeout 錯誤傳送給用戶端。
    • API Proxy 中指定的 io.timeout.millis 屬性可以覆寫訊息處理器中指定的逾時值。這個逾時值適用於指定上述屬性的特定 API Proxy。舉例來說，如果在 API Proxy 中將 io.timeout.millis 設為 10 秒，這個 API Proxy 就會使用 10 秒的逾時值。
      • 如果後端伺服器在特定 API Proxy 的 10 秒內沒有回應，訊息處理器就會逾時，並將 504 Gateway Timeout 錯誤傳送給用戶端。

解析度

  1. 檢查後端伺服器為何需要超過 55 秒，並瞭解是否能修正/最佳化，以加快回應速度。
  2. 如果無法修正/最佳化後端伺服器，或後端伺服器所需時間超過設定的逾時時間，請 在路由器和訊息處理器上將逾時值調高至適當值。

情境 #2 - 路由器在訊息處理器/後端伺服器回覆前逾時

如果路由器在訊息處理器/後端伺服器回應前逾時，您可能會收到 504 Gateway Timeout 錯誤。以下列舉部分可能導致這種現象的狀況：

  • 路由器上設定的逾時值短於訊息處理器上設定的逾時值。舉例來說，假設 Router 的逾時時間為 50 秒，而 Message Processor 的逾時時間為 55 秒。
    路由器逾時 訊息處理器逾時
    50 秒 55 秒
  • 使用 API Proxy 目標端點設定中設定的 io.timeout.millis 屬性，以較高的逾時值覆寫訊息處理器的逾時值：

    舉例來說，如果設定下列逾時值：

    路由器逾時 訊息處理器逾時 API Proxy 內的逾時
    57 秒 55 秒 120 秒

    但 API Proxy 中的 io.timeout.millis 設為 120 秒：

    <HTTPTargetConnection>
     <Properties>
          <Property name="io.timeout.millis">120000</Property>
      </Properties>
      <URL>http://www.apigee.com</URL>
</HTTPTargetConnection>

    這樣一來，即使訊息處理器的逾時值 (55 秒) 小於路由器的逾時值 (57 秒)，訊息處理器也不會在 55 秒後逾時。這是因為 API Proxy 中設定的 120 秒值，會覆寫訊息處理器的 55 秒逾時值。因此，這個特定 API Proxy 的訊息處理器逾時值為 120 秒。

    由於 Router 的逾時值 (57 秒) 低於 API Proxy 內設定的 120 秒，如果後端伺服器在 57 秒後未回覆，Router 就會逾時。

診斷

  1. 檢查 NGINX 存取記錄 (/opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log)

  2. 如果路由器在訊息處理器之前逾時，您會在特定 API 要求的 NGINX 存取記錄中看到 504 狀態，且訊息處理器的 message id 會設為 -。這是因為路由器在路由器上設定的逾時期間內，未收到訊息處理器的任何回應。

    範例 NGINX 記錄檔項目，顯示因路由器逾時而出現 504 錯誤

  3. 在上述範例中，請注意 NGINX 的 504 狀態、來自 Message Processor 的訊息 ID -，以及經過的總時間 57.001 秒。這是因為路由器在 57.001 秒後逾時，且我們未收到訊息處理器的任何回應。
  4. 在這種情況下，您會在 Message Processor 記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log). Broken Pipe
    2017-06-09 00:00:25,886 org:myorg env:test api:myapi-v1 rev:23 messageid:rrt-mp01-18869-23151-1  NIOThread@1 INFO  HTTP.SERVICE - ExceptionHandler.handleException() : Exception java.io.IOException: Broken pipe occurred while writing to channel ClientOutputChannel(ClientChannel[A:XX.XX.XX.XX:8998 Remote host:YY.YY.YY.YY:51400]@23751 useCount=1 bytesRead=0 bytesWritten=486 age=330465ms  lastIO=0ms )
2017-06-09 00:00:25,887  org:myorg env:test api:myapi-v1 rev:23 messageid:rrt-mp01-18869-23151-1  NIOThread@1 INFO  HTTP.SERVICE - ExceptionHandler.handleException() : Exception trace:
java.io.IOException: Broken pipe
        at com.apigee.nio.channels.ClientOutputChannel.writePending(ClientOutputChannel.java:51) ~[nio-1.0.0.jar:na]
        at com.apigee.nio.channels.OutputChannel.onWrite(OutputChannel.java:116) ~[nio-1.0.0.jar:na]
        at com.apigee.nio.channels.OutputChannel.write(OutputChannel.java:81) ~[nio-1.0.0.jar:na]
         … <snipped>

路由器逾時後，會關閉與訊息處理器的連線，因此系統會顯示這項錯誤。訊息處理器完成處理作業後，會嘗試將回應寫入路由器。由於與路由器的連線已關閉，因此訊息處理器會顯示 Broken Pipe exception。

如上所述，在這種情況下，您應該會看到這項例外狀況。因此，504 Gateway Timeout 錯誤的實際原因仍是後端伺服器回應時間過長，您需要解決這個問題。

解析度

  1. 如果是自訂後端伺服器，則
    1. 檢查後端伺服器回應時間過長的原因，並確認是否能修正/最佳化，加快回應速度。
    2. 如果無法修正/最佳化後端伺服器，或後端伺服器需要很長時間是已知事實，請增加路由器和訊息處理器的逾時值。

      建議：依下列順序，為不同元件設定逾時值：

      用戶端逾時 > 路由器逾時 > 訊息處理器逾時 > API Proxy 逾時
  2. 如果是 NodeJS 後端伺服器，請執行下列操作：
    1. 檢查 NodeJS 程式碼是否會呼叫任何其他後端伺服器，以及是否需要很長時間才能傳回回應。檢查後端伺服器耗時較長的原因，並視情況修正問題。
    2. 檢查訊息處理器是否出現 CPU 或記憶體用量偏高的情況：
      1. 如果任何訊息處理器 CPU 使用率偏高，請使用下列指令，每 30 秒產生三份執行緒傾印： 
        JAVA_HOME/bin/jstack -l PID > FILENAME
      2. 如果任何訊息處理器的記憶體用量偏高，請使用下列指令產生 heap dump：
        sudo -u apigee JAVA_HOME/bin/jmap -dump:live,format=b,file=FILENAME PID
      3. 使用下列指令重新啟動訊息處理器。這應該會降低 CPU 和記憶體使用量：
        /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
      4. 監控 API 呼叫，確認問題是否仍存在。
      5. 請與 Apigee Edge 支援團隊聯絡，並提供執行緒傾印、記憶體快照資料和訊息處理器記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log))，協助調查 CPU/記憶體用量偏高的原因。

請參閱：如何控管 Message Processor 上 NodeJS 後端伺服器的逾時

  • NodeJS 後端伺服器會在訊息處理器的 JVM 程序中執行。NodeJS 後端伺服器的逾時值是透過 nodejs.properties 檔案中的 http.request.timeout.seconds 屬性控管。這項屬性預設為 0，也就是說，對於這個訊息處理器所服務機構的所有 API Proxy，逾時功能預設為停用。因此即使 NodeJS 後端伺服器耗時較長，訊息處理器也不會逾時。
  • 不過，如果 NodeJS 後端伺服器耗時較長，且 API 要求所花的時間超過 57 秒，路由器就會逾時，並向用戶端傳送 504 Gateway Timeout 錯誤。

情境 #3 - 用戶端應用程式在路由器/訊息處理器/後端伺服器回應前逾時

如果用戶端應用程式在後端伺服器回應前逾時，可能會收到 504 Gateway Timeout 錯誤。發生這種情況的可能原因如下：

  1. 用戶端應用程式設定的逾時值低於路由器和訊息處理器設定的逾時值：

    舉例來說，如果設定下列逾時值：

    用戶端逾時 路由器逾時 訊息處理器逾時
    50 秒 57 秒 55 秒

    在這種情況下，透過 Edge 取得 API 要求回應的總時間 <= 50 秒。這包括發出 API 要求所花費的時間、Edge (路由器、訊息處理器) 處理要求、要求傳送至後端伺服器 (如適用)、後端處理要求並傳送回應、Edge 處理回應，以及最終將回應傳回給用戶端。

    如果路由器未在 50 秒內回應用戶端，用戶端就會逾時並關閉與路由器的連線。用戶端會收到 504 的回應代碼。

    這會導致 NGINX 設定狀態碼 499，表示用戶端已關閉連線。

診斷

  1. 如果用戶端應用程式在收到路由器回應前逾時，就會關閉與路由器的連線。在這種情況下，您會在特定 API 要求的 NGINX 存取記錄中看到狀態碼 499。

    顯示狀態碼 499 的 NGINX 記錄檔項目範例

  2. 在上述範例中，請注意 NGINX 的 499 狀態，以及經過的總時間為 50.001 秒。這表示用戶端在 50.001 秒後逾時。
  3. 在這種情況下，您會在 Message Processor 記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log).
    Broken Pipe
    2017-06-09 00:00:25,886 org:myorg env:test api:myapi-v1 rev:23 messageid:rrt-1-11193-11467656-1  NIOThread@1 INFO  HTTP.SERVICE - ExceptionHandler.handleException() : Exception java.io.IOException: Broken pipe occurred while writing to channel ClientOutputChannel(ClientChannel[A:XX.XX.XX.XX:8998 Remote host:YY.YY.YY.YY:51400]@23751 useCount=1 bytesRead=0 bytesWritten=486 age=330465ms  lastIO=0ms )
2017-06-09 00:00:25,887  org:myorg env:test api:myapi-v1 rev:23 messageid:rrt-1-11193-11467656-1  NIOThread@1 INFO  HTTP.SERVICE - ExceptionHandler.handleException() : Exception trace:
java.io.IOException: Broken pipe
        at com.apigee.nio.channels.ClientOutputChannel.writePending(ClientOutputChannel.java:51) ~[nio-1.0.0.jar:na]
        at com.apigee.nio.channels.OutputChannel.onWrite(OutputChannel.java:116) ~[nio-1.0.0.jar:na]
        at com.apigee.nio.channels.OutputChannel.write(OutputChannel.java:81) ~[nio-1.0.0.jar:na]
         … <snipped>
  4. 路由器逾時後，會關閉與訊息處理器的連線。當「訊息處理器」完成處理作業時，會嘗試將回應寫入路由器。由於與路由器的連線已關閉，訊息處理器會顯示 Broken Pipe exception。
  5. 在上述情況下，這項例外狀況是預期行為。因此，504 Gateway Timeout 錯誤的實際原因仍是後端伺服器回應時間過長，您需要解決這個問題。

解析度

  1. 如果是自訂後端伺服器，請按照下列步驟操作：
    1. 檢查後端伺服器，判斷為何需要超過 57 秒，並查看是否可以修正/最佳化，以加快回應速度。
    2. 如果無法修正/最佳化後端伺服器，或後端伺服器需要很長時間才能完成作業，請增加路由器和訊息處理器的逾時值。

      建議：依下列順序，為不同元件設定逾時值：

      用戶端逾時 > 路由器逾時 > 訊息處理器逾時 > API Proxy 逾時
  2. 如果是 NodeJS 後端，請執行下列操作：
    1. 檢查 NodeJS 程式碼是否呼叫任何其他後端伺服器，以及是否需要很長時間才能傳回。檢查後端伺服器處理時間較長的原因。
    2. 檢查訊息處理器的 CPU 或記憶體用量是否偏高：
      1. 如果訊息處理器 CPU 使用率偏高，請使用下列指令，每 30 秒產生三份執行緒傾印： 
        JAVA_HOME/bin/jstack -l PID > FILENAME
      2. 如果訊息處理器的記憶體用量偏高，請使用下列指令產生記憶體快照資料：
        sudo -u apigee JAVA_HOME/bin/jmap -dump:live,format=b,file=FILENAME PID
      3. 使用下列指令重新啟動訊息處理器。這應該會降低 CPU 和記憶體用量：
        /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
      4. 監控 API 呼叫，確認問題是否仍存在。
      5. 請與 Apigee Edge 支援團隊聯絡，並提供執行緒傾印、記憶體快照資料和訊息處理器記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log))，協助他們調查 CPU/記憶體用量偏高的原因。

提高路由器和訊息處理器的逾時值

請根據需求，謹慎選擇要在路由器和訊息處理器上設定的逾時值。請勿任意設定過大的逾時值。如需協助，請與 Apigee Edge 支援團隊聯絡。

路由器

chown apigee:apigee /opt/apigee/customer/application/router.properties
  1. 如果路由器電腦上沒有 /opt/apigee/customer/application/router.properties 檔案，請建立該檔案。
  2. 在這個檔案中新增下列這行文字： 
    conf_load_balancing_load.balancing.driver.proxy.read.timeout=TIME_IN_SECONDS

    舉例來說，如要將逾時值設為 120 秒，請按照下列方式設定：

    conf_load_balancing_load.balancing.driver.proxy.read.timeout=120
  3. 確認這個檔案的擁有者是 apigee：
  4. 重新啟動路由器： 
    /opt/apigee/apigee-service/bin/apigee-service edge-router restart
  5. 如果你有多個路由器，請在所有路由器上重複上述步驟。

訊息處理器

  1. 如果訊息處理器電腦上沒有 /opt/apigee/customer/application/message-processor.properties 檔案，請建立該檔案。
  2. 在這個檔案中新增下列這行文字： 
    conf_http_HTTPTransport.io.timeout.millis=TIME_IN_MILLISECONDS

    舉例來說，如要將逾時值設為 120 秒，請按照下列方式設定：

    conf_http_HTTPTransport.io.timeout.millis=120000
  3. 確認這個檔案的擁有者是 apigee： 
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. 重新啟動訊息處理器： 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
  5. 如果您有多個訊息處理器，請在所有訊息處理器上重複上述步驟。

構想：依下列順序，在不同元件上設定逾時值：

用戶端逾時 > 路由器逾時 > 訊息處理器逾時 > API Proxy 逾時

Edge 處理 API 要求的速度緩慢

如果 Edge 速度很慢，且/或處理 API 要求需要很長時間，就會收到 504 Gateway Timeout 錯誤。

診斷

  1. 在 Edge UI 中追蹤受影響的 API。
  2. 請等待錯誤發生，或發出一些 API 呼叫，重現 504 Gateway Timeout 錯誤 (如果您有 API 呼叫)。
  3. 請注意，在這種情況下，您可能會在追蹤記錄中看到成功的回應。
    1. 由於訊息處理器未在路由器/用戶端指定的逾時時間內回覆，因此路由器/用戶端逾時 (以逾時時間最短者為準)。不過，訊息處理器會繼續處理要求，且可能順利完成。
    2. 此外，只有在訊息處理器與 HTTP/HTTPS 後端伺服器通訊時，訊息處理器上設定的 HTTPTransport.io.timeout.millis 值才會觸發。換句話說，如果 API Proxy 內的任何政策 (ServiceCallout 政策除外) 耗費很長時間，就不會觸發這項逾時。
  4. 發生錯誤後，請檢查經過時間最長的特定要求。
  5. 查看每個階段經過的時間，並記下耗時最長的階段。
  6. 如果您在 Service Callout 政策以外的任何政策中，發現最長經過時間，表示 Edge 處理要求的時間過長。
  7. 以下是 UI 追蹤記錄範例，顯示 JavaScript 政策的經過時間非常長：

  8. 在上述範例中，您會發現 JavaScript 政策耗費的時間異常長，約為 245 秒。

解析度

  1. 檢查回應時間過長的政策，以及是否有任何可能需要長時間處理的自訂程式碼。如有這類程式碼，請嘗試修正/最佳化已識別的程式碼。
  2. 如果沒有可能導致處理時間過長的自訂程式碼，請檢查 Message Processor 的 CPU 或記憶體用量是否偏高：
    1. 如果任何訊息處理器 CPU 使用率偏高，請使用下列指令，每 30 秒產生三份執行緒傾印： 
      JAVA_HOME/bin/jstack -l PID > FILENAME
    2. 如果任何訊息處理器的記憶體用量偏高，請使用下列指令產生記憶體快照資料：
      sudo -u apigee JAVA_HOME/bin/jmap -dump:live,format=b,file=FILENAME PID
    3. 使用下列指令重新啟動訊息處理器。這應該會降低 CPU 和記憶體使用量。
      /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
    4. 監控 API 呼叫，確認問題是否仍存在。
    5. 請與 Apigee Edge 支援團隊聯絡，並提供執行緒傾印、記憶體快照資料和訊息處理器記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log))，協助他們調查 CPU/記憶體用量偏高的原因。

使用 API 監控功能診斷問題

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

逐步瞭解範例情境，瞭解如何使用 API 監控功能排解 API 的 5xx 問題。 舉例來說，您可能會想設定快訊，在 504 狀態碼數量超過特定門檻時收到通知。