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

API 监控

方法 1：使用 API Monitoring

如需使用 API 监控功能诊断错误，请执行以下操作：

1. 以具有 适当角色的用户身份 登录 Apigee Edge 界面。

2. 切换到您要调查问题的组织。

   
3. 前往分析 > API 监控 > 调查页面。
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：使用 Trace 工具

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

1. 启用跟踪会话，并选择以下任一选项：
   • 等待出现错误代码为 messaging.adaptors.http.flow.SslHandshakeFailed 的 503 Service Unavailable 错误，或
   • 如果您可以重现问题，请进行 API 调用以重现问题 503 Service Unavailable

2. 确保已启用显示所有 FlowInfo：

   
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（记录的分析数据）阶段，然后点击它。

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. 如果您是私有云用户，则可以使用 NGINX 访问日志来确定有关 HTTP 503 Service Unavailable 的关键信息。

2. 检查 NGINX 访问日志：

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

3. 搜索以查看在特定时长内（如果问题发生在过去）是否存在任何错误代码为 messaging.adaptors.http.flow.SslHandshakeFailed 的 503 错误，或者是否仍有任何请求失败并显示 503。

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 监控、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：比较后端服务器的证书与存储在消息处理器的信任库中的证书

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 界面中，依次选择环境 > 引用。请注意特定信任库参考的参考列中的名称。这将是您的信任库名称。

      （ 查看放大图片）

      

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

      myCompanyTruststoreRef: myCompanyTruststore

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

   1. 获取密钥库或信任库的所有证书。此 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 与目标端点中指定的主机名完全相同，然后使用完整的证书链更新后端的密钥库。

更正后端服务器

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

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>