Keycloak v20.0.3无法连接VM上的PostgreSQL 12，K8S环境正常

问题背景 #

• Keycloak v20.0.1/v20.0.3 无法连接VM上的PostgreSQL 12（Ubuntu 18.04），但连接K8S部署的PostgreSQL正常
• Docker环境：Docker Desktop 4.16.3 (96739)
• 核心错误：
  • Keycloak容器日志：org.postgresql.util.PSQLException: Connection has been closed.
  • PostgreSQL日志：连接授权成功，但查询时触发FATAL: relation "migration_model" does not exist，随后连接断开

已尝试的配置 #

环境变量配置 #

KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=admin
KC_DB=postgres
KC_DB_URL_DATABASE=web-oidc-v20
KC_DB_URL_HOST=192.168.201.23
KC_DB_URL_PORT=5432
KC_DB_USERNAME=web-oidc
KC_DB_PASSWORD=Abcd@1234
KC_HOSTNAME_ADMIN_URL=http://localhost:8080
KC_HOSTNAME_URL=http://localhost:8080

JDBC URL替换尝试 #

曾用KC_DB_URL=jdbc:postgresql://192.168.201.23:5432/web-oidc-v20替代拆分的URL参数，问题依旧

Docker启动命令 #

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -e KC_DB=postgres -e KC_DB_URL_DATABASE=web-oidc-v20 -e KC_DB_URL_HOST=192.168.201.23 -e KC_DB_URL_PORT=5432 -e KC_DB_USERNAME=web-oidc -e KC_DB_PASSWORD=Abcd@1234 -e KC_HOSTNAME_ADMIN_URL=http://localhost:8080 -e KC_HOSTNAME_URL=http://localhost:8080 web-oidc-v20

排查步骤 #

1. 检查PostgreSQL用户权限与Schema #

migration_model是Keycloak初始化时创建的迁移表，默认在连接用户的默认Schema下生成，优先排查权限问题：

• 登录PostgreSQL，临时赋予用户超级权限测试：

  ALTER USER web-oidc WITH SUPERUSER;
  

  重启Keycloak，若能正常创建表，说明原用户缺少CREATE TABLE、CREATE SCHEMA等权限，执行以下语句补全：

  GRANT ALL PRIVILEGES ON DATABASE web-oidc-v20 TO web-oidc;
  ALTER USER web-oidc CREATEDB CREATEROLE;
  

2. 检查PostgreSQL的search_path配置 #

若用户默认Schema不是public，Keycloak会找不到目标表：

• 执行语句修改用户默认搜索路径：

  ALTER USER web-oidc SET search_path TO public, "$user";
  

• 重启PostgreSQL服务：

  sudo systemctl restart postgresql
  

3. 重建空数据库 #

若数据库存在残留数据或异常表结构，会导致初始化失败：

• 备份数据库后，重建空库：

  DROP DATABASE web-oidc-v20;
  CREATE DATABASE web-oidc-v20;
  

• 重新赋予用户权限：

  GRANT ALL PRIVILEGES ON DATABASE web-oidc-v20 TO web-oidc;
  

• 重启Keycloak

4. 验证Docker网络连通性 #

确认Docker容器能正常访问VM的PostgreSQL端口：

• 宿主机端测试：

  nc -zv 192.168.201.23 5432
  

• 容器内部测试（进入容器后执行）：

  # 若容器基于Alpine，先安装工具
  apk add busybox-extras
  telnet 192.168.201.23 5432
  

5. 检查PostgreSQL的pg_hba.conf配置 #

确保VM上的PostgreSQL允许Docker所在网段的连接：

• 编辑/etc/postgresql/12/main/pg_hba.conf，添加或修改规则：

  host    web-oidc-v20    web-oidc    <宿主机IP>/24    scram-sha-256
  

  替换<宿主机IP>为Docker所在宿主机的实际IP（如192.168.201.x）
• 重启PostgreSQL服务：

  sudo systemctl restart postgresql
  

6. 补全Keycloak启动模式参数 #

Keycloak v20需要显式指定启动模式，缺少时会导致初始化逻辑异常：

• 开发环境添加start-dev参数，重新启动：

  docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -e KC_DB=postgres -e KC_DB_URL=jdbc:postgresql://192.168.201.23:5432/web-oidc-v20 -e KC_DB_USERNAME=web-oidc -e KC_DB_PASSWORD=Abcd@1234 web-oidc-v20 start-dev
  

  生产环境替换为start参数

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