503 服務無法使用

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

影片

如要進一步瞭解 503 錯誤,請觀看以下影片:

影片 說明
疑難排解並解決 DNS 問題導致的 503 服務無法使用錯誤 瞭解下列資訊:
  • Apigee Edge 中 DNS 解析和網路相關問題導致的 503 服務無法使用錯誤
  • 疑難排解並解決 DNS 解析問題造成的即時 503 服務無法使用錯誤
疑難排解並解決網路問題導致的 503 服務無法使用錯誤 疑難排解並解決 Apigee Edge 中網路問題造成的即時 503 服務無法使用錯誤

問題

用戶端應用程式收到 HTTP 回應狀態 503,在 API Proxy 呼叫之後,系統會顯示 Service Unavailable 訊息。

錯誤訊息

系統會顯示以下錯誤訊息:

HTTP/1.1 503 Service Unavailable
      

您也可以在 HTTP 回應中看到以下錯誤訊息:

服務無法使用

{
   "fault": {
      "faultstring": "The Service is temporarily unavailable",
      "detail": {
           "errorcode": "messaging.adaptors.http.flow.ServiceUnavailable"
       }
    }
}
      

可能原因

如果 Apigee Edge 的訊息處理器因連線逾時、主機名稱不正確或 SSL 交握失敗而導致 HTTP 回應 503 Service Unavailable,就會發生 HTTP 回應 503 Service Unavailable 和錯誤代碼 messaging.adaptors.http.flow.ServiceUnavailable

出現 503 Service Unavailable 回應的可能原因如下:

原因 說明 誰可以執行疑難排解步驟
DNS 解析有誤導致連線錯誤 目標伺服器的 DNS 解析導致 IP 位址錯誤,進而造成連線錯誤。 Edge Private Cloud 使用者
連線錯誤 網路或連線問題會導致用戶端無法連線至伺服器。 Edge Private Cloud 使用者
目標伺服器主機名稱不正確 指定的目標伺服器主機不正確或含有不需要的字元 (例如空格)。 Edge Public and Private Cloud 使用者
SSL 握手失敗 用戶端和伺服器之間的 TLS/SSL 握手失敗。(有關這個類別的疑難排解請參閱另一個主題)。 Edge Public and Private Cloud 使用者

常見診斷步驟

判斷失敗要求的郵件 ID

追蹤工具

如何使用追蹤工具判斷失敗要求的訊息 ID:

  1. 如果問題仍未解決,請為受影響的 API 啟用追蹤工作階段
  2. 發出 API 呼叫並重現問題 - 503 Service Unavailable (錯誤代碼 messaging.adaptors.http.flow.ServiceUnavailable.)
  3. 請選取其中一個失敗的要求。
  4. 前往 AX 階段,在「階段詳細資料」部分向下捲動,判斷要求的郵件 ID (X-Apigee.Message-ID),如下圖所示。

    「階段詳細資料」部分中的郵件 ID

NGINX 存取記錄檔

如何使用 NGINX 存取記錄判斷失敗要求的郵件 ID:

