跳转到主要内容
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：
      然后设置：
      将 client.p12 一并放入应用的 .zip 中，并在控制面板的环境变量里设置 DATABASE_URL。
  3. 确认用户名和密码与控制面板中显示的一致，如果证书是刚刚生成的，请重启数据库。
切勿将 certificate.pem 或 client.p12 提交到公开仓库中，使其保持在版本控制之外，但当你的应用需要从磁盘读取它时，请将其包含在部署用的 .zip 中。

​
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 托管数据库，而不是使用外部 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 的协议/方案，如果数据库是刚创建的，请重启它。 关于从零开始创建并连接一个托管数据库，请参见数据库。
如果错误信息与上述都不匹配，我们的支持团队可以帮你诊断具体的连接失败原因。

​
联系我们

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