Keycloak生产容器docker run可连PostgreSQL，docker-compose失败

核心问题根源 #

docker-compose启动失败的关键原因是volume挂载路径错误：你将keycloak-data volume直接挂载到了容器的/opt/keycloak目录，这会完全覆盖镜像中Keycloak的安装内容——包括builder阶段构建的PostgreSQL驱动文件。没有驱动的情况下，Keycloak无法识别PostgreSQL的JDBC URL，从而抛出Driver does not support the provided URL错误。

而docker run命令中并未挂载整个/opt/keycloak目录，镜像里的构建内容（含PostgreSQL驱动）得以保留，因此能正常连接数据库。

具体修复步骤 #

1. 修正Docker Compose的Volume挂载路径 #

不要覆盖整个Keycloak安装目录，只挂载数据存储目录/opt/keycloak/data（该目录用于存储主题、导入配置等用户数据，不会影响镜像自带的核心文件）：

services:
  keycloak:
    # ...其他配置
    volumes:
      - keycloak-data:/opt/keycloak/data  # 修改此处的挂载路径

2. 修复Keycloak.env的格式与变量名错误 #

• env文件需使用=而非:定义变量
• Keycloak管理员用户名的正确变量名是KEYCLOAK_ADMIN，不是KEYCLOAK_ADMIN_USER

修正后的keycloak.env：

KEYCLOAK_ADMIN=admin_user
KEYCLOAK_ADMIN_PASSWORD=some_strong_password
KEYCLOAK_FRONTEND_URL=https://keycloak.tld.com

3. 添加数据库健康检查（可选但推荐） #

depends_on仅保证启动顺序，不等待数据库服务就绪。添加健康检查确保Keycloak在数据库完全可用后再启动：

services:
  pgkeydb:
    # ...其他配置
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d keycloak"]
      interval: 5s
      timeout: 5s
      retries: 5
  keycloak:
    # ...其他配置
    depends_on:
      pgkeydb:
        condition: service_healthy

验证流程 #

1. 重新构建镜像：docker build . -t service-keycloak
2. 启动服务：docker compose up -d
3. 查看日志确认连接正常：docker compose logs keycloak

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