您也可以參閱 NGINX 存取記錄,判斷 503 錯誤的郵件 ID。如果問題過去發生,或是問題間歇發生,而且您無法在 UI 中擷取追蹤記錄,這個方法就特別實用。請按照下列步驟,從 NGINX 存取記錄確認這項資訊:

  1. 查看 NGINX 存取記錄檔:(/opt/apigee/var/log/edge-router/nginx/ <org>~ <env>.<port#>_access_log)
  2. 搜尋特定 API Proxy 是否在特定時間範圍內 (如果問題在過去) 出現 503 錯誤,或是是否有任何要求仍失敗並顯示 503 錯誤。
  3. 如果 X-Apigee-fault-codeMessaging.adaptors.http.flow.ServiceUnavailable 出現任何 503 錯誤,請記下一或多個這類要求的訊息 ID,如以下範例所示:

    顯示 503 錯誤的範例項目

    顯示狀態碼、訊息 ID、錯誤來源和故障代碼的示例項目

DNS 解析有誤導致連線錯誤

診斷

  1. 判斷失敗要求的訊息 ID。
  2. 在訊息處理器記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log) 中搜尋特定要求訊息 ID,可能會發現以下錯誤:

    出現 onConnectTimeout 錯誤,代表訊息處理器無法在預設的連線逾時期限 (預設值:3 秒) 內連線到後端伺服器。
    2019-08-14 09:11:49,314 org:myorg env:prod api:Employees rev:1 messageid:mo-96cf6757a-9401-21-1 NIOThread@0 ERROR HTTP.CLIENT - HTTPClient$Context.onTimeout() : ClientChannel[Connected:]@164162 useCount=1 bytesRead=0 bytesWritten=0 age=3001ms lastIO=3001ms .onConnectTimeout connectAddress=www.abc.com/11.11.11.11  resolvedAddress=www.abc.com/22.22.22.22
    
    2019-08-14 09:11:49,333 org:myorg env:prod api:Employees rev:1 messageid:mo-96cf6757a-9401-21-1 NIOThread@0 ERROR ADAPTORS.HTTP.FLOW - RequestWriteListener.onTimeout() : RequestWriteListener.onTimeout(HTTPRequest@6b393600)
          
  3. 請記下 onConnectTimeout 錯誤中的已解析 IP 位址,然後檢查該 IP 位址是否適用於你的後端伺服器。如果 IP 位址有效,請前往連線錯誤
  4. 如果 IP 位址無效,最有可能的原因是 DNS 解析發生問題。
  5. 重複執行步驟 3 和步驟 4,再完成幾個失敗的 API 要求,並確認系統是否顯示相同或其他無效的 IP 位址。
  6. 在郵件處理器記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log) 中搜尋包含重要字詞「DNS Refresh」的郵件。檢查是否每隔一段時間才在郵件處理器的 DNS 快取中加入錯誤或無效的 IP 位址。
    2019-08-14 09:11:49,314 org:myorg env:prod api:Employees rev:1 messageid:mo-96cf6757a-9401-21-1 NIOThread@0 INFO c.a.p.h.d.DNSCachedAddress - DNSCachedAddress.reportDifferences() : DNS Refresh for host: apitarget-uat.schemeweb.co.uk:4436. Added 2 IPs [www.abc.com/22.22.22.22, www.abc.com/33.33.33.33] Removed 1 IPs [www.abc.com/11.11.11.11]
          
  7. 如果權威 DNS 伺服器或 /etc/resolv.conf 中設定的名稱伺服器有任何問題,就可能會發生這個問題。

    通常,有一或多個權威 DNS 伺服器設定為執行 DNS 解析。如果沒有權威 DNS 伺服器,系統會改回「/etc/resolv.conf」中的設定,並視情況執行 DNS 解析作業。舉例來說,如果 /etc/resolv.conf 設為使用特定名稱伺服器,系統就會使用這些名稱伺服器執行 DNS 解析。
  8. 如果 /etc/resolv.conf 中指定的權威 DNS 伺服器或名稱伺服器有任何問題,系統會將後端伺服器主機名稱解析為錯誤/無效的 IP 位址。錯誤/無效的 IP 位址會儲存在郵件處理器的 DNS 快取中。
    1. 如果 /etc/resolv.conf 中指定的權威 DNS 伺服器或名稱伺服器問題持續發生,郵件處理器的 DNS 快取中會繼續保留無效/無效的 IP 位址。只要錯誤的 IP 位址儲存在郵件處理器的 DNS 快取中,使用特定後端伺服器的所有 API 要求就會失敗並傳回 503 錯誤。
    2. 如果 /etc/resolv.conf 中指定的權威 DNS 伺服器或名稱伺服器發生問題,DNS 快取會間歇地儲存良好和錯誤的 IP 位址。在這種情況下,凡是使用特定後端伺服器的 API,這些 API 都會間歇發生 503 錯誤。
  9. 如果 DNS 伺服器的問題持續發生,客戶可能會持續失敗。如果 DNS 伺服器的問題不穩,您會看到間歇性失敗。也就是說,每當後端伺服器主機名稱解析為錯誤的 IP 位址時,您都會看到 503 錯誤。另外,當後端伺服器主機名稱解析為良好的 IP 位址時,您也能觀察到成功的回應。

