Keycloak无法创建用户报错排查及相关问题咨询

1. 报错信息中的‘Unexpected row count: -1; expected: 1;’是什么含义，为何会触发该错误？ #

• 含义：JPA执行用户插入语句后，预期数据库会返回1行成功插入的结果，但实际收到的返回值是-1，说明数据库未正常反馈写入结果，JPA判定操作失败。
• 触发原因：结合切换到secondary节点后恢复的情况，大概率是原数据库主节点出现故障——比如主节点写入通道异常、网络分区导致Keycloak无法和主库正常交互、主库事务处理模块故障，或是主从同步中断引发的写入阻塞，导致插入操作的结果无法被正常确认，进而触发JPA的乐观锁异常。

2. 使用(?)作为参数占位符是否属于正常情况？ #

完全正常。这是JDBC预编译SQL语句的标准占位符形式，Keycloak通过JPA操作数据库时，底层会自动生成这类预编译语句，目的是防止SQL注入，同时提升数据库执行效率。

3. 如何避免该问题再次发生？ #

• 配置数据库自动故障转移机制：当主节点检测到异常时，自动切换到可用的secondary节点，无需手动干预。
• 监控数据库状态：实时监控主节点的可用性、写入延迟、资源使用率（CPU、内存、磁盘），提前发现潜在故障。
• 定期检查主从同步：确保secondary节点与主库的数据同步正常，避免切换后出现数据不一致。
• 优化Keycloak数据库连接配置：给连接池添加健康检查机制，自动剔除失效的数据库连接，避免Keycloak持续尝试连接故障节点。
• 提升数据库集群冗余：采用多主架构或更可靠的集群方案，降低单节点故障的影响范围。

4. 已重启Keycloak集群但问题未解决，该如何处理？ #

• 优先排查数据库端：检查原主库的数据库日志，查看是否有写入失败、锁等待、资源耗尽（如磁盘满、连接数超限）等异常记录。
• 测试主库写入能力：手动执行insert into USER_ENTITY语句，验证主库是否能正常处理写入请求。
• 检查网络连通性：确认Keycloak集群与原主库之间的网络是否正常，有无防火墙拦截、网络波动等情况。
• 临时切换到secondary节点恢复服务，再深入排查原主库的故障根源（比如主节点硬件故障、数据库进程异常等）。

5. 若为事务锁定记录导致该问题，其触发原因是什么？ #

• 原主库存在长时间未提交的事务：比如某个批量操作、异常中断的事务占用了USER_ENTITY表的锁，导致新的插入请求被阻塞。
• 数据库隔离级别过高：比如使用Serializable隔离级别，会加剧锁竞争，引发写入阻塞。
• 数据库资源不足：CPU、内存耗尽导致锁无法及时释放，事务处理超时。
• 主从同步锁冲突：主库在同步数据到secondary时出现锁竞争，引发写入操作异常。

6. 通过应用程序调用API直接向数据库创建用户是否可行？ #

不建议这么做。Keycloak的用户数据分散在多个关联表（如USER_ATTRIBUTE、CREDENTIAL）中，直接写入USER_ENTITY会导致数据不一致；同时Keycloak内部的权限验证、事件记录、集群缓存同步等逻辑会被绕过，后续可能出现用户无法登录、缓存与数据库数据不匹配等问题。应该使用Keycloak官方提供的Admin API来创建用户。

7. 数据库未配置任何触发器。 #

这可以排除触发器拦截写入操作、篡改返回结果的可能性，进一步确认故障根源集中在数据库节点的可用性、事务处理或网络交互层面。

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