如何解决在使用 VPC 链接与 API Gateway REST API 集成时出现的 500 错误？

简短描述

具有 VPC 链接集成的 API Gateway 可能无法将流量转发到后端资源。

也可能出于以下原因之一返回 "HTTP 500" 状态代码：

• VPC 链接处于故障状态。或者，端点服务不存在或处于已拒绝状态。
• 目标组显示已注册目标运行状况不正常或未在使用中。
• 安全组禁止特定端口上的流量。
• 网络访问控制列表（网络 ACL）会屏蔽流量。
• 目标未监听目标端口。
• 域名证书与已启用 TLS 的网络负载均衡器或应用程序负载均衡器不匹配。

如果您的 API 已启用 Amazon CloudWatch Logs，则执行日志中会显示一条错误消息，其中包含出现错误的原因。

解决方法

验证后端连接

在对 API Gateway 进行故障排除之前，请执行以下操作之一：

• 使用 curl 或 Postman 等工具从 VPC 内部向网络负载均衡器 DNS 名称发送请求。如果请求失败，则表明网络负载均衡器配置、后端目标运行状况或网络存在问题。
• 使用 VPC Reachability Analyzer 以验证从 API Gateway VPC 链接子网到后端资源的流量。

确认出现错误的原因

激活 CloudWatch API 日志记录。此外，配置执行日志记录。

**注意：**在配置日志记录设置时，请将日志记录级别设置为 Error and info logs（错误和信息日志），然后选择 Data tracing（数据跟踪）。这些设置可为您提供完整的请求和响应日志。

要确定出现错误的原因，请在 CloudWatch 中查看 REST API 的执行日志。然后，根据您收到的错误消息对问题进行故障排除。

针对 "There was an internal error while executing your request" 进行故障排除

您会收到以下错误消息：

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

要解决此问题，请检查以下配置：

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

针对 "Host name 'domain.com.com' does not match the certificate subject provided by the peer" 进行故障排除

您会收到以下错误消息：

"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 的负载均衡器目标返回的证书相匹配。受支持的证书颁发机构提供商列表必须信任您在目标实例上配置的证书。

对 "PKIX path building failed:...unable to find valid certification path to requested target" 进行故障排除

您会收到以下错误消息：

"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"

当集成返回的证书被 REST API 服务标记为无效时，就会出现此错误。即使您在集成的 TlsConfig 属性上将 insecureSkipVerification 设置为 true，API Gateway 也会执行基本的证书验证。

API Gateway 会审查以下信息：

• 证书到期日期
• 主机名
• 根证书颁发机构 (CA) 是否存在
  **注意：**集成必须包含并返回完整的证书链，以供 API Gateway 验证信任链并建立安全连接。完整证书链涵盖从服务器证书到根 CA 证书的所有中间证书。此外，根 CA 必须包含带有 keyCertSign 的 keyUsage 以及带有 CA:TRUE 的 basicConstraints。有关更多信息，请参阅 x-amazon-apigateway-integration.tlsConfig 对象。

对 "Cannot verify ECDH ServerKeyExchange signature" 进行故障排除

您会收到以下错误消息：

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

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

对 "Execution failed due to an internal error" 进行故障排除

您会收到以下错误消息：

"Error: Execution failed due to an internal error"

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

对 "Execution failed due to a VPC link error" 进行故障排除

您会收到以下错误消息：

"Error: Execution failed due to a VPC link error"

API Gateway 存在多个依赖项。当其中某个依赖项出现暂时性连接故障时，就可能会出现错误。对于低频错误，最佳做法是实施带指数回退的重试机制。如果错误频率很高，请联系 AWS Support。务必要提供显示错误的 API Gateway 执行日志。

对 "Execution failed due to configuration error: Not a valid protocol version" 进行故障排除

您会收到以下错误消息：

"Error: Execution failed due to configuration error: Not a valid protocol version"

当集成响应的 HTTP 响应无效且不符合 HTTP 规范时，就会出现此错误。集成后端可能会向 API Gateway 回传无效数据。

要对此问题进行故障排除，请执行以下操作：

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

监控并检测错误和问题

使用以下工具来确定是暂时性故障还是持续存在的配置问题：

• 在 CloudWatch 中监控 5XXError 和 IntegrationLatency API Gateway 指标以检测模式。
• 启用 AWS X-Ray 跟踪以监控从 API Gateway 到 VPC 链接、VPC 链接到网络负载均衡器以及网络负载均衡器到后端的请求路径。

相关信息

了解 Amazon API Gateway 私有集成中的 VPC 链接

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

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