Keycloak配置PostgreSQL异常：默认连接H2数据库问题

一、先确认核心配置是否到位 #

Keycloak 17+采用Quarkus架构，连接PostgreSQL必须明确指定数据库类型，这是绝大多数问题的根源：

• 必须设置KC_DB=postgres，没这个参数的话，Keycloak默认用内置H2数据库，不管你写什么PostgreSQL连接串都没用
• 配套的连接参数要和PostgreSQL服务匹配：
  • KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak：这里的postgres要和docker-compose里PostgreSQL的服务名一致
  • KC_DB_USERNAME=keycloak、KC_DB_PASSWORD=你的密码：要和PostgreSQL容器的初始化参数对应

二、针对「不带--optimized启动但无数据库表」的问题 #

这种情况基本是Keycloak没切换到PostgreSQL模式，还在默认用H2：

1. 查看Keycloak容器日志，搜database关键词，如果看到Using H2 database的提示，说明KC_DB=postgres没生效，检查docker-compose里的环境变量是否写错、是否被覆盖
2. 官方Keycloak镜像已经自带PostgreSQL驱动，不需要额外挂载，但如果是你自定义的Dockerfile，要确认驱动jar包已经放到/opt/keycloak/providers目录下
3. 可以先运行start --auto-build命令，强制Keycloak根据配置构建镜像并初始化数据库，再启动服务

三、针对「带--optimized启动提示URL格式错误」的问题 #

--optimized是生产优化模式，对配置校验更严格，报错的原因还是KC_DB没设为postgres，系统默认期望H2的URL格式，自然不识别PostgreSQL的连接串：

1. 确保KC_DB=postgres这个环境变量在docker-compose里配置正确，没有拼写错误
2. 先执行一次start --auto-build完成数据库初始化和镜像优化，之后再用start --optimized启动，避免直接启动时初始化不完整

四、单独启动容器仍无数据写入的问题 #

单独启动时要注意网络和连接有效性：

1. 确保两个容器在同一个Docker网络里，手动启动的话，用docker network create keycloak-net创建网络，启动时加--network keycloak-net参数
2. 进入PostgreSQL容器，检查Keycloak的数据库是否存在、是否有表：

   docker exec -it 你的postgres容器名 psql -U keycloak -d keycloak
   # 查看所有表
   \dt
   

3. 如果表不存在，手动执行Keycloak的数据库迁移命令：

   docker exec -it 你的keycloak容器名 /opt/keycloak/bin/kc.sh db migrate
   

五、完整可用的docker-compose示例 #

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak123
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak-network

  keycloak:
    image: quay.io/keycloak/keycloak:22.0.3
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak123
      KC_HOSTNAME: localhost
      KC_HTTP_PORT: 8080
      KC_ADMIN: admin
      KC_ADMIN_PASSWORD: admin123
    command: start --optimized
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    networks:
      - keycloak-network

volumes:
  postgres_data:

networks:
  keycloak-network:

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