解析度

請與作業系統管理員聯絡,並修正 DNS 伺服器的問題。

  1. 如果權威 DNS 伺服器或 /etc/resolv.conf 中指定的名稱伺服器發生問題,請使用適當的伺服器修正問題,以解決這個問題。
  2. 如果使用郵件處理器的系統中的 /etc/resolv.conf 設定發生問題,請修正設定問題。

連結錯誤

當 Apigee Edge 訊息處理器嘗試連線至後端伺服器,但發生下列其中一項問題時,就會發生連線錯誤:

  • 訊息處理器無法在預設的連線逾時期限內連線。(預設值:3 秒)
  • 後端伺服器會拒絕連線。

診斷

  1. 判斷失敗要求的訊息 ID。
  2. 在訊息處理器記錄 (/opt/apigee/var/log/edge-message-processor/logs/system.log) 中搜尋特定要求訊息 ID。您可能會遇到以下錯誤:
    1. onConnectTimeout 錯誤表示訊息處理器無法在預設連線逾時期限內連線至後端伺服器。
      2016-06-23 09:11:49,314 org:myorg env:prod api:Employees rev:1 messageid:mo-96cf6757a-9401-21-1 NIOThread@2 ERROR HTTP.CLIENT - HTTPClient$Context.onTimeout() : ClientChannel[C:]@10 useCount=1 bytesRead=0 bytesWritten=0 age=3001ms lastIO=3001ms .onConnectTimeout connectAddress=www.abc.com/11.11.11.11:80 resolvedAddress=www.abc.com/11.11.11.11
      2016-06-23 09:11:49,333 org:myorg env:prod api:Employees rev:1 messageid:mo-96cf6757a-9401-21-1 NIOThread@2 ERROR ADAPTORS.HTTP.FLOW - RequestWriteListener.onTimeout() : RequestWriteListener.onTimeout(HTTPRequest@6b393600)
      
    2. java.net.ConnectException: Connection refused」錯誤表示後端伺服器拒絕連線。
      14:40:16.531 +0530
      2016-06-17 09:10:16,531 org:myorg env:prod api:www.abc.com rev:1 rrt07eadn-22739-40983870-15 NIOThread@2 ERROR HTTP.CLIENT - HTTPClient$Context.onConnectFailure() : connect to www.abc.com:11.11.11.11:443 failed with exception {}
      java.net.ConnectException: Connection refused
      at sun.nio.ch.SocketChannelImpl.checkConnect(Native Method) ~[na:1.7.0_75]
      at sun.nio.ch.SocketChannelImpl.finishConnect(SocketChannelImpl.java:739) ~[na:1.7.0_75]
      at com.apigee.nio.ClientChannel.finishConnect(ClientChannel.java:121) ~[nio-1.0.0.jar:na]
      at com.apigee.nio.handlers.NIOThread.run(NIOThread.java:108) ~[nio-1.0.0.jar:na]
      
  3. 使用 telnet 指令確認是否能從各個訊息處理器直接連線至特定後端伺服器:
    1. 如果後端伺服器會解析為單一 IP 位址,請使用下列指令:
      telnet BackendServer-IPaddress 443
                
    2. 如果後端伺服器會解析多個 IP 位址,請在 telnet 指令中使用後端伺服器的主機名稱,如下所示:
      telnet BackendServer-HostName 443
                
  4. 如果您可以連線至後端伺服器,您可能會看到類似 Connected to backend-server 的訊息。如果您無法連線至後端伺服器,可能是因為訊息處理器的 IP 位址未在特定後端伺服器的許可清單中。

