RDS 代理故障排除 - Amazon Relational Database Service
验证代理的连接常见问题和解决方案

RDS 代理故障排除

下面，您可以找到一些常见 RDS 代理问题的故障排除思路，以及有关 RDS Proxy 的 CloudWatch Logs 的信息。

在 RDS Proxy 日志中，每个条目都以关联的代理终端节点的名称作为前缀。此名称可以是您为用户定义的端点指定的名称。或者，对于执行读/写请求的代理的默认端点，它可以是特殊名称 default。有关代理终端节点的更多信息，请参阅 使用 Amazon RDS Proxy 终端节点。

验证代理的连接

您可以使用以下命令验证连接中的所有组件（例如代理、数据库和计算实例）是否均可相互进行通信。

使用 describe-db-proxies 命令检查代理本身。此外，使用 describe-db-proxy-target-groups 命令检查关联的目标组。检查目标的详细信息是否与您打算与代理关联的 RDS 数据库实例匹配。使用如下命令。

aws rds describe-db-proxies --db-proxy-name $DB_PROXY_NAME
aws rds describe-db-proxy-target-groups --db-proxy-name $DB_PROXY_NAME

要确认代理可以连接到底层数据库，请使用 describe-db-proxy-targets 命令检查目标组中指定的目标。使用如下命令。

aws rds describe-db-proxy-targets --db-proxy-name $DB_PROXY_NAME

describe-db-proxy-targets 命令的输出包括一个 TargetHealth 字段。您可以检查 State 内部的字段 Reason、Description 和 TargetHealth，以检查代理是否可以与底层数据库实例进行通信。

  • State 值 AVAILABLE 表示代理可以连接到数据库实例。

  • State 值 UNAVAILABLE 表示存在临时或永久的连接问题。在这种情况下，请检查 Reason 和 Description 字段。例如，如果 Reason 的值为 PENDING_PROXY_CAPACITY，请在代理完成其扩展操作后，重试连接。如果 Reason 的值为 UNREACHABLE、CONNECTION_FAILED 或 AUTH_FAILURE，请使用 Description 字段中的说明来帮助您诊断问题。

  • 在更改为 State 或 REGISTERING 之前，AVAILABLE 字段的值可能在短时间内为 UNAVAILABLE。

如果以下 Netcat 命令 (nc) 成功，您可以从登录的 EC2 实例或其他系统访问代理终端节点。如果您与代理和关联数据库不在同一 VPC 中，则该命令将报告失败。您可能未在同一 VPC 中就可以直接登录到数据库。但是，除非在同一 VPC 中，否则无法登录到代理。

nc -zx MySQL_proxy_endpoint 3306

nc -zx PostgreSQL_proxy_endpoint 5432

您可以使用以下命令来确保 EC2 实例具有所需属性。特别是，EC2 实例的 VPC 必须与代理连接到的 的 VPC 相同。

aws ec2 describe-instances --instance-ids your_ec2_instance_id

检查用于代理的 Secrets Manager 密钥。

aws secretsmanager list-secrets
aws secretsmanager get-secret-value --secret-id your_secret_id

确保 get-secret-value 显示的 SecretString 字段被编码为包含 username 和 password 字段的 JSON 字符串。以下示例显示了 SecretString 字段的格式。

{
  "ARN": "some_arn",
  "Name": "some_name",
  "VersionId": "some_version_id",
  "SecretString": '{"username":"some_username","password":"some_password"}',
  "VersionStages": [ "some_stage" ],
  "CreatedDate": some_timestamp
}

常见问题和解决方案

本节介绍使用 RDS 代理时的一些常见问题和潜在的解决方案。

运行 aws rds describe-db-proxy-targets CLI 命令后，如果 TargetHealth 描述显示 Proxy does not have any registered credentials，请验证以下内容：

  • 已经为用户注册了访问代理的凭证。

  • 用于访问代理使用的 Secrets Manager 密钥的 IAM 角色是有效的。

创建或连接数据库代理时，您可能会遇到以下 RDS 事件。

类别 RDS 事件 ID 描述

失败

 RDS-EVENT-0243 RDS 无法为代理预调配容量，因为您的子网中没有足够的 IP 地址可用。要解决此问题，请确保您的子网具有最少的未使用 IP 地址数。要确定您的实例类的建议数量，请参阅计划 IP 地址容量。

失败

 RDS-EVENT-0275

RDS 限制了一些与数据库代理名称的连接。从客户端到代理的并发连接请求数已超出了限制。

创建新代理或连接到代理时，您可能会遇到以下问题。

错误 原因或解决方法

403: The security token included in the request is invalid

选择现有 IAM 角色，而不是选择创建新角色。

连接到 MySQL 代理时，您可能会遇到以下问题。

错误 原因或解决方法
ERROR 1040 (HY000): Connections rate limit exceeded (limit_value) 从客户端到代理的连接请求速率超过了限制。
ERROR 1040 (HY000): IAM authentication rate limit exceeded 从客户端到代理的具有 IAM 身份验证的并发请求数超过了限制。
ERROR 1040 (HY000): Number simultaneous connections exceeded (limit_value) 从客户端到代理的并发连接请求数超出了限制。

ERROR 1045 (28000): Access denied for user 'DB_USER'@'%' (using password: YES)

代理使用的 Secrets Manager 密钥与现有数据库用户的用户名和密码不匹配。更新 Secrets Manager 密钥中的凭证，或者确保数据库用户存在并且具有与密钥中的密码相同的密码。
ERROR 1105 (HY000): Unknown error 出现未知错误。
ERROR 1231 (42000): Variable ''character_set_client'' can't be set to the value of value

为 character_set_client 参数设置的值无效。例如，值 ucs2 无效，因为它会导致 MySQL 服务器崩溃。
ERROR 3159 (HY000): This RDS Proxy requires TLS connections.

您在代理中启用了需要传输层安全性设置，但您的连接将参数 ssl-mode=DISABLED 包含在 MySQL 客户端中。请执行以下任一操作：

  • 禁用代理的需要传输层安全性设置。

  • 在 MySQL 客户端中，使用最小设置 ssl-mode=REQUIRED 连接到数据库。
ERROR 2026 (HY000): SSL connection error: Internal Server Error

与代理的 TLS 握手失败。一些可能的原因包括：

  • SSL 是必需的，但服务器不支持它。

  • 发生内部服务器错误。

  • 发生握手错误。
ERROR 9501 (HY000): Timed-out waiting to acquire database connection

等待获取数据库连接时代理超时。一些可能的原因包括：

  • 代理无法建立数据库连接，因为已达到最大连接数

  • 代理无法建立数据库连接，因为数据库不可用。

连接到 PostgreSQL 代理时，您可能会遇到以下问题。

错误 原因 解决方案

IAM authentication is allowed only with SSL connections.

用户在 PostgreSQL 客户端中，尝试使用具有设置 sslmode=disable 的 IAM 身份验证连接到数据库。

用户需要在 PostgreSQL 客户端中使用最小设置 sslmode=require 连接到数据库。有关更多信息，请参阅 PostgreSQL SSL 支持文档。

This RDS Proxy requires TLS connections.

用户启用了需要传输层安全性选项，但尝试在 PostgreSQL 客户端中使用 sslmode=disable 进行连接。

要修复此错误，请执行以下操作之一：

  • 禁用代理的需要传输层安全性选项。

  • 在 PostgreSQL 客户端中，使用最小设置 sslmode=allow 连接到数据库。

IAM authentication failed for user user_name. Check the IAM token for this user and try again.

该错误可能是由于以下原因引起的：

  • 客户端提供了错误的 IAM 用户名。

  • 客户端向用户提供了错误的 IAM 授权令牌。

  • 客户端在使用没有所需权限的 IAM 策略。

  • 客户端向用户提供了过期的 IAM 授权令牌。

要修复此错误，请执行以下操作：

  1. 确认提供的 IAM 用户存在。

  2. 确认 IAM 授权令牌属于提供的 IAM 用户。

  3. 确认 IAM 策略具有足够的 RDS 权限。

  4. 检查所用 IAM 授权令牌的有效性。

This RDS proxy has no credentials for the role role_name. Check the credentials for this role and try again.

这个角色没有 Secrets Manager 密钥。

为此角色添加 Secrets Manager 密钥。有关更多信息，请参阅设置 RDS 代理的 AWS Identity and Access Management（IAM）策略。

RDS supports only IAM, MD5, or SCRAM authentication.

用于连接到代理的数据库客户端正在使用代理当前不支持的身份验证机制。

如果您不使用 IAM 身份验证，请使用 MD5 或 SCRAM 密码身份验证。

A user name is missing from the connection startup packet. Provide a user name for this connection.

用于连接到代理的数据库客户端在尝试建立连接时未发送用户名。

请确保在使用您选择的 PostgreSQL 客户端设置与代理的连接时定义用户名。

Feature not supported: RDS Proxy supports only version 3.0 of the PostgreSQL messaging protocol.

用于连接到代理的 PostgreSQL 客户端使用早于 3.0 的协议。

使用支持 3.0 消息传递协议的较新 PostgreSQL 客户端。如果您使用的是 PostgreSQL psql CLI，请使用大于或等于 7.4 的版本。

Feature not supported: RDS Proxy currently doesn't support streaming replication mode.

用于连接到代理的 PostgreSQL 客户端正在尝试使用流复制模式，该模式目前不受 RDS 代理支持。

在用于连接的 PostgreSQL 客户端中关闭流复制模式。

Feature not supported: RDS Proxy currently doesn't support the option option_name.

通过启动消息，用于连接到代理的 PostgreSQL 客户端正在请求 RDS 代理当前不支持的选项。

在用于连接的 PostgreSQL 客户端中，关闭上述消息中显示为不支持的选项。

The IAM authentication failed because of too many competing requests.

从客户端到代理的具有 IAM 身份验证的并发请求数超过了限制。

降低使用 PostgreSQL 客户端中的 IAM 身份验证建立连接的速率。

The maximum number of client connections to the proxy exceeded number_value.

从客户端到代理的并发连接请求数超出了限制。

减少从 PostgreSQL 客户端到此 RDS 代理的活动连接数。

Rate of connection to proxy exceeded number_value.

从客户端到代理的连接请求速率超过了限制。

降低从 PostgreSQL 客户端建立连接的速率。

The password that was provided for the role role_name is wrong.

此角色的密码与 Secrets Manager 密钥不匹配。

检查 Secrets Manager 中此角色的密钥，以查看密码是否与 PostgreSQL 客户端中使用的密码相同。

The IAM authentication failed for the role role_name. Check the IAM token for this role and try again.

用于 IAM 身份验证的 IAM 令牌存在问题。

生成新的身份验证令牌并在新连接中使用它。

IAM is allowed only with SSL connections.

客户端尝试使用 IAM 身份验证进行连接，但未启用 SSL。

在 PostgreSQL 客户端中启用 SSL。

Unknown error.

出现未知错误。

请联系 AWS Support，以便我们调查此问题。

Timed-out waiting to acquire database connection.

等待获取数据库连接时代理超时。一些可能的原因包括：

  • 代理无法建立数据库连接，因为已达到最大连接数。

  • 代理无法建立数据库连接，因为数据库不可用。

可能的解决方案包括以下各项：

  • 检查 状态的目标，以查看它是否不可用。

  • 检查是否有长时间运行的事务和/或查询正在执行。它们可以长时间使用连接池中的数据库连接。

Request returned an error: database_error.

从代理建立的数据库连接返回错误。

解决方案取决于特定的数据库错误。示例为：Request returned an error: database "your-database-name" does not exist。这意味着数据库服务器上不存在指定的数据库名称。或者，这意味着服务器上不存在用作数据库名称（如果未指定数据库名称）的用户名。