> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Cloud 数据库连接错误：MySQL Host Not Allowed、MongoNetworkError、SSL

> 修复 Host is not allowed to connect to this MySQL server、MongoNetworkError、MongoDB Atlas IP 白名单失败、连接超时、ECONNREFUSED，以及 Square Cloud 上的 SSL/TLS 连接错误。

Square Cloud 上大多数数据库连接失败都可以归结为以下三个原因之一：缺少 SSL 证书、IP 白名单没有考虑到动态 IP，或凭据错误。请对照下方确切的错误信息。

## "Host 'X' is not allowed to connect to this MySQL server"

**含义：** MySQL 客户端以这条确切的信息拒绝了连接。

**发生原因：** Square Cloud 的托管数据库**每次连接都要求 SSL**。当连接尝试在未加载证书的情况下发起时会出现此错误，而不是像信息所暗示的那样是由于防火墙/主机白名单。

**如何修复：**

1. 在 Square Cloud 控制面板中打开数据库并下载证书文件（CA、cert、key，通常有 2-3 个字段）。
2. 在你客户端的 SSL/TLS 配置中加载这些文件：
   * **图形界面客户端**（MySQL Workbench、DBeaver、HeidiSQL）：在客户端的 SSL 选项卡中配置下载的证书文件，然后使用控制面板中显示的 host/port/user/password 进行连接。
   * **代码（Prisma ORM）：** 将客户端证书+密钥转换为 `.p12`：
     ```bash theme={null}
     openssl pkcs12 -export -out client.p12 -inkey client.key -in client.crt
     ```
     然后设置：
     ```
     DATABASE_URL=mysql://USER:PASSWORD@HOST:PORT/DB?sslidentity=./client.p12&sslpassword=PASSWORD
     ```
     将 `client.p12` 一并放入应用的 `.zip` 中，并在控制面板的环境变量里设置 `DATABASE_URL`。
3. 确认用户名和密码与控制面板中显示的一致，如果证书是刚刚生成的，请重启数据库。

<Warning>切勿将 `certificate.pem` 或 `client.p12` 提交到公开仓库中，使其保持在版本控制之外，但当你的应用需要从磁盘读取它时，请将其包含在部署用的 `.zip` 中。</Warning>

## MongoNetworkError 与 MongoDB Atlas IP 白名单失败

**含义：** 一个外部托管的 MongoDB Atlas 集群（而非 Square Cloud 托管数据库）以 `MongoNetworkError: connection ... closed` 拒绝连接，即便凭据是正确的。

**发生原因：** Square Cloud 的应用容器使用**每次重启都会变化的动态 IPv4 地址**。为单个静态 IP 配置的 MongoDB Atlas IP 白名单在下一次重启前可以正常工作，之后就会悄悄失效。

**如何修复，二选一：**

1. **如果需要外部 Atlas，推荐做法：** 在 Atlas 的 Network Access 中添加 `0.0.0.0/0` 以允许来自任意 IP 的连接，并通过更强的凭据（长且随机的密码、专用的数据库用户、仅保存在环境变量中的连接字符串）来弥补更宽松的白名单带来的风险。
2. **总体推荐做法：** 将数据库迁移到 [Square Cloud 托管数据库](/zh/services/databases)，而不是使用外部 Atlas 集群。将数据库托管在应用旁边可以彻底消除 IP 白名单问题，并带来近乎零的延迟。

## 连接超时与 ECONNREFUSED

**含义：** 应用在尝试连接数据库时挂起直到超时，或立即以 `ECONNREFUSED` 失败。

**通常可以这样判断原因：**

* **超时**（连接挂起，没有立即被拒绝）通常意味着目标数据库上的防火墙或 IP 白名单正在阻止连接。许多外部服务商默认会屏蔽数据中心/境外 IP。
* 立即出现的 **ECONNREFUSED** 或 "authentication failed" 通常意味着 host/port 是可达的，但凭据、数据库名或端口号有误。

**如何修复：**

1. 如果连接的是外部服务商（而非 Square Cloud 托管数据库），请在目标防火墙上放行 Square Cloud 的 ASN：`398395` 和 `26548`。对于只支持基于 IP 白名单的服务商（如 MongoDB Atlas），请改用 `0.0.0.0/0` 配合强凭据，因为源 IP 是动态的。
2. 仔细核对 host、port、用户名和密码，与服务商或 Square Cloud 控制面板显示的是否一致。
3. 对连接字符串中的特殊字符进行 URL 编码（密码中原样保留的 `@`、`:`、`/` 等字符会破坏解析）。
4. 检查服务商的驱动是否要求在连接字符串中显式添加 `ssl=true`（或类似）参数。

## SSL/TLS 连接错误

**含义：** 客户端无法与数据库建立 TLS 握手，或紧随其后出现一个看似是身份验证问题、实际上是证书问题的错误。

**发生原因：** Square Cloud 托管数据库要求每次连接都使用 SSL。每种数据库引擎对证书的形式要求略有不同：

* **Redis：** 协议必须是 `rediss://`（两个 s），而不是 `redis://`。形式：`rediss://default:PASSWORD@HOST:PORT`。`node-redis` 也接受 `socket: { tls: true, ca: fs.readFileSync("certificate.pem") }`；Python 的 `redis` 库使用 `ssl_ca_certs`/`ssl_certfile`/`ssl_keyfile`（从控制面板下载的合并版 `certificate.pem` 对它们都适用）。
* **Drizzle ORM（Postgres）：** 一个标准的 `pg` `Pool`，配置 `ssl: { ca, cert, key }`，均通过 `fs.readFileSync` 从合并版 `certificate.pem` 加载，并在 `drizzle.config.ts` 中使用相同的 `ssl` 对象。
* **JDBC（Java）：** 客户端密钥必须转换为 PK8/DER 格式，并在 JDBC URL 的 SSL 属性中引用。

**如何修复：** 从控制面板的数据库页面重新下载证书（旧的或不完整的证书文件是常见原因），确认连接字符串使用了对应引擎支持 TLS 的协议/方案，如果数据库是刚创建的，请重启它。

关于从零开始创建并连接一个托管数据库，请参见[数据库](/zh/services/databases)。

<Tip>如果错误信息与上述都不匹配，我们的支持团队可以帮你诊断具体的连接失败原因。</Tip>

## 联系我们

如果你仍然遇到**技术问题**，我们的**专业支持团队**可以为你提供帮助。[**联系我们**](https://squarecloud.app/zh/support)，我们很乐意协助你解决任何问题 —— 支持质量正是开发者给予 Square Cloud [**4.9/5 评分（共 402 条评价）**](https://www.trustpilot.com/review/squarecloud.app)（Google 与 Trustpilot）的重要原因之一。