解析度

將存取特定後端伺服器上的訊息處理器 IP 位址存取權授予訊息處理器,以允許來自邊緣訊息處理器的流量存取您的後端伺服器。舉例來說,在 Linux 上,您可以使用 iptables 允許來自後端伺服器上的訊息處理器 IP 位址的流量。

如果問題持續發生,請與網路管理員聯絡,找出並修正問題。如需 Apigee 的進一步協助,請與 Apigee 支援團隊聯絡。

目標伺服器主機名稱不正確

診斷

如果目標伺服器中指定的主機名稱不正確,您會收到 503 Service Unavailable 回應以及錯誤代碼 messaging.adaptors.http.flow.ServiceUnavailable.

追蹤工具

如何使用追蹤工具進行診斷:

  1. 如果問題仍未解決,請為受影響的 API 啟用追蹤工作階段
  2. 發出 API 呼叫並重現問題 - 503 Service Unavailable (錯誤代碼 messaging.adaptors.http.flow.ServiceUnavailable.)
  3. 請選取其中一個失敗的要求。
  4. 瀏覽追蹤記錄的各個階段,找出發生錯誤的位置。
  5. 選取含有錯誤的 FlowInfo。您可以在 error.cause 欄位中找到詳細資訊,藉此瞭解失敗原因,如以下範例所示:

    在追蹤記錄中顯示 error.cause 的要求示例

    在追蹤記錄中顯示 error.cause 的要求範例
  6. 如果看到 error.cause 顯示「無法連上主機」,表示發生錯誤的可能原因如下:
    • 目標伺服器/目標端點設定中指定的主機名稱不正確,或含有不必要的空格或特殊字元。

      舉例來說,主機名稱包含多餘的空格,如下所示:
      "demo-target.apigee.net "
                        
    • 使用 AssignMessageJavaScript 政策在 API Proxy 中由 target.url 變數覆寫的主機名稱不正確,或含有空格或任何其他不需要的特殊字元。
  7. 檢查目標端點設定和/或目標伺服器定義,確認目標伺服器的主機名稱是否不正確,或含有不需要的空格或特殊字元。
  8. 如果目標伺服器主機是以動態方式建立,請檢查用來建立目標伺服器的適當政策 (例如 AssignMessage/JavaScript 政策)。請檢查目標伺服器的主機名稱是否不正確,或是否含有不必要的空格或特殊字元。
  9. 決定目標伺服器主機名稱後,請對主機名稱執行 nslookup/dig 指令,看看能否成功解析。

    舉例來說,在含有不需要空格的主機名稱上執行 nslookup 指令,會傳回下列輸出內容:

    nslookup "demo-target.apigee.net "
    Server:	49.205.75.2
    Address:	49.205.75.2#53
    
    ** server can't find demo-target.apigee.net\032: NXDOMAIN
    
  10. 如果作業系統指令 nslookup 也無法解析主機名稱,則這個問題可能是目標伺服器使用的主機名稱不正確。

    前往「解析度」

訊息處理器記錄

