Keycloak环境变量不生效：无法指定MySQL数据库问题排查

问题 #

我想为Keycloak指定使用的数据库，参考Keycloak官方文档后知道可以用KC_DB环境变量设置数据库厂商（比如mysql）。我基于Bitnami的Keycloak镜像创建了Dockerfile：

FROM bitnami/keycloak:18

EXPOSE 80

然后用以下命令运行容器：

docker run --name keycloak -e KC_DB=mysql -p 8080:80 keycloak

但日志显示容器仍在尝试连接PostgreSQL，无法解析postgresql主机：

PS D:\Projects\keycloak> docker run --name keycloak -e KC_DB=mysql -p 8080:80 keycloak
keycloak 23:48:07.88 
keycloak 23:48:07.88 Welcome to the Bitnami keycloak container
keycloak 23:48:07.88 Subscribe to project updates by watching https://github.com/bitnami/containers
keycloak 23:48:07.89 Submit issues and feature requests at https://github.com/bitnami/containers/issues
keycloak 23:48:07.89 
keycloak 23:48:07.89 INFO  ==> ** Starting keycloak setup **
keycloak 23:48:07.90 INFO  ==> Validating settings in KEYCLOAK_* env vars...
keycloak 23:48:07.91 INFO  ==> Trying to connect to PostgreSQL server postgresql...
cannot resolve host "postgresql": lookup postgresql on 192.168.65.5:53: read udp 172.17.0.2:51615->192.168.65.5:53: i/o timeout
...

尝试KC_DB_HOST等环境变量也没生效，Keycloak 19版本同样有这个问题，请问原因是什么？

原因与解决办法 #

你使用的是Bitnami官方打包的Keycloak镜像，这类镜像不直接采用Keycloak原生的KC_*系列环境变量，而是有一套独立的环境变量命名规则。

Bitnami镜像中用于指定数据库类型的变量是KEYCLOAK_DATABASE_VENDOR，而非原生的KC_DB。默认情况下，Bitnami Keycloak镜像会优先尝试连接PostgreSQL，因此必须使用Bitnami专属的变量进行配置：

• 指定数据库类型：设置KEYCLOAK_DATABASE_VENDOR=mysql
• 同时需配套设置完整的数据库连接信息：
  • KEYCLOAK_DATABASE_HOST：数据库主机地址
  • KEYCLOAK_DATABASE_PORT：数据库端口
  • KEYCLOAK_DATABASE_NAME：目标数据库名称
  • KEYCLOAK_DATABASE_USER：数据库用户名
  • KEYCLOAK_DATABASE_PASSWORD：数据库密码

正确的容器运行命令示例：

docker run --name keycloak \
  -e KEYCLOAK_DATABASE_VENDOR=mysql \
  -e KEYCLOAK_DATABASE_HOST=你的mysql主机地址 \
  -e KEYCLOAK_DATABASE_PORT=3306 \
  -e KEYCLOAK_DATABASE_NAME=keycloak \
  -e KEYCLOAK_DATABASE_USER=keycloak_user \
  -e KEYCLOAK_DATABASE_PASSWORD=keycloak_pass \
  -p 8080:80 \
  keycloak

核心原因是：第三方厂商打包的Keycloak镜像会自定义环境变量体系，不能直接套用Keycloak官方原生文档的配置参数，需对应查看该镜像的专属文档获取正确配置方式。

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