Speedtest-Tracker数据库连接问题分析与解决方案

问题现象

在使用Docker部署的Speedtest-Tracker项目中，用户遇到了前端页面无法加载的问题，错误信息显示为"SQLSTATE[HY000] [2002] Connection refused"。这种数据库连接拒绝错误通常表现为HTTP 500内部服务器错误，用户无法访问登录页面或仪表板。

问题分析

数据库连接拒绝错误(SQLSTATE[HY000] [2002])通常表明应用程序无法与数据库服务器建立连接。在容器化环境中，这类问题可能由多种因素引起：

1. 数据库服务状态异常：MariaDB服务可能未正常运行或已崩溃
2. 网络配置问题：容器间的网络连接可能存在问题
3. 认证信息错误：数据库用户名或密码可能不正确
4. 网络隔离问题：容器被错误地加入了不适当的网络

排查过程

用户尝试了多种解决方案：

• 设置环境变量SETTINGS_CACHE_ENABLED=false和DB_SSLMODE=no-verify
• 重新部署Speedtest-Tracker和MariaDB容器（尝试了v10和latest版本）
• 切换使用SQLite数据库（成功运行但丢失历史数据）

根本原因

最终发现问题的根源在于网络配置错误。用户意外地将数据库容器加入了反向代理网络，导致网络连接混乱。这种配置会导致：

1. 容器间的通信路径被错误路由
2. 数据库连接请求被发送到错误的网络接口
3. 应用程序无法找到正确的数据库服务端点

解决方案

1. 检查容器网络配置：

   • 确认数据库容器只加入了必要的网络
   • 确保应用容器和数据库容器在同一网络中

2. 验证数据库连接信息：

   • 检查环境变量中的数据库主机名、端口、用户名和密码
   • 确保这些信息与数据库容器的实际配置匹配

3. 临时解决方案：

   • 使用SQLite数据库（适合不需要历史数据或小型部署）
   • 但会丢失之前的测试记录

4. 永久修复：

   • 从反向代理网络中移除数据库容器
   • 恢复原有的网络配置
   • 重新应用正确的环境变量

预防措施

为避免类似问题再次发生，建议：

1. 明确网络规划：在部署前规划好各容器的网络归属
2. 使用专用网络：为数据库通信创建专用网络
3. 配置检查清单：部署前核对所有网络和连接参数
4. 监控设置：实施数据库连接健康检查

总结

容器化环境中的数据库连接问题往往与网络配置密切相关。通过系统性地检查网络拓扑、验证连接参数，并理解容器间的通信机制，可以有效地解决这类"Connection refused"错误。Speedtest-Tracker作为依赖数据库的应用，确保数据库服务的可访问性是维持其正常运行的关键。