如何使用郵件處理器記錄進行診斷:

  1. 判斷失敗要求的訊息 ID
  2. 在郵件處理器記錄中搜尋郵件 ID。(/opt/apigee/var/log/edge-message-processor/logs/system.log)。
  3. 如果看到下列警告/錯誤訊息,表示「訊息處理者」無法解析主機名稱。由於系統會延後訊息,因此可能不會針對所有郵件 ID/要求顯示這則警告訊息。
    org:myorg env:prod api:TestTargetServer rev:2 messageid:<messageid>  NIOThread@0 WARN S.HTTPCLIENTSERVICE - DNSCache$2.failed() : Failed to resolve hostname www.somehost.com . Reason mocktarget.apigee.net : Name or service not known. This log message will snooze for 2 hours
        
  4. 後面會顯示警告訊息,因為無法連上目標伺服器主機,因此「郵件處理器」會從 DNS 快取中移除位址。
    org:myorg env:prod api:TestTargetServer rev:2 messageid:<messageid> NIOThread@0 WARN  c.a.p.h.d.DNSCachedAddress - DNSCachedAddress.addressNotReachable() : The last address has been removed from Address list null refreshing
        
  5. 系統可能會顯示訊息處理者失敗訊息,並顯示「無法連上主機」例外狀況,有時錯誤訊息會將主機名稱顯示為:
    org:myorg env:prod api:TestTargetServer rev:2 messageid:<messageid>  NIOThread@0 ERROR HTTP.CLIENT - HTTPClient$Context.onConnectFailure() :  connect to demo-target.apigee.net  failed with exception {}
    java.lang.RuntimeException: Host not reachable
    	at com.apigee.protocol.http.HTTPClient$Context.initConnect(HTTPClient.java:704)
    	at com.apigee.protocol.http.HTTPClient$Context.send(HTTPClient.java:675)
    	at com.apigee.messaging.adaptors.http.flow.data.TargetRequestSender.sendRequest(TargetRequestSender.java:234)
    	…<snipped>
        
  6. 主機名稱有時會顯示為 null,因為主機名稱無法解析或連線,如下所示:
    org:myorg env:prod api:TestTargetServer rev:2 messageid:<messageid>  NIOThread@0 ERROR HTTP.CLIENT - HTTPClient$Context.onConnectFailure() :  connect to null failed with exception {}
    java.lang.RuntimeException: Host not reachable
    	at com.apigee.protocol.http.HTTPClient$Context.initConnect(HTTPClient.java:704)
    	at com.apigee.protocol.http.HTTPClient$Context.send(HTTPClient.java:675)
    	at com.apigee.messaging.adaptors.http.flow.data.TargetRequestSender.sendRequest(TargetRequestSender.java:234)
    	…<snipped>
        
  7. Host not reachable 錯誤通常發生於下列任一情況:
    • 目標伺服器/目標端點設定中指定的主機名稱不正確,或含有不必要的空格或特殊字元。

      舉例來說,下列錯誤訊息中,主機名稱「demo-target.apigee.net」中有不必要的空間:
      NIOThread@0 ERROR HTTP.CLIENT - HTTPClient$Context.onConnectFailure() :  connect to demo-target.apigee.net  failed with exception
              
    • 使用 AssignMessageJavaScript 政策在 API Proxy 中由 target.url 變數覆寫的主機名稱不正確,或含有空格或任何其他不需要的特殊字元。
  8. 使用下列其中一項方法,確定訊息處理器嘗試通訊的目標伺服器主機名稱:
    1. 仔細檢查包含 Host not reachable 的錯誤訊息。
    2. 如果錯誤訊息顯示主機名稱,請複製主機名稱 (包括任何空格或任何特殊字元)。
    3. 如下列錯誤訊息所示,如果錯誤訊息顯示主機名稱為 null,請參閱:
      org:myorg env:prod api:TestTargetServer rev:2 messageid:<messageid>  NIOThread@0 ERROR HTTP.CLIENT - HTTPClient$Context.onConnectFailure() :  connect to null failed with exception {}
              
      1. 檢查失敗 API Proxy 中使用的目標伺服器定義,判斷主機名稱。
      2. 如果目標伺服器主機是動態建立,請檢查用來建立目標伺服器的適當政策,例如 AssignMessage/JavaScript 政策
  9. 決定目標伺服器主機名稱後,請對主機名稱執行 nslookup/dig 指令,檢查主機是否能成功解析。

    例如,對含有空格的主機名稱執行 nslookup 指令

    nslookup "demo-target.apigee.net "
    Server:	49.205.75.2
    Address:	49.205.75.2#53
    
    ** server can't find demo-target.apigee.net\032: NXDOMAIN
          
  10. 如果作業系統指令 nslookup 也無法解析主機名稱,表示這個問題是目標伺服器使用的主機名稱不正確。

