Keycloak导入Realm失败：PostgreSQL唯一约束冲突问题

错误现象 #

Keycloak日志报错：

ERROR: duplicate key value violates unique constraint "uk_b71cjlbenv945rb6gcon438at"
Detail: Key (realm_id, client_id)=(walter, account-console) already exists

Azure PostgreSQL日志同步显示：

duplicate key value violates unique constraint "uk_b71cjlbenv945rb6gcon438at"
2023-09-29 15:49:58 UTC-6516f21f.73e80-DETAIL: Key (realm_id, client_id)=(walter, account-console) already exists.
2023-09-29 15:49:58 UTC-6516f21f.73e80-STATEMENT: insert into public.CLIENT (ALWAYS_DISPLAY_IN_CONSOLE, BASE_URL, BEARER_ONLY, CLIENT_AUTHENTICATOR_TYPE, CLIENT_ID, CONSENT_REQUIRED, DESCRIPTION, DIRECT_ACCESS_GRANTS_ENABLED, ENABLED, FRONTCHANNEL_LOGOUT, FULL_SCOPE_ALLOWED, IMPLICIT_FLOW_ENABLED, MANAGEMENT_URL, NAME, NODE_REREG_TIMEOUT, NOT_BEFORE, PROTOCOL, PUBLIC_CLIENT, REALM_ID, REGISTRATION_TOKEN, ROOT_URL, SECRET, SERVICE_ACCOUNTS_ENABLED, STANDARD_FLOW_ENABLED, SURROGATE_AUTH_REQUIRED, ID) values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26)

但检查数据库未找到walter Realm的对应记录。

问题原因 #

1. 残留数据：之前的导入操作或初始化脚本可能已向CLIENT表插入了(walter, account-console)记录，但对应的Realm记录未成功创建或被删除，导致唯一约束冲突。
2. 增量导入默认行为：Keycloak默认采用增量导入模式，即使Realm不存在，也会尝试保留已有的Client记录，进而触发冲突。
3. 导入文件与Realm名称不匹配：导入的abc-realm.json中定义的Realm名称可能为walter，与文件名不一致，导致导入逻辑混乱。

解决方案 #

1. 清理数据库残留数据 #

连接到Azure PostgreSQL，执行以下SQL查询并删除冲突记录：

-- 确认冲突记录是否存在
SELECT * FROM public.CLIENT WHERE realm_id = 'walter' AND client_id = 'account-console';

-- 如果存在则删除
DELETE FROM public.CLIENT WHERE realm_id = 'walter' AND client_id = 'account-console';

2. 修改Keycloak导入模式为覆盖模式 #

在values.yaml的extraEnv中添加导入行为参数，将默认的增量导入改为覆盖导入：

extraEnv: |
  - name: PROXY_ADDRESS_FORWARDING
    value: "true"
  - name: DB_VENDOR
    value: postgres
  # ... 其他原有环境变量 ...
  - name: KEYCLOAK_IMPORT
    value: "/realm/init-realm/abc-realm.json"
  - name: JAVA_OPTS
    value: "-Dkeycloak.import.action=replace"

或者直接修改KEYCLOAK_IMPORT的值：

- name: KEYCLOAK_IMPORT
  value: "/realm/init-realm/abc-realm.json -Dkeycloak.import.action=replace"

3. 验证导入文件的Realm名称 #

打开abc-realm.json，确认文件中realm字段的值是否为walter：

{
  "realm": "walter",
  // ... 其他配置 ...
}

若文件名与Realm名称不一致，建议统一命名（如改为walter-realm.json），避免后续混淆。

4. 检查初始化脚本 #

查看keycloak-postgres-configuration-script中的postgres-records.sql，确认是否存在手动插入walter Realm相关Client的语句，若有则移除或修改，避免重复插入。

验证操作 #

重新部署Keycloak，查看日志确认导入成功，无约束冲突报错。

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