Keycloak一次性获取用户数量不一致问题求助

问题确认 #

这是Keycloak的已知问题，在处理大规模用户集合的单次批量查询场景下，已有不少用户反馈过类似的返回结果数量不稳定的情况，尤其是当用户规模超过10000量级时。

可能的原因 #

• Keycloak内部查询限制：Keycloak默认对用户查询设置了隐性的返回上限，即使你传入了足够大的max参数，实际返回结果也可能被内部机制截断，这个上限通常在10000-20000之间（不同版本略有差异）。
• 数据库层面限制：单次拉取大量用户数据时，数据库可能因查询超时、内存资源不足等原因提前终止查询，导致返回不完整的结果集。
• 客户端请求超时：Resteasy客户端默认的读取超时时间较短，大结果集在传输过程中可能因超时被截断。

非分批获取的解决方案 #

1. 调整Keycloak的用户查询上限参数 #

在Keycloak启动时添加JVM系统参数，增大允许的单次查询返回数量：

# Docker部署时的启动示例
docker run -e JAVA_OPTS="-Dkeycloak.user.query.limit=50000" quay.io/keycloak/keycloak:21.1.1 start

该参数值需设置为大于你的实际用户总数（比如你的场景设置为50000），确保单次查询能覆盖所有用户。

2. 优化Resteasy客户端配置 #

增大客户端的读取超时时间，避免大结果集传输超时：

keycloakServiceRealm = KeycloakBuilder.builder()
                                  .serverUrl(keycloakServerUrl)
                                  .grantType(OAuth2Constants.CLIENT_CREDENTIALS)
                                  .realm(keycloakRealm)
                                  .clientId(keycloakServiceClient)
                                  .username(keycloakServiceUsername)
                                  .clientSecret(keycloakServiceSecret)
                                  .resteasyClient(
                                          new ResteasyClientBuilderImpl()
                                                  .connectionPoolSize(10)
                                                  .readTimeout(30000, TimeUnit.MILLISECONDS) // 设置30秒读取超时
                                                  .build())
                                  .build()
                                  .realm(keycloakRealm);

3. 验证用户总数准确性 #

确认users().count()返回的数值与实际用户总数一致：

• 直接通过Keycloak管理控制台查看对应Realm的用户总数，对比count()的结果。
• 如果存在差异，可能是缓存或数据库事务问题，可以尝试重启Keycloak或清理缓存后再测试。

4. 优化数据库配置 #

如果是使用外部数据库（而非内置H2），可以调整数据库的查询超时、内存分配等参数，确保能处理大查询请求：

• 例如PostgreSQL可以调整statement_timeout参数，MySQL调整wait_timeout等。

补充说明 #

虽然分批获取（如每次拉取1000条）是最稳妥、兼容性最好的方案，但上述方法可以在避免额外请求的前提下尝试解决问题。需要注意的是，增大单次查询上限可能会增加Keycloak和数据库的资源消耗，需根据服务器配置调整合适的参数值。

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