解析度

  1. 確認目標端點設定目標伺服器定義中指定的目標伺服器主機名稱正確無誤,且沒有任何不需要的空格或特殊字元。
  2. 如果您使用任何 AssignMessage/JavaScript 政策動態產生目標伺服器主機名稱,請調查政策定義和程式碼,並確認目標伺服器主機名稱已正確產生。

SSL 握手失敗

我們完整的疑難排解教戰手冊專門處理 TLS/SSL 握手錯誤。請參閱 SSL 握手失敗

判斷問題來源

有時在傳入 (北行) 或傳出 (南行) 連線上可能會發生特定類型的錯誤。用戶端應用程式和 Edge 之間發生傳入 (北行) 錯誤。Edge 與後端目標伺服器之間發生傳出 (southbound) 錯誤。如要診斷這類問題,您的第一項工作是找出錯誤發生在北極連線還是南極連線上。

瞭解北向和向南連接

在 Edge 中,傳入或傳出連線可能會發生 503 Service Unavailable 錯誤:

  • 連入 (或北行) 連線 - 用戶端應用程式與邊緣路由器之間的連線。路由器是 Apigee Edge 的元件,可處理傳送至系統的傳入要求。
  • 傳出 (或南行) 連線 - 邊緣訊息處理器與後端伺服器之間的連線。訊息處理器是 Apigee Edge 的元件,可透過 Proxy 將 API 要求傳送至後端目標伺服器。

如果您是 Edge Public Cloud 使用者,您可能不知道路由器或訊息處理器等內部元件。公有雲使用者無法查看或存取這些內部元件。對於不需要直接存取這些元件的問題,我們會盡可能提供替代方法。

下圖說明 Apigee Edge 的北行連線和南行連線。

用戶端應用程式 (北行連線) 通過 Edge 至後端伺服器 (南界連線) 的流程

判斷發生「503 Service Unavailable」錯誤的位置

請採取下列任一程序,判斷「503 服務無法使用」錯誤是否發生在北行或南極連線。

UI 追蹤

如何使用 UI 追蹤判斷錯誤發生的位置:

  1. 如果問題仍未解決,請為受影響的 API 啟用 UI 追蹤。
  2. 如果 API 要求的 UI 追蹤記錄在目標要求流程期間發生 503 Service Unavailable 錯誤,或是由後端伺服器傳送,問題就會成為 southbound (在訊息處理器和後端伺服器之間)。
  3. 如果您找不到特定 API 呼叫的追蹤記錄,可能是因為用戶端應用程式與路由器之間出現 Northbound

API 監控

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

逐步操作範例情境,示範如何使用 API Monitoring 排解 API 的 5xx 問題。舉例來說,您可以設定快訊,讓系統在 messaging.adaptors.http.flow.ServiceUnavailable 錯誤數量超過特定門檻時收到通知。

NGINX 存取記錄檔

如何使用 UI 追蹤判斷錯誤發生的位置:

如果問題過去發生,或是問題間歇發生,導致您無法擷取追蹤記錄,請按照下列步驟操作:

  1. 檢查 NGINX 存取記錄 (/opt/apigee/var/log/edge-router/nginx/ org-env.port_access_log )。
  2. 搜尋特定 API Proxy 是否有任何 503 錯誤。
  3. 如果您發現特定 API 在特定時間發生任何 503 錯誤,則該問題在訊息處理器和後端伺服器之間 (訊息處理器和後端伺服器之間) 的南開連線時發生。
  4. 如果沒有,則問題是在用戶端應用程式與路由器之間 (ID 為北行) 連線時發生。