外观
认证账号管理
2026-04-01
nebula-auth中的认证账号(AuthAccount)是系统登录凭证的载体,与业务系统的用户(SysUser)分离。
本文介绍认证账号的状态管理、锁定/解锁操作,以及通过 RPC 创建和维护账号的规范。
目录
一、认证账号与业务用户的关系
nebula-auth nebula-system
│ │
AuthAccount SysUser
(登录凭证) ←────────── (业务用户信息)
loginName username
credentialHash nickname / email 等
status / failCount orgId / roleId 等- AuthAccount 只存储登录所需的最小信息:登录名、密码哈希、账号状态、失败次数
- SysUser 存储业务相关信息:昵称、组织、角色、权限等
- 两者通过
loginName关联,nebula-system在创建用户时通过 RPC 在nebula-auth创建对应的认证账号
二、认证账号字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
id | Long | 账号 ID |
loginName | String | 登录名(全局唯一) |
credentialHash | String | 密码哈希(BCrypt,不可逆) |
accountType | String | 账号类型(NORMAL / ADMIN 等) |
status | Integer | 状态(0:正常 1:禁用) |
failCount | Integer | 连续登录失败次数 |
lockTime | LocalDateTime | 锁定到期时间(null 表示未锁定) |
createTime | LocalDateTime | 创建时间 |
modifyTime | LocalDateTime | 最后修改时间 |
三、账号状态管理接口
接口前缀:
/auth/account
通常由系统管理后台调用
3.1 分页查询
接口: POST /auth/account/page
请求体:
{
"pageNo": 1,
"pageSize": 10,
"loginName": "admin",
"status": 0
}响应:
{
"code": 0,
"data": {
"records": [
{
"id": 10001,
"loginName": "admin",
"accountType": "ADMIN",
"status": 0,
"failCount": 0,
"lockTime": null,
"createTime": "2026-01-01T10:00:00"
}
],
"total": 1,
"pageNo": 1,
"pageSize": 10
}
}3.2 启用账号
接口: PATCH /auth/account/{accountId}/v
{ "code": 0, "message": "操作成功" }3.3 禁用账号
接口: PATCH /auth/account/{accountId}/x
禁用后,该账号无法登录,已登录的会话也会在下次校验时失效。
3.4 锁定账号
接口: PATCH /auth/account/{accountId}/lock?lockMinutes=30
| 参数 | 说明 |
|---|---|
accountId | 账号 ID(路径参数) |
lockMinutes | 锁定时长(分钟),传 0 表示永久锁定 |
账号被锁定后,登录时提示"账号已被锁定,请 N 分钟后再试"。
3.5 解锁账号
接口: PATCH /auth/account/{accountId}/unlock
解锁后:
- 账号状态恢复正常
- 失败次数重置为 0
- 锁定时间清除
四、通过 RPC 创建和管理账号
业务服务(如 nebula-system)在创建用户时,通过 AuthRpcService RPC 接口在 nebula-auth 中同步创建认证账号。
4.1 创建认证账号
@Autowired
private AuthRpcService authRpcService;
// 在创建 SysUser 的事务中,同步创建认证账号
AuthAccountCreateRequest request = new AuthAccountCreateRequest();
request.setLoginName(saveParam.getUsername());
request.setPassword(saveParam.getInitPassword()); // 初始密码(明文,auth 内部哈希存储)
request.setAccountType("NORMAL");
R<Long> result = authRpcService.createAccount(request);
Long authAccountId = result.getDataOrThrow();4.2 修改密码
AuthCredentialUpdateRequest request = new AuthCredentialUpdateRequest();
request.setLoginName(username);
request.setNewPassword(newPassword); // 新密码(明文)
request.setOldPassword(oldPassword); // 旧密码(用于验证,可选)
authRpcService.updateCredential(request);4.3 同步账号状态
当业务系统禁用用户时,同步禁用认证账号:
// 同步状态(0:正常 1:禁用)
authRpcService.syncAccountStatus(authAccountId, 1);事务注意: 业务用户表和认证账号操作不在同一个数据库中,无法通过本地事务保证原子性。
建议:先创建业务用户,再创建认证账号;若认证账号创建失败,回滚业务用户。
使用@Transactional保证业务用户操作的原子性,认证账号操作放在事务提交后执行(或使用TransactionSynchronizationManager注册回调)。
