docker-compose部署Keycloak+MySQL 本地目录挂载时连接数据库失败

这个报错和账号密码配置本身无关，核心是绑定挂载宿主机目录时MySQL 5.7初始化流程异常，和Docker命名卷的场景差异如下：

• 用Docker管理的local命名卷时，Docker会自动适配卷的目录权限，匹配MySQL容器内运行用户（uid/gid=999）的读写要求，首次启动时如果卷为空，会完整执行初始化逻辑：创建你指定的keycloak库、keycloak用户、写入对应的访问授权，所有配置生效，所以服务正常运行。
• 用宿主机目录绑定挂载时，两个问题会直接导致初始化失败：
  1. 宿主机目录默认权限归属当前登录用户，MySQL容器内的999号用户没有目录读写权限，初始化脚本无法写入系统表、业务库和用户授权信息，权限表中根本不存在你配置的keycloak用户，收到Keycloak容器（网段IP为192.168.32.3）的连接请求时直接返回访问拒绝。
  2. 如果./.docker/dbdata目录非空（比如之前试错残留的不完整初始化文件、其他版本MySQL生成的数据文件），MySQL 5.7会跳过初始化流程直接读取旧数据，旧数据中没有匹配的用户授权规则，同样会报访问拒绝。

按以下步骤操作即可实现本地目录持久化，同时解决鉴权失败问题：

1. 清理异常残留
   先停掉所有相关容器，彻底清空挂载目录的所有内容（含隐藏文件），避免旧数据干扰初始化：

   docker-compose down
   sudo rm -rf ./.docker/dbdata/* ./.docker/dbdata/.*
   

   如果之前测试用的命名卷有需要保留的数据，提前备份后再执行清理。

2. 提前配置目录权限
   Linux环境下提前给挂载目录赋权，匹配MySQL容器内运行用户的权限要求：

   sudo chown -R 999:999 ./.docker/dbdata
   sudo chmod -R 750 ./.docker/dbdata
   

   Windows(WSL2)、macOS环境运行Docker Desktop时不需要手动执行chown，只需确保该目录在Docker的文件共享允许列表内即可。

3. 修正docker-compose配置
   不要只配置服务启动依赖，增加健康检查确保MySQL完全初始化完成后再启动Keycloak，参考可正常运行的配置片段：

   version: '3.8'
   services:
     db:
       image: mysql:5.7
       volumes:
         - ./.docker/dbdata:/var/lib/mysql
       environment:
         MYSQL_ROOT_PASSWORD: root_temp_pwd
         MYSQL_DATABASE: keycloak
         MYSQL_USER: keycloak
         MYSQL_PASSWORD: password
         MYSQL_INITDB_SKIP_TZINFO: "yes"
       healthcheck:
         test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-proot_temp_pwd"]
         interval: 5s
         timeout: 5s
         retries: 10
     keycloak:
       image: quay.io/keycloak/keycloak:legacy
       depends_on:
         db:
           condition: service_healthy
       environment:
         DB_VENDOR: mysql
         DB_ADDR: db
         DB_PORT: 3306
         DB_DATABASE: keycloak
         DB_USER: keycloak
         DB_PASSWORD: password
         KEYCLOAK_USER: admin
         KEYCLOAK_PASSWORD: admin
       ports:
         - "8080:8080"
   

4. 启动验证
   执行启动命令后等待10-20秒，让MySQL完成首次初始化：

   docker-compose up -d
   

   查看数据库日志确认初始化完成，出现ready for connections字样即代表数据库正常：

   docker-compose logs db | grep "ready for connections"
   

   后续Keycloak会自动完成数据库连接和自身初始化，不会再抛出数据库连接拒绝错误。

常见踩坑：不要在数据库未就绪时启动Keycloak，legacy版本的Keycloak没有自动重试数据库连接的逻辑，只要第一次连不上就会直接退出，必须通过健康检查控制启动顺序。

内容的提问来源于stack exchange，提问作者Wincenty Bertoni Lech