在 Keycloak 自定义用户存储提供者（User Storage SPI）中，addUser() 方法默认不会被调用——只有当 getUserByUsername() 显式抛出 UserNotFoundException 时，Keycloak 才会进入用户创建流程并调用该方法。
在 keycloak 自定义用户存储提供者（user storage spi）中，`adduser()` 方法默认不会被调用——只有当 `getuserbyusername()` 显式抛出 `usernotfoundexception` 时，keycloak 才会进入用户创建流程并调用该方法。
Keycloak 的用户存储 SPI 设计遵循“查无则建”（query-first, create-on-miss）原则：当管理员在管理控制台点击“Add user”或通过 Admin REST API 创建新用户时，Keycloak 并不会直接调用 addUser()。相反，它首先执行查询操作——依次调用 getUserByUsername()、getUserByEmail() 和 getUserByFederatedIdentity()——以确认该用户是否已存在于外部存储中。
只有当所有这些查询方法均返回 null 或明确抛出 UserNotFoundException（注意：返回 null 不足以触发创建逻辑！），Keycloak 才会继续调用 addUser() 来持久化新用户。这是许多开发者踩坑的关键点：若 getUserByUsername() 在用户不存在时仅返回 null，Keycloak 会认为“该用户名已被占用（空占位）”，从而跳过创建步骤并静默失败。
✅ 正确实现方式（Java 示例）：
酷纬企业网站管理系统Kuwebs是酷纬信息开发的为企业网站提供解决方案而开发的营销型网站系统。在线留言模块、常见问题模块、友情链接模块。前台采用DIV+CSS，遵循SEO标准。 1.支持中文、英文两种版本，后台可以在不同的环境下编辑中英文。 3.程序和界面分离，提供通用的PHP标准语法字段供前台调用，可以为不同的页面设置不同的风格。 5.支持google地图生成、自定义标题、自定义关键词、自定义描
@Override
public UserModel getUserByUsername(RealmModel realm, String username) {
try {
// 调用外部系统查询用户（如 HTTP API）
UserDto userDto = externalUserService.findByUsername(username);
if (userDto != null) {
return new CustomUserModel(userDto, session, realm);
}
} catch (ResourceNotFoundException e) {
// ✅ 关键：API 返回 404 时，主动抛出 Keycloak 标准异常
throw new UserNotFoundException("User not found: " + username);
}
// ❌ 错误：return null; → 将导致 addUser 永远不被调用
throw new UserNotFoundException("User not found: " + username);
}⚠️ 注意事项：
- 必须抛出 org.keycloak.models.UserNotFoundException（而非自定义异常或 null），否则 Keycloak 无法识别为“查询未命中”；
- getUserByEmail() 同理需遵循相同契约，否则邮箱冲突校验可能失效；
- 若启用了“Import users on first login”，addUser() 也不会被调用——此时应实现 federatedIdentityLogin() 流程；
- 建议在 addUser() 中校验用户名/邮箱唯一性，并在冲突时抛出 ModelException 以触发友好的错误提示。
总结：addUser() 是被动触发的“后备创建入口”，其激活完全依赖于查询方法对“用户不存在”这一语义的显式、标准声明。确保 getUserByUsername() 和 getUserByEmail() 在查无结果时统一抛出 UserNotFoundException，是解锁自定义用户写入能力的第一步。
