503 服务不可用 - SSL 握手失败

API 监控

过程 1：使用 API 监控

如需使用 API Monitoring 诊断错误，请执行以下操作：

1. <ph type="x-smartling-placeholder"></ph> 以拥有的用户身份登录 Apigee Edge 界面 适当的角色。

2. 切换到您要在其中调查问题的单位。

   
3. 导航至分析 >API 监控 >调查页面。
4. 选择您观察到错误的具体时间范围。

5. 根据时间绘制错误代码。

   <ph type="x-smartling-placeholder">

6. 选择包含错误代码的单元格 messaging.adaptors.http.flow.SslHandshakeFailed（如图所示） 如下：

   ( 查看大图）

   

7. 有关错误代码的信息 “messaging.adaptors.http.flow.SslHandshakeFailed”显示为 如下所示：

   ( 查看大图）

   

8. 点击查看日志 ，然后展开失败请求对应的行。

   ( 查看大图）

   
9. 在日志窗口中，请注意以下详细信息： <ph type="x-smartling-placeholder">
   </ph>
   • 请求消息 ID
   • 状态代码：503
   • 故障来源：target
   • 错误代码：messaging.adaptors.http.flow.SslHandshakeFailed

Trace

步骤 2：使用跟踪工具

如需使用跟踪工具诊断错误，请执行以下操作：

1. 启用跟踪会话，并且 <ph type="x-smartling-placeholder">
   </ph>
   • 等待错误代码为 503 Service Unavailable 的错误 出现 messaging.adaptors.http.flow.SslHandshakeFailed 次，或
   • 如果您可以重现问题，请进行 API 调用以重现问题 503 Service Unavailable

2. 确保已启用 Show all FlowInfos：

   
3. 选择其中一个失败请求并检查跟踪记录。
4. 浏览跟踪记录的不同阶段，并找到失败的位置。

5. 通常，您会在“目标请求流程开始”阶段之后发现该错误。 如下所示：

   ( 查看大图）

   
6. 请注意跟踪记录中以下各项的值： <ph type="x-smartling-placeholder">
   </ph>
   • 错误： 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（记录的 Google Analytics 数据）阶段，然后点击该阶段。

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

   <ph type="x-smartling-placeholder">
3. 搜索是否存在任何带有错误代码的 503 错误 在特定时间段内messaging.adaptors.http.flow.SslHandshakeFailed （如果问题发生在 过去），或者是否还有 503 仍失败的任何请求。

4. 如果您发现任何与 X-Apigee-fault-code 匹配的 503 错误， messaging.adaptors.http.flow.SslHandshakeFailed 的值，则 确定 X-Apigee-fault-source.

   NGINX 访问日志中的 503 错误示例：

   ( 查看大图）

   

   以上 NGINX 访问日志中的示例条目包含以下值： X-Apigee-fault-code 和 X-Apigee-fault-code

   标头	值
   X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
   X-Apigee-fault-source	target

消息处理器日志

过程 4：使用消息处理器日志

1. 使用 API 监控、跟踪工具、 或 NGINX 访问日志（具体说明请参阅常见诊断步骤）。

2. 在消息处理器日志中搜索特定的请求消息 ID （/opt/apigee/var/log/edge-message-processor/logs/system.log）。您可能会注意到 以下错误：

   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 阶段：比较后端服务器的证书和存储在 消息处理器的信任库

1. 确定后端服务器的证书链。
2. 使用 执行下列步骤： <ph type="x-smartling-placeholder">
   </ph>

   1. 从 TrustStore 元素获取信任库引用名称 位于 TargetEndpoint 的 SSLInfo 部分。

      我们来看看 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 界面中，选择环境 >参考。记下 特定信任库引用的引用列。这将是您的 信任库名称。

      ( 查看大图）

      

   4. 在上面的示例中，信任库名称为：

      myCompanyTruststoreRef：myCompanyTruststore

3. 获取存储在信任库中的证书（在上一步确定） 使用下列 API：

   1. <ph type="x-smartling-placeholder"></ph> 获取密钥库或信任库的所有证书。此 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. <ph type="x-smartling-placeholder"></ph> 从密钥库或信任库获取特定证书的证书详细信息。 此 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
      

      并返回 503 Service Unavailable 以及错误代码 messaging.adaptors.http.flow.SslHandshakeFailed 发送给客户端 应用。

正确的 FQDN

使用正确的 FQDN、有效且完整的证书更新后端服务器的密钥库 链：

1. 如果您没有包含正确 FQDN 的后端服务器证书， 然后从相应的 CA（证书授权机构）获取适当的证书。

2. 确认您拥有 有效且完整的后端服务器证书链。

   <ph type="x-smartling-placeholder">
3. 在您拥有有效且完整的证书链，并包含 叶证书或实体证书中与主机名相同的后端服务器 更新后端的密钥库 完整的证书链

正确的后端服务器

使用正确的后端服务器的主机名更新目标端点：

1. 如果在目标端点中未正确指定主机名，请更新 目标端点具有与后端中的 FQDN 匹配的正确主机名 服务器证书。

2. 保存对 API 代理所做的更改。

   在上面讨论的示例中，如果后端服务器主机名不正确 则您可以使用后端服务器证书中的 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>