Keycloak无法连接MariaDB Galera数据库问题求助

问题现象 #

通过Bitnami Helm Chart安装Keycloak并配置外部MariaDB Galera数据库后，Pod启动时报错，日志显示java.net.UnknownHostException: mariadb-galera.default.svc.cluster.local;databaseName=bitnami_keycloak;，无法解析数据库主机地址。

安装命令 #

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm upgrade keycloak bitnami/keycloak --create-namespace --install --namespace default --values values-keycloak.yaml --version 13.3.0

配置文件values-keycloak.yaml #

global:
  storageClass: "hcloud-volumes"
auth:
  adminUser: user
  adminPassword: "user"
tls:
  enabled: true
  autoGenerated: true
production: true
extraEnvVars:
  - name: KC_DB
    value: 'mariadb'
  - name: KC_DB_URL
    value: 'jdbc:mariadb://mariadb-galera.default.svc.cluster.local;databaseName=bitnami_keycloak;'
replicaCount: 1
service:
  type: ClusterIP
ingress:
  enabled: true
  hostname: example.com
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-staging
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/proxy-buffer-size: 128k
  tls: true
postgresql:
  enabled: false
externalDatabase:
  host: "mariadb-galera.default.svc.cluster.local"
  port: 3306
  user: bn_keycloak
  database: bitnami_keycloak
  password: "password"

关键错误日志 #

Caused by: java.net.UnknownHostException: mariadb-galera.default.svc.cluster.local;databaseName=bitnami_keycloak;
    at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:567)
    at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
    at java.base/java.net.Socket.connect(Socket.java:633)
    at org.mariadb.jdbc.client.impl.ConnectionHelper.connectSocket(ConnectionHelper.java:130)
    ... 11 more

问题原因 #

MariaDB JDBC URL格式错误：自定义的KC_DB_URL用;分隔主机地址和数据库名称，但MariaDB JDBC驱动要求URL格式为jdbc:mariadb://<host>:<port>/<database>，额外参数需用?开头、&分隔。错误格式导致驱动把mariadb-galera.default.svc.cluster.local;databaseName=bitnami_keycloak;整个字符串当作主机名解析，无法找到对应服务。

此外，Bitnami的Keycloak Chart在配置externalDatabase字段后，会自动生成正确的JDBC URL，手动设置KC_DB_URL反而覆盖了正确配置。

解决方案 #

方法一：移除自定义KC_DB_URL配置 #

修改values-keycloak.yaml，删除extraEnvVars中的KC_DB_URL条目，保留KC_DB指定数据库类型（也可删除，Chart会根据externalDatabase自动识别）：

extraEnvVars:
  - name: KC_DB
    value: 'mariadb'
# 移除以下错误配置
# - name: KC_DB_URL
#   value: 'jdbc:mariadb://mariadb-galera.default.svc.cluster.local;databaseName=bitnami_keycloak;'

方法二：修正KC_DB_URL格式 #

若需手动指定JDBC URL，使用正确格式：

extraEnvVars:
  - name: KC_DB
    value: 'mariadb'
  - name: KC_DB_URL
    value: 'jdbc:mariadb://mariadb-galera.default.svc.cluster.local:3306/bitnami_keycloak'

需添加额外参数时（如禁用SSL）：

value: 'jdbc:mariadb://mariadb-galera.default.svc.cluster.local:3306/bitnami_keycloak?useSSL=false'

重新部署Keycloak #

执行helm升级命令应用配置：

helm upgrade keycloak bitnami/keycloak --create-namespace --install --namespace default --values values-keycloak.yaml --version 13.3.0

验证 #

查看Keycloak Pod日志，确认数据库连接成功：

kubectl logs -n default keycloak-0

若日志无UnknownHostException且Keycloak正常启动，说明问题已解决。

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