Docker部署Keycloak连接PostgreSQL时出现配置错误

问题重现 #

运行Keycloak Docker容器并关联PostgreSQL数据库时，触发以下错误：

ERROR: Failed to run 'build' command.
ERROR: Cannot invoke "io.smallrye.config.ConfigValue.withConfigSourceName(String)" because the return value of "org.keycloak.quarkus.runtime.configuration.mappers.PropertyMapper.transformValue(String, java.util.Optional, io.smallrye.config.ConfigSourceInterceptorContext)" is null

执行的Docker命令同时混合使用了数据库相关的环境变量与命令行参数。

错误根源 #

你重复配置了数据库连接信息：既通过环境变量（DB_ADDR、DB_PORT、DB_DATABASE等）设置，又通过命令行参数（--db-url、--db-username、--db-password）定义，导致Keycloak的配置映射组件出现冲突，返回空值触发该异常。

修复方案 #

选择以下任一方式统一配置逻辑，避免重复：

方案1：仅用环境变量配置 #

移除命令行中的数据库参数，保留环境变量配置：

docker run --name mykeycloak -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e DB_VENDOR=POSTGRES \
  -e DB_ADDR=localhost \
  -e DB_PORT=5432 \
  -e DB_DATABASE=wallet_realm \
  -e DB_USER=postgres \
  -e DB_PASSWORD=postgres \
  quay.io/keycloak/keycloak:latest \
  start \
  --features=token-exchange

方案2：仅用命令行参数配置 #

移除数据库相关环境变量，保留命令行参数配置：

docker run --name mykeycloak -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest \
  start \
  --db=postgres \
  --features=token-exchange \
  --db-url=jdbc:postgresql://localhost:5432/wallet_realm \
  --db-username=postgres \
  --db-password=postgres

额外提示 #

• 若PostgreSQL同样运行在Docker容器中，需将localhost替换为PostgreSQL容器的名称或网络别名，否则Keycloak容器无法访问到数据库服务。
• 提前确认PostgreSQL服务已启动，wallet_realm数据库已创建，且postgres用户拥有该数据库的读写权限。

内容的提问来源于stack exchange，提问作者Mohamed Sid Abdalla Rgagde