503 服務無法使用 - SSL 握手失敗

API Monitoring

程序 #1：使用 API 監控功能

如何使用 API Monitoring 診斷錯誤：

1. 以 適當角色的使用者 登入 Apigee Edge UI。

2. 切換至您想要調查問題的機構。

   
3. 前往「分析」>「API 監控」>「調查」頁面。
4. 請選取你發現錯誤的特定時間範圍。

5. 將「Fault Code」與「Time」進行比較。

6. 選取含有錯誤代碼 messaging.adaptors.http.flow.SslHandshakeFailed 的儲存格，如下所示：

   ( 查看較大圖片)。

   

7. 錯誤代碼 messaging.adaptors.http.flow.SslHandshakeFailed 的相關資訊如下所示：

   ( 查看較大圖片)。

   

8. 按一下「查看記錄」 ，然後展開失敗要求的資料列。

   ( 查看較大圖片)。

   
9. 在「記錄檔」視窗中記下下列詳細資料：
   • 要求郵件 ID
   • 狀態碼： 503
   • Fault 資料來源： target
   • 錯誤代碼： messaging.adaptors.http.flow.SslHandshakeFailed

追蹤記錄

程序 2：使用追蹤工具

如何使用追蹤工具診斷錯誤：

1. 啟用追蹤工作階段，並採取下列任一做法：
   • 等待發生錯誤代碼 messaging.adaptors.http.flow.SslHandshakeFailed 的 503 Service Unavailable 錯誤，或
   • 如果可以重現問題，請透過 API 呼叫來重現問題 503 Service Unavailable

2. 確保已啟用「Show all FlowInfos」：

   
3. 請選取其中一個失敗的要求，然後檢查追蹤記錄。
4. 瀏覽追蹤記錄的不同階段，找出發生錯誤的位置。

5. 您會在「目標要求流程」開始階段之後看到錯誤，如下所示：

   ( 查看較大圖片)。

   
6. 記下追蹤記錄中的下列值：
   • 錯誤： SSL Handshake failed sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   • error.cause: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   • error.class: com.apigee.errors.http.server.ServiceUnavailableException
   • 錯誤 SSL Handshake failed sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target 值表示 Apigee Edge 的訊息處理者無法驗證後端伺服器的憑證，因此 SSL 握手失敗。
7. 前往追蹤記錄中的「AX」(Analytics (分析) 已記錄) 階段，然後按一下該階段。

8. 向下捲動至「階段詳細資料錯誤標頭」區段，確定 X-Apigee-fault-code 和 X-Apigee-fault-source 及 X-Apigee-Message-ID 的值如下：

   ( 查看較大圖片)。

   
9. 記下 X-Apigee-fault-code、X-Apigee-fault-source 和 X-Apigee-Message-ID 的值：

錯誤標頭	值
X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
X-Apigee-fault-source	target
X-Apigee-Message-ID	MESSAGE_ID

NGINX

程序 3：使用 NGINX 存取記錄檔

如何使用 NGINX 存取記錄檔診斷錯誤：

1. 如果您是 Private Cloud 使用者，即可使用 NGINX 存取記錄檔來判斷 HTTP 503 Service Unavailable 的重要資訊。

2. 查看 NGINX 存取記錄檔：

   /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

3. 搜尋特定期間內 (問題過去是否發生)，或是否有任何要求仍為 503 失敗，且錯誤代碼為 messaging.adaptors.http.flow.SslHandshakeFailed。503

4. 如果發現 X-Apigee-fault-code 與 messaging.adaptors.http.flow.SslHandshakeFailed 值相符的任何 503 錯誤，請判斷 X-Apigee-fault-source 的值。

   NGINX 存取記錄中的 503 錯誤示例：

   ( 查看較大圖片)。

   

   上述 NGINX 存取記錄範例中的「X-Apigee-fault-code」X-Apigee-fault-code 和「X-Apigee-fault-source」X-Apigee-fault-code 值有下列值：

   標頭	值
   X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
   X-Apigee-fault-source	target

訊息處理器記錄

程序 #4：使用訊息處理器記錄

1. 請按照常見診斷步驟的說明，使用 API 監控、追蹤工具或 NGINX 存取記錄檔，找出其中一個失敗要求的訊息 ID。

