如何故障排除 API Gateway 的 VPC 链接集成的 500 错误？

简述

带有 VPC 链接的 AWS API Gateway 可能无法将流量转发至后端资源并返回 HTTP 500 状态码，原因如下：

• VPC 链接处于故障状态。或者，端点服务已删除或处于已被拒绝状态。
• 目标组的已注册目标运行状况不正常或未在使用中。
  注意：如果在 60 天内没有通过 VPC 链接发送流量，则该链接将变为停用状态。有关更多信息，请参阅为 HTTP API 使用 VPC 链接。
• 安全组禁止特定端口上的流量。
• 网络访问控制列表会屏蔽流量。
• 目标未监听目标端口。
• 域名证书与已启用 TLS 的网络负载均衡器或应用程序负载均衡器不匹配。

如果您的 API 已启用 Amazon CloudWatch Logs，则执行日志中会显示一条错误信息，说明错误原因。

CloudWatch logs 中的 HTTP 500 错误信息示例

"Thu Aug 04 17:48:21 UTC 2022 : Execution failed due to configuration error: There was an internal error while executing your request Thu Aug 04 17:48:21 UTC 2022 : Method completed with status: 500"

-或-

"Thu Aug 04 19:50:21 UTC 2022 : Execution failed due to configuration error: Host name 'domain.com.com' does not match the certificate subject provided by the peer (CN=myinstance.com)
Thu Aug 04 19:50:21 UTC 2022 : Method completed with status: 500"

解决方案

确认导致出现错误的原因

启用 CloudWatch API 日志记录。请务必配置执行日志记录。

注意：配置日志记录设置时，为日志级别选择信息。然后，选择记录完整的请求/响应数据。

要确定错误的原因，请查看 CloudWatch 中的 REST API 执行日志。

检查执行日志中的错误信息

Error: Execution failed due to configuration error: There was an internal error while executing your request

确认以下配置：

• 验证 VPC 链接负载均衡器是否存在且未被删除。
• 验证 VPC 链接是否处于可用状态。如果 VPC 链接处于失败状态，则必须创建一个新的 VPC 链接并将其与您的 API 关联。
  **注意：**修改集成请求后部署 API。
• 验证 VPC 链接端点连接是否处于可用状态。
• 如果使用阶段变量引用 VPC ID，请验证 VPC 链接 ID 是否正确。
• 验证 VPC 链接负载均衡器是否监听请求配置的 HTTP/HTTPS 端口。检查侦听器是否配置了正确的端口。确保网络 ACL 不会阻止请求。
• 验证目标组是否接受请求。网络 ACL 必须允许入站和出站流量，安全组必须允许已配置端口的入站流量。
• 如果请求返回 500 错误，则连接可能收到了 TCP RST 数据包。验证后端服务器是否正在运行。验证目标端口的后端目标上是否有服务在运行。验证后端目标是否监听目标端口。
• 确认对 AWS PrivateLink 流量强制执行入站规则选项已关闭。对 PrivateLink 流量强制执行入站规则将所有入站和出站安全组规则应用于来自 VPC 链接的流量。如果您未将安全组配置为允许来自 VPC 链接的流量，则该安全组可以阻止 API Gateway 流量。要将安全组规则应用于不是来自 VPC 链接的流量，请关闭对 PrivateLink 流量强制执行入站规则。

Error: Execution failed due to configuration error: Host name 'domain.com.com' does not match the certificate subject provided by the peer (CN=myinstance.com)

确保端点域名与已启用 TLS 的负载均衡器目标返回的证书相匹配。

Error: Execution failed due to configuration error: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

当 API Gateway 找不到根证书颁发机构时，就会发生此错误。即使在集成 TlsConfig 属性上将 insecureSkipVerification 设置为 true，API Gateway 也会执行基本的证书验证。验证将审查以下信息：

• 证书到期日期
• 主机名
• 根证书颁发机构是否存在

您在目标实例上配置的证书必须是受支持的证书颁发机构提供商清单中的可信证书。

Error: Execution failed due to configuration error: Cannot verify ECDH ServerKeyExchange signature

当密钥和相应的证书不匹配时，就会发生此错误，此时 TLS 握手失败。要解决此问题，请检查您用于配置证书颁发机构、证书和密钥的文件内容。

Error: Execution failed due to an internal error

由于目标在负载均衡器上重置，Amazon API Gateway 未能通过 VPC 链接连接到负载均衡器，此时就会发生此错误。要解决此问题，在目标上设置的超时要比负载均衡器上的默认超时（350 秒）长。

Error: Execution failed due to configuration error: Not a valid protocol version: {Text of string}

当集成响应的 HTTP 响应无效且不符合 HTTP 规范时，就会发生此错误。这可能意味着集成后端向 Amazon API Gateway 发送了无效数据。

要排查此错误，请采取以下措施：

• 重现您从 Amazon API Gateway 发出的请求。要测试 Amazon API Gateway 使用的服务端点，请创建一个与服务端点 ID 关联的 VPC 端点。您还可以捕获运行数据包来查看从集成后端返回的响应。
• 为避免重复加密，请根据目标响应将负载均衡器协议更改为 TLS 或 TCP。
• 确保在集成 TlsConfig 属性上将 insecureSkipVerification 设置为 true。

相关信息

Understanding VPC Links in Amazon API Gateway private Integrations

使用 Amazon CloudWatch 指标监控 REST API 执行

为 API Gateway 私有集成设置网络负载均衡器