nebula-auth 中的认证账号（AuthAccount）是系统登录凭证的载体，与业务系统的用户（SysUser）分离。
本文介绍认证账号的状态管理、锁定/解锁操作，以及通过 RPC 创建和维护账号的规范。

---

目录

• 一、认证账号与业务用户的关系
• 二、认证账号字段说明
• 三、账号状态管理接口
• 四、通过 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 注册回调）。