2. 在訊息處理器記錄檔 (/opt/apigee/var/log/edge-message-processor/logs/system.log) 中搜尋特定要求訊息 ID。您可能會注意到下列錯誤：

   org:myorg env:test api:MyProxy rev:1
   messageid:myorg-28247-3541813-1
   NIOThread@1 ERROR HTTP.CLIENT - HTTPClient$Context.handshakeFailed() :
   SSLClientChannel[Connected: Remote:X.X.X.X:443
   Local:192.168.194.140:55102]@64596 useCount=1
   bytesRead=0 bytesWritten=0 age=233ms  lastIO=233ms
   isOpen=true handshake failed, message: General SSLEngine problem
   

   上述錯誤表示訊息處理器與後端伺服器之間的 SSL 握手失敗。

   然後是具有詳細堆疊追蹤的例外狀況，如下所示：

   org:myorg env:test api:MyProxy rev:1
   messageid:myorg-28247-3541813-1
   NIOThread@1 ERROR ADAPTORS.HTTP.FLOW - RequestWriteListener.onException() :
   RequestWriteListener.onException(HTTPRequest@1522922c)
   javax.net.ssl.SSLHandshakeException: General SSLEngine problem
   	at sun.security.ssl.Handshaker.checkThrown(Handshaker.java:1478)
   	at sun.security.ssl.SSLEngineImpl.checkTaskThrown(SSLEngineImpl.java:535)
   	... <snipped>
   Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
   	at sun.security.ssl.Alerts.getSSLException(Alerts.java:203)
   	at sun.security.ssl.SSLEngineImpl.fatal(SSLEngineImpl.java:1728)
   	... <snipped>
   Caused by: sun.security.validator.ValidatorException: PKIX path building failed:
   sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid
   certification path to requested target
   	at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:397)
   	at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:302)
   	... <snipped>
     

   請注意，握手失敗的原因如下：

   Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

   這表示 Apigee Edge 的訊息處理器無法驗證後端伺服器的憑證，因此 SSL 握手失敗。

第 1 階段

第 1 階段：決定後端伺服器的憑證鏈

請使用下列其中一種方法確定後端伺服器的憑證鏈：

openssl s_client -connect BACKEND_SERVER_HOST_NAME:PORT#

Certificate chain
 0 s:/CN=mocktarget.apigee.net
   i:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
 1 s:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
   i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
 2 s:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
   i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1

第 2 階段

第 2 階段：比較儲存在訊息處理器信任儲存庫中的後端伺服器憑證和憑證

1. 決定後端伺服器的憑證鏈結。
2. 請按照下列步驟，判斷儲存在訊息處理器信任儲存庫中的憑證：

   1. 從 TargetEndpoint 的 SSLInfo 區段，從 TrustStore 元素取得信任儲存庫參照名稱。

      以下是 TargetEndpoint 設定中的 SSLInfo 部分範例：

      <TargetEndpoint name="default">
      ...
         <HTTPTargetConnection>
            <Properties />
            <SSLInfo>
               <Enabled>true</Enabled>
               <ClientAuthEnabled>true</ClientAuthEnabled>
               <KeyStore>ref://myKeystoreRef</KeyStore>
               <KeyAlias>myKey</KeyAlias>
               <TrustStore>
                  ref://myCompanyTrustStoreRef
               </TrustStore>
            </SSLInfo>
         </HTTPTargetConnection>
         ...
      </TargetEndpoint>
      

   2. 在上述範例中，TrustStore 參照名稱為 myCompanyTruststoreRef。

   3. 在 Edge UI 中，依序選取「Environments」>「References」。記下特定信任儲存庫參考資料中的「參考資料」欄中的名稱。這會是您的信任儲存庫名稱。

      ( 查看較大圖片)。

      

   4. 在上述範例中，信任儲存庫的名稱為：

      myCompanyTruststoreRef：myCompanyTruststore

