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

API Monitoring

程序 1：使用 API Monitoring

如要使用 API 監控功能診斷錯誤，請按照下列步驟操作：

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

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

   
3. 依序前往「Analyze」>「API Monitoring」>「Investigate」頁面。
4. 選取您觀察到錯誤的特定時間範圍。

5. 繪製「錯誤代碼」與「時間」的關係圖。

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

   ( 查看較大圖片)

   

7. 故障代碼資訊 messaging.adaptors.http.flow.SslHandshakeFailed會顯示如下：

   ( 查看較大圖片)

   

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

   ( 查看較大圖片)

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

追蹤記錄

程序 #2：使用追蹤工具

如要使用「追蹤」工具診斷錯誤，請按照下列步驟操作：

1. 啟用「追蹤工作階段」，並選擇下列其中一種做法：
   • 等待發生 503 Service Unavailable 錯誤 (錯誤代碼為 messaging.adaptors.http.flow.SslHandshakeFailed)，或
   • 如果可以重現問題，請發出 API 呼叫來重現問題 503 Service Unavailable

2. 確認已啟用「顯示所有流程資訊」：

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

5. 您通常會在「Target Request Flow Started」(目標要求流程已啟動) 階段後發現錯誤，如下所示：

   ( 查看較大圖片)

   
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 表示 SSL 交握失敗，因為 Apigee Edge 的訊息處理器無法驗證後端伺服器的憑證。
7. 在追蹤記錄中前往「AX」(記錄的 Analytics 資料) AX階段，然後按一下。

8. 向下捲動至「Phase Details Error Headers」部分，並判斷「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. 如果您是私有雲使用者，可以透過 NGINX 存取記錄判斷 HTTP 503 Service Unavailable 的金鑰資訊。

2. 檢查 NGINX 存取記錄：

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

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

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

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

   ( 查看較大圖片)

   

   上述 NGINX 存取記錄檔的範例項目具有下列 X-Apigee-fault-code 和 X-Apigee-fault-source 值：

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

訊息處理器記錄

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

1. 如「常見診斷步驟」一文所述，使用 API Monitoring、Trace 工具或 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

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

第 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：比較後端伺服器的憑證和儲存在 Message Processor 信任儲存區中的憑證

1. 判斷後端伺服器的憑證鏈結。
2. 請按照下列步驟，判斷儲存在 Message Processor 信任儲存區中的憑證：

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

      讓我們看看設定中的 SSLInfo 部分範例：TargetEndpoint

      <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」。請記下特定信任儲存區參照「Reference」欄中的名稱。這會是您的信任儲存庫名稱。

      ( 查看較大圖片)

      

   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 是金鑰儲存庫的名稱
      • $TOKEN 會設為 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述
      • 本範例使用的 curl 選項說明請參閱「使用 curl」

      輸出內容範例：

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

      [
        "serverCert"
      ]

   2. 從金鑰儲存區或信任儲存區取得特定憑證的憑證詳細資料。 這個 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 是金鑰儲存庫的名稱
      • 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、有效且完整的憑證鏈結更新後端伺服器的金鑰儲存區：

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

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

3. 取得有效且完整的憑證鏈結後，請確認分葉或實體憑證中的後端伺服器 FQDN，與目標端點中指定的主機名稱相同，然後使用完整的憑證鏈結更新後端的 KeyStore。

修正後端伺服器

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

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

2. 儲存 API Proxy 變更。

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

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