Frappe Docker 项目中的 MariaDB 连接问题分析与解决方案

问题现象描述

在 Frappe Docker 环境中，当后端服务尝试连接 MariaDB 数据库时，出现了访问被拒绝的错误。具体表现为后端服务容器（backend-1）在建立数据库连接时，收到了来自 MariaDB 的 1045 错误代码，提示用户认证失败。

错误详情分析

错误日志显示，连接尝试使用的是用户 _5e5899d8398b5f7b，从 IP 地址 172.18.0.7（这是 Docker 内部网络中的一个容器）发起连接，虽然提供了密码，但仍然被拒绝访问。

根本原因

这种问题通常发生在以下情况：

1. Docker 容器重建后：当 MariaDB 容器被重新创建时，数据库中的用户权限信息可能丢失或重置
2. 环境变量不一致：数据库连接配置与实际的数据库用户信息不匹配
3. 密码变更：数据库用户的密码在容器重建后被重置，但应用配置未相应更新
4. 权限未正确初始化：在容器启动过程中，初始化脚本未能正确设置用户权限

解决方案

方法一：重建数据库用户

1. 进入 MariaDB 容器：

   docker exec -it mariadb bash
   

2. 登录到 MySQL 控制台：

   mysql -u root -p
   

3. 重新创建用户并授权：

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

方法二：重置环境配置

1. 检查 docker-compose.yml 文件中的环境变量配置，确保数据库连接参数正确
2. 确认 MYSQL_ROOT_PASSWORD 和 DB_PASSWORD 等关键环境变量设置一致
3. 重启相关服务容器使配置生效

方法三：持久化数据库数据

1. 确保为 MariaDB 配置了持久化存储卷
2. 在 docker-compose.yml 中配置类似如下的数据卷：

   volumes:
     - mariadb-data:/var/lib/mysql
   

预防措施

1. 使用数据卷：始终为数据库容器配置持久化存储，防止容器重建时数据丢失
2. 备份用户权限：定期备份 MySQL 的用户权限表（mysql.user）
3. 环境变量管理：使用统一的环境变量管理工具，确保配置一致性
4. 监控连接：设置监控告警，及时发现数据库连接问题

技术原理深入

在 Docker 环境中，数据库连接问题通常涉及以下几个方面：

1. 网络隔离：Docker 容器间的网络通信需要通过正确的网络配置
2. 用户主机限制：MySQL/MariaDB 的用户权限通常绑定到特定主机
3. 密码加密：MySQL 8.0+ 使用 caching_sha2_password 认证插件，可能与旧客户端不兼容
4. 初始化顺序：容器启动时，数据库初始化与应用启动的时间顺序可能导致连接问题

理解这些底层原理有助于更全面地排查和预防类似问题。