Docker Compose部署Keycloak+MySQL出现连接失败错误求助

核心原因分析 #

1. 容器间网络寻址错误 #

你的Keycloak配置中KC_DB_URL设置为jdbc:mysql://localhost:3306/keycloak，但在Docker容器内部，localhost指向的是Keycloak容器自身，而非MySQL容器。在Docker Compose的自定义网络（这里是internal）中，容器之间必须通过服务名称（即mysql，对应你定义的MySQL服务名）来互相访问。

2. MySQL服务未完全就绪就发起连接 #

depends_on: { condition: service_started }仅确保MySQL容器启动，但MySQL服务需要时间完成初始化（比如创建数据库、加载权限表），此时Keycloak提前发起连接会导致通信失败。

3. MySQL 8.x认证插件兼容性问题 #

最新版MySQL 8.x默认使用caching_sha2_password认证插件，而Keycloak的JDBC驱动可能无法兼容该插件，导致连接被拒绝。

修复方案 #

修正后的docker-compose.yml #

version: "3.8" # 使用较新的Compose版本，兼容性更好

services:    
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    ports:
      - 8080:8080/tcp
    command: start-dev
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=changeme
      - KC_DB=mysql
      - KC_DB_URL=jdbc:mysql://mysql:3306/keycloak?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
      - KC_DB_USERNAME=keycloak
      - KC_DB_PASSWORD=changeme
    networks:
      - internal
    depends_on:
      mysql:
        condition: service_healthy # 等待MySQL服务完全就绪

  mysql:
    image: mysql:8.0 # 指定稳定版本，避免最新版兼容性风险
    container_name: mysql
    restart: always
    environment:
      MYSQL_DATABASE: keycloak
      MYSQL_USER: keycloak
      MYSQL_PASSWORD: changeme
      MYSQL_ROOT_PASSWORD: changeme
      MYSQL_DEFAULT_AUTH: mysql_native_password # 强制使用兼容的认证插件
    ports:
      - 3306:3306
    expose:
      - 3306
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - internal
    healthcheck: # 添加健康检查，确保MySQL服务可用
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]
      interval: 5s
      timeout: 5s
      retries: 5

networks:
  internal:
    driver: bridge

volumes:
  mysql_data:

关键修改说明 #

• 修正数据库连接地址：将KC_DB_URL中的localhost替换为mysql（MySQL服务名），并添加useSSL=false、serverTimezone=UTC等JDBC参数，解决时区和连接权限问题。
• 添加MySQL健康检查：通过healthcheck配置让Docker检测MySQL服务是否真正就绪，Keycloak仅在MySQL健康状态正常时启动。
• 强制兼容认证插件：设置MYSQL_DEFAULT_AUTH=mysql_native_password，确保Keycloak能正常完成用户认证。
• 升级Compose版本：将version从1升级到3.8，支持service_healthy等更完善的依赖控制逻辑。

内容的提问来源于stack exchange，提问作者Staudi