3. 使用以下 API 取得儲存在信任儲存庫中的憑證 (於上一步決定)：

   1. 取得 KeyStore 或 Truststore 的所有憑證。這個 API 會列出特定信任儲存庫中的所有憑證。

      公有雲使用者：

      curl -v -X GET https//api.enterprise.apigee.com/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs -H "Authorization: Bearer $TOKEN"
      

      Private Cloud 使用者：

      curl -v -X GET http://MANAGEMENT_HOST:PORT_#/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs -H "Authorization: Bearer $TOKEN"
      

      地點：

      • ORGANIZATION_NAME 是機構名稱
      • ENVIRONMENT_NAME 是環境的名稱。
      • KEYSTORE_NAME 是 KeyStore 名稱
      • $TOKEN 已設為您的 OAuth 2.0 存取權杖，如取得 OAuth 2.0 存取權杖一節中所述
      • 本範例中使用的 curl 選項相關說明請參閱「使用 curl」

      輸出內容範例：

      範例信任儲存庫 myCompanyTruststore 中的憑證如下：

      [
        "serverCert"
      ]
      

   2. 從 KeyStore 或 Truststore 取得特定憑證的認證詳細資料。這個 API 會傳回特定信任儲存庫中特定憑證的相關資訊。

      公有雲使用者：

      curl -v -X GET https//api.enterprise.apigee.com/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs/CERT_NAME -H "Authorization: Bearer $TOKEN"
      

      Private Cloud 使用者

      curl -v -X GET http://MANAGEMENT_HOST:PORT_#>/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs/CERT_NAME -H "Authorization: Bearer $TOKEN"
      

      地點：

      • ORGANIZATION_NAME 是機構名稱
      • ENVIRONMENT_NAME 是環境的名稱。
      • KEYSTORE_NAME 是 KeyStore 名稱
      • CERT_NAME 是憑證的名稱
      • $TOKEN 已設為您的 OAuth 2.0 存取權杖，如取得 OAuth 2.0 存取權杖一節中所述
      • 本範例中使用的 curl 選項相關說明請參閱「使用 curl」

      輸出內容範例

      serverCert 的詳細資料會顯示下列主體和核發者：

      節能綠葉/實體憑證：

      "subject": "CN=mocktarget.apigee.net",
      "issuer": "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      

      中繼憑證：

      "subject" : "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      "issuer" : "CN=GTS Root R1, O=Google Trust Services LLC, C=US",
      

4. 驗證步驟 1 中取得的實際伺服器憑證，以及與步驟 3 中取得的信任儲存庫中儲存的憑證是否相符。如果兩者不相符，則就是問題原因。

   如上例所示，我們一次來看看一個憑證：

   1. 分葉憑證：

      從後端伺服器：

      s:/CN=mocktarget.apigee.net
      i:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
      

      透過郵件處理器 (用戶端) 的信任儲存庫：

      "subject": "CN=mocktarget.apigee.net",
      "issuer": "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      

      儲存在信任儲存庫中的分葉憑證與後端伺服器相符。

   2. 中繼憑證：

      從後端伺服器：

      s:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
      i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
      

      透過郵件處理器 (用戶端) 的信任儲存庫：

      "subject" : "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      "issuer" : "CN=GTS Root R1, O=Google Trust Services LLC, C=US",
      

      儲存在信任儲存庫中的中繼憑證與後端伺服器相符。

   3. 根憑證：

      從後端伺服器：

      s:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
      i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
      

      訊息處理器的信任儲存庫中完全缺少根憑證。

   4. 由於信任儲存庫中缺少根憑證，訊息處理工具會擲回以下例外狀況：

      sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
      

      並將包含錯誤代碼 messaging.adaptors.http.flow.SslHandshakeFailed 的 503 Service Unavailable 傳回用戶端應用程式。

正確 FQDN

使用正確的 FQDN、有效且完整的憑證鏈，更新後端伺服器的 KeyStore：

1. 如果您沒有具有正確 FQDN 的後端伺服器憑證，請透過適當的 CA (憑證授權單位) 取得適當的憑證。

2. 確認您具備有效且完整的後端伺服器憑證鏈結。

3. 當您在分葉或實體憑證中，取得有效且完整的憑證鏈結，且包含正確的後端伺服器 FQDN 與目標端點中指定的主機名稱相同時，請將後端的 KeyStore 更新為完整的憑證鏈。

正確的後端伺服器

使用正確的後端伺服器的主機名稱更新目標端點：

1. 如果在目標端點中指定的主機名稱不正確，請更新目標端點，使其的主機名稱與後端伺服器憑證中的 FQDN 相符。

2. 儲存對 API Proxy 所做的變更。

   在上述範例中，若指定錯誤的後端伺服器主機名稱，您可以使用後端伺服器憑證 (即 backend.apigee.net) 中的 FQDN 進行修正，如下所示：

   <TargetEndpoint name="default">
      …
      <HTTPTargetConnection>
         <Properties />
         <SSLInfo>
            <Enabled>true</Enabled>
            <TrustStore>ref://myTrustStoreRef</TrustStore>
         </SSLInfo>
         <URL>https://backend.apigee.net/resource</URL>
      </HTTPTargetConnection>
   </TargetEndpoint>