Docker Compose部署Keycloak时数据库连接失败问题求助

核心问题分析 #

从日志中的ERROR: keycloakdb和连接失败提示来看，主要原因是Keycloak启动时PostgreSQL数据库尚未完成初始化。Docker的depends_on仅保证Postgres容器先启动，但不会等待数据库进程完全就绪，导致Keycloak在数据库可用前发起连接请求失败。

解决方案步骤 #

1. 为PostgreSQL配置健康检查

通过healthcheck让Docker确认Postgres服务完全就绪后，再启动Keycloak。修改docker-compose.yml中的keycloakdb服务：

keycloakdb:
  image: postgres:16
  volumes:
    - postgres_data:/var/lib/postgresql/data
  environment:
    POSTGRES_DB: keycloak
    POSTGRES_USER: keycloak
    POSTGRES_PASSWORD: keycloak
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"]
    interval: 5s
    timeout: 5s
    retries: 5

2. 修改Keycloak的启动依赖条件

让Keycloak等待Postgres的健康状态，而非仅容器启动。修改keycloak_web服务的depends_on：

keycloak_web:
  # 其他配置保持不变
  depends_on:
    keycloakdb:
      condition: service_healthy

3. （可选）添加启动前等待脚本

如果健康检查方式不生效，可以给Keycloak添加启动前的等待逻辑，确保Postgres就绪：

keycloak_web:
  # 其他配置保持不变
  command: >
    bash -c "until pg_isready -h keycloakdb -p 5432 -U keycloak; do echo '等待Postgres就绪...'; sleep 2; done; start-dev"

注意：如果Keycloak镜像中没有pg_isready命令，需要先安装postgresql-client，可以通过修改镜像或自定义entrypoint实现。

4. 清理旧数据（若存在损坏）

如果之前的启动失败导致Postgres数据卷出现异常，可清理后重新启动：

docker-compose down -v
docker-compose up -d

5. 验证配置参数

再次确认以下配置完全一致：

• Postgres的POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD
• Keycloak的KC_DB_USERNAME、KC_DB_PASSWORD、KC_DB_URL中的数据库名称

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