# RDS 代理故障排除
<a name="rds-proxy.troubleshooting"></a>

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

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

**Topics**
+ [验证代理的连接](#rds-proxy-verifying)
+ [常见问题和解决方案](#rds-proxy-diagnosis)
+ [排查 RDS for MySQL 的 RDS 代理问题](#rds-proxy-MySQL-troubleshooting)
+ [排查 RDS for PostgreSQL 的 RDS 代理问题](#rds-proxy-PostgreSQL-troubleshooting)

## 验证代理的连接
<a name="rds-proxy-verifying"></a>

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

 使用 [describe-db-proxies](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxies.html) 命令检查代理本身。此外，使用 [describe-db-proxy-target-groups](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-target-groups.html) 命令检查关联的目标组。检查目标的详细信息是否与您打算与代理关联的 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](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-targets.html) 命令检查目标组中指定的目标。使用如下命令。

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

 [describe-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-targets.html) 命令的输出包括一个 `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
}
```

排查 IAM 身份验证问题时，请验证以下内容：
+ 数据库已启用 IAM 身份验证。
+ 代理配置了正确的身份验证方案。
+ 提供给代理的 IAM 角色中的 IAM 策略授予对相应数据库及其用户名的必要 `rds-db:connect` 权限。
+ 对于端到端 IAM 身份验证，存在与 IAM 用户或角色名称匹配的数据库用户。
+ 为连接启用了 SSL/TLS。

## 常见问题和解决方案
<a name="rds-proxy-diagnosis"></a>

本节介绍使用 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-proxy-network-prereqs.md#rds-proxy-network-prereqs.plan-ip-address)。 | 
|  失败  | RDS-EVENT-0275 |  RDS 限制了一些与数据库代理*名称*的连接。从客户端到代理的并发连接请求数已超出了限制。  | 

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


|  错误  |  原因或解决方法  | 
| --- | --- | 
|   `403: The security token included in the request is invalid`   |  选择现有 IAM 角色，而不是选择创建新角色。 | 

## 排查 RDS for MySQL 的 RDS 代理问题
<a name="rds-proxy-MySQL-troubleshooting"></a>

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


|  错误  |  原因或解决方法  | 
| --- | --- | 
|  ERROR 1040 (HY000): Connections rate limit exceeded (limit\$1value)  |  从客户端到代理的连接请求速率超过了限制。 | 
|  ERROR 1040 (HY000): IAM authentication rate limit exceeded  |  从客户端到代理的具有 IAM 身份验证的并发请求数超过了限制。 | 
|  ERROR 1040 (HY000): Number simultaneous connections exceeded (limit\$1value)  |  从客户端到代理的并发连接请求数超出了限制。 | 
|   `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\$1set\$1client'' 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 客户端中。请执行以下任一操作： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html)  | 
|  ERROR 2026 (HY000): SSL connection error: Internal Server Error  |   与代理的 TLS 握手失败。一些可能的原因包括： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html)  | 
|  ERROR 9501 (HY000): Timed-out waiting to acquire database connection  |   等待获取数据库连接时代理超时。一些可能的原因包括： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html)  | 

## 排查 RDS for PostgreSQL 的 RDS 代理问题
<a name="rds-proxy-PostgreSQL-troubleshooting"></a>

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


|  错误  |  原因  |  解决方案  | 
| --- | --- | --- | 
|   `ERROR 28000: IAM authentication is allowed only with SSL connections.`   |   用户在 PostgreSQL 客户端中，尝试使用具有设置 `sslmode=disable` 的 IAM 身份验证连接到数据库。  |   用户需要在 PostgreSQL 客户端中使用最小设置 `sslmode=require` 连接到数据库。有关更多信息，请参阅 [PostgreSQL SSL 支持](https://www.postgresql.org/docs/current/libpq-ssl.html)文档。  | 
|  `ERROR 28000: 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 代理配置 IAM 身份验证](rds-proxy-iam-setup.md)。  | 
|  `ERROR 28000: RDS supports only IAM, MD5, or SCRAM authentication.`   |   用于连接到代理的数据库客户端正在使用代理当前不支持的身份验证机制。  |   如果您不使用 IAM 身份验证，请使用 MD5 或 SCRAM 密码身份验证。  | 
|  `ERROR 28000: A user name is missing from the connection startup packet. Provide a user name for this connection.`   |   用于连接到代理的数据库客户端在尝试建立连接时未发送用户名。  |   请确保在使用您选择的 PostgreSQL 客户端设置与代理的连接时定义用户名。  | 
|  `ERROR 28000: IAM is allowed only with SSL connections.`   |   客户端尝试使用 IAM 身份验证进行连接，但未启用 SSL。  |   在 PostgreSQL 客户端中启用 SSL。  | 
|  `ERROR 28000: This RDS Proxy requires TLS connections.`   |   用户启用了**需要传输层安全性**选项，但尝试在 PostgreSQL 客户端中使用 `sslmode=disable` 进行连接。  |   要修复此错误，请执行以下操作之一： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html)  | 
|  `ERROR 28P01: IAM authentication failed for user user_name. Check the IAM token for this user and try again.`   |   该错误可能是由于以下原因引起的： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html)  |   要修复此错误，请执行以下操作： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html)  | 
|  `ERROR 28P01: The password that was provided for the role role_name is wrong.`   |   此角色的密码与 Secrets Manager 密钥不匹配。  |   检查 Secrets Manager 中此角色的密钥，以查看密码是否与 PostgreSQL 客户端中使用的密码相同。  | 
|  `ERROR 28P01: The IAM authentication failed for the role role_name. Check the IAM token for this role and try again.`   |   用于 IAM 身份验证的 IAM 令牌存在问题。  |   生成新的身份验证令牌并在新连接中使用它。  | 
|  `ERROR 0A000: 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 的版本。  | 
|  `ERROR 0A000: Feature not supported: RDS Proxy currently doesn't support streaming replication mode.`   |   用于连接到代理的 PostgreSQL 客户端正在尝试使用流复制模式，该模式目前不受 RDS 代理支持。  |   在用于连接的 PostgreSQL 客户端中关闭流复制模式。  | 
|  `ERROR 0A000: Feature not supported: RDS Proxy currently doesn't support the option option_name.`   |   通过启动消息，用于连接到代理的 PostgreSQL 客户端正在请求 RDS 代理当前不支持的选项。  |   在用于连接的 PostgreSQL 客户端中，关闭上述消息中显示为不支持的选项。  | 
|  `ERROR 53300: The IAM authentication failed because of too many competing requests.`   |   从客户端到代理的具有 IAM 身份验证的并发请求数超过了限制。  |   降低使用 PostgreSQL 客户端中的 IAM 身份验证建立连接的速率。  | 
|  `ERROR 53300: The maximum number of client connections to the proxy exceeded number_value.`   |   从客户端到代理的并发连接请求数超出了限制。  |   减少从 PostgreSQL 客户端到此 RDS 代理的活动连接数。  | 
|  `ERROR 53300: Rate of connection to proxy exceeded number_value.`   |   从客户端到代理的连接请求速率超过了限制。  |   降低从 PostgreSQL 客户端建立连接的速率。  | 
|  `ERROR XX000: Unknown error.`   |   出现未知错误。  |   请联系 AWS Support，以便我们调查此问题。  | 
|  `ERROR 08000: Timed-out waiting to acquire database connection.`   |   代理在 `ConnectionBorrowTimeout` 设置指定的持续时间内等待获取数据库连接时超时。一些可能的原因包括： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html)  |   可能的解决方案包括以下各项： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy.troubleshooting.html)  | 
|  `ERROR XX000: Request returned an error: database_error.`   |   从代理建立的数据库连接返回错误。  |   解决方案取决于特定的数据库错误。示例为：`Request returned an error: database "your-database-name" does not exist`。这意味着数据库服务器上不存在指定的数据库名称。或者，这意味着服务器上不存在用作数据库名称（如果未指定数据库名称）的用户名。  | 
|  `ERROR 53300: The IAM authentication failed because of too many competing requests.`  |  从客户端到代理的具有 IAM 身份验证的并发请求数超过了限制。  |  降低使用 PostgreSQL 客户端中的 IAM 身份验证建立连接的速率。  | 
|  `ERROR 28000: Enable IAM authentication for the client connection to the proxy and try again.`  |  RDS 代理无法连接到数据库，因为客户端与代理的连接未启用 IAM 身份验证。当注册用户将代理的 `DefaultAuthScheme` 参数设置为 `IAM_AUTH`，但客户端使用密码身份验证而非 IAM 身份验证时，就会发生这种情况。  |  为客户端与代理的连接启用 IAM 身份验证，然后重试。  | 
|  `ERROR 28000: Configure IAM authentication as the DefaultAuthScheme in your proxy and try again.`  |  RDS 代理无法连接到数据库，因为 `DefaultAuthScheme` 未设置为 `IAM_AUTH`。代理的 `DefaultAuthScheme` 参数设置为 `NONE`，但客户端正在尝试使用 IAM 身份验证。  |  将代理的 `DefaultAuthScheme` 设置为 `IAM_AUTH`，然后重试。  | 

### 对已删除的 `postgres` 数据库进行故障排除
<a name="rds-proxy-PostgreSQL-troubleshooting.postgresDBDelete"></a>

如果您错误地从实例中删除了 `postgres` 数据库，则需要还原数据库以还原与实例的连接。在数据库实例中运行以下命令：

```
CREATE DATABASE postgres;
GRANT CONNECT ON DATABASE postgres TO rdsproxyadmin;
```