故障排除：数据库

连接被拒绝

错误： ECONNREFUSED 127.0.0.1:5432 或 connect ECONNREFUSED 127.0.0.1:27017

此错误意味着 1DevTool 到达了连接字符串中的主机和端口，但那里没有任何监听。数据库服务器要么未运行，要么在监听不同的端口。

修复：

• 检查数据库是否在运行。 对于 PostgreSQL：在终端中运行 pg_ctl status。对于 MySQL：mysqladmin status。对于 Redis：redis-cli ping（你应该得到 PONG）。如果服务已停止则启动它。
• 检查端口。 默认端口是 5432（PostgreSQL）、3306（MySQL/MariaDB）、27017（MongoDB）和 6379（Redis）。将 DATABASE_URL 中的端口与数据库实际使用的端口进行比较。
• Docker 容器。 如果数据库在 Docker 内运行，使用 docker ps 检查容器是否运行。如果未列出，使用 docker start <container-name> 启动它。同时确认容器的端口已发布到你的主机（在 docker ps 输出中查找 0.0.0.0:5432->5432/tcp）。

---

认证失败

错误： password authentication failed for user "postgres" 或 Access denied for user 'root'@'localhost'

连接字符串中的用户名或密码与数据库服务器期望的不匹配。

修复：

• 仔细检查 DATABASE_URL 或连接设置中的用户名和密码。很容易将 Supabase 账户密码与数据库密码混淆 —— 它们是不同的。使用 Supabase 仪表板 Settings → Database 下显示的密码。
• 密码中的特殊字符。 如果你的密码包含 @、#、/ 或 :，这些字符必须在连接字符串中进行 URL 编码。例如，@ 变为 %40，# 变为 %23。像 p@ss#word 这样的密码在 URL 中应写为 p%40ss%23word。

---

需要 SSL/TLS

错误： SSL connection has been closed unexpectedly 或 server requires SSL but client does not support it

许多云数据库提供商（Supabase、Neon、Railway、Render）需要加密连接。

修复： 在 PostgreSQL 连接字符串末尾添加 ?sslmode=require：

postgresql://user:pass@host:5432/db?sslmode=require

对于 MongoDB Atlas，在连接字符串中使用 mongodb+srv:// 方案 —— 它会自动启用 TLS，不需要额外参数。

---

查询超时

原因： 查询扫描了太多数据，或 1DevTool 和数据库之间的网络连接在查询中途断开。

修复：

• 在探索数据时向查询添加 LIMIT 子句。例如：SELECT * FROM orders LIMIT 100。
• 如果特定查询始终很慢，检查 WHERE 子句中的列是否有索引。在 SQL 编辑器中运行 EXPLAIN ANALYZE <your query> 会显示查询计划。
• 如果超时偶尔发生，检查你的网络。VPN 连接尤其会导致数据库连接不稳定。

---

MongoDB：密码中的特殊字符

如果你的 MongoDB 密码包含 @、/、: 或 #，你必须在连接字符串中对这些字符进行 URL 编码。这些字符在 URL 中有特殊含义，如果按字面使用会破坏解析。

常见编码：@ → %40、# → %23、/ → %2F、: → %3A。

示例：密码 my@secret#pass 在连接字符串中变为 my%40secret%23pass。

---

无法连接到 Docker 容器

如果数据库在 Docker 容器内运行，而你尝试从 1DevTool（运行在主机上）连接，不要在连接字符串中使用 localhost。从主机，localhost 指的是主机本身 —— 而不是容器。

改用 host.docker.internal：

postgresql://user:[email protected]:5432/db

这个特殊的主机名总是从 Docker 内部解析到你的主机，并从主机侧解析到正确的回环接口。