RomM项目数据库连接问题的分析与解决方案

问题背景

RomM是一款游戏库管理应用，用户报告在使用过程中遇到了数据库连接问题。主要表现为首次启动时能够创建账户并正常使用，但在容器重启后出现无法连接数据库的错误，导致无法登录系统。

问题现象

用户在使用Docker部署RomM时，主要遇到以下症状：

1. 首次启动时能够正常创建管理员账户
2. 容器重启后出现"Unable to login: Internal Server Error"错误
3. 日志中显示"Can't connect to server on 'romm-db'"和"403: User not found"错误
4. 数据库容器看似正常运行，但应用无法建立连接

技术分析

网络配置问题

从用户提供的Docker Compose配置来看，网络设置基本正确：

• 为RomM和数据库创建了专用网络(romm-db-net)
• 同时连接到默认网络(himitsu)用于外部访问
• 容器间能够互相ping通，证明基础网络连通性正常

数据库连接时序问题

更深入的分析表明，这很可能是一个启动顺序问题：

1. 数据库容器虽然启动完成，但MariaDB服务可能尚未完全初始化
2. RomM容器已经尝试连接数据库
3. 连接失败导致认证信息未被正确写入数据库
4. 后续重启时无法验证用户凭据

健康检查机制缺失

原始配置中缺少对数据库服务可用性的健康检查，导致应用容器无法正确判断数据库是否已准备好接收连接。

解决方案

方案一：添加健康检查机制

在Docker Compose中添加健康检查配置：

services:
  romm:
    depends_on:
      romm-db:
        condition: service_healthy
        restart: true

  romm-db:
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 30s
      interval: 10s
      timeout: 5s
      retries: 3

方案二：手动验证数据库

1. 进入数据库容器：

docker exec -it romm-db mysql -u root -p

2. 创建用户并授权：

CREATE USER 'romm-serv'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON romm.* TO 'romm-serv'@'%';
FLUSH PRIVILEGES;

方案三：环境变量验证

确保以下环境变量匹配：

• DB_PASSWD (RomM) 必须等于 MYSQL_PASSWORD (数据库)
• DB_USER (RomM) 必须等于 MYSQL_USER (数据库)
• DB_NAME (RomM) 必须等于 MYSQL_DATABASE (数据库)

最佳实践建议

1. 使用较新版本的Docker(25+)以获得完整的健康检查功能支持
2. 部署前清除浏览器缓存和Cookie
3. 监控容器日志以获取更详细的错误信息
4. 考虑使用数据库持久化卷确保数据安全
5. 对于生产环境，建议实施完整的备份策略

总结

RomM的数据库连接问题通常源于容器启动顺序和健康状态检测机制。通过实施适当的健康检查配置和确保正确的权限设置，可以有效地解决这类问题。对于持续出现问题的环境，手动验证数据库状态和用户权限是最直接的排查方法。