系统提供了 2 种类型的用户，分别满足对应的管理后台、用户 App 场景。

• AdminUser 管理员用户，前端访问 yudao-ui-admin-vue3 (opens new window) 管理后台，后端访问 /admin-api/** RESTful API 接口。
• MemberUser 会员用户，前端访问 yudao-mall-uniapp (opens new window) 用户 App，后端访问 /app-api/** RESTful API 接口。

虽然是不同类型的用户，他们访问 RESTful API 接口时，都通过 Token 认证机制，具体可见 《开发指南 —— 功能权限》。

1. 表结构

2 种类型的时候，采用不同数据库的表进行存储，管理员用户对应 system_users (opens new window) 表，会员用户对应 member_user (opens new window) 表。如下图所示：

为什么不使用统一的用户表？

确实可以采用这样的方案，新增 type 字段区分用户类型。不同用户类型的信息字段，例如说上图的 dept_id、post_ids 等等，可以增加拓展表，或者就干脆“冗余”在用户表中。

不过实际项目中，不同类型的用户往往是不同的团队维护，并且这也是绝大多团队的实践，所以我们采用了多个用户表的方案。

如果表需要关联多种类型的用户，例如说上述的 system_oauth2_access_token 访问令牌表，可以通过 user_type 字段进行区分。并且 user_type 对应 UserTypeEnum (opens new window) 全局枚举，代码如下：

2. 如何获取当前登录的用户？

使用 SecurityFrameworkUtils (opens new window) 提供的如下方法，可以获得当前登录用户的信息：

2.1 获取当前用户信息

public static LoginUser getLoginUser()

2.2 获取当前用户编号（最常用）

public static Long getLoginUserId()

2.3 获取当前用户昵称

public static LoginUser getLoginUserNickname()

注意，仅适合 AdminUser 管理员用户！

2.4 获取当前用户部门

public static Long getLoginUserDeptId()

注意，仅适合 AdminUser 管理员用户！

2.5 获取更多信息

① 在 OAuth2TokenServiceImpl 的 #buildUserInfo(...) 方法中，补充读取更多的用户信息，例如说 mobile、sex 等等。如下图所示：

图片纠错：最新版本引入 `yudao-module-system` 依赖即可，因为 `yudao-module-system-api` 已经合并到 `yudao-module-system` 中。

② 在 SecurityFrameworkUtils 新增对应的 getXXX() 静态方法，参考如下图所示：

3. 账号密码登录

3.1 管理后台的实现

使用 username 账号 + password 密码进行登录，由 AuthController (opens new window) 提供 /admin-api/system/auth/login 接口。代码如下：

@PostMapping("/login")
@Operation(summary = "使用账号密码登录")
public CommonResult<AuthLoginRespVO> login(@RequestBody @Valid AuthLoginReqVO reqVO) {
    String token = authService.login(reqVO, getClientIP(), getUserAgent());
    // 返回结果
    return success(AuthLoginRespVO.builder().token(token).build());
}

如何关闭验证码？

参见 《后端手册 —— 验证码》 文档。

3.2 用户 App 的实现

使用 mobile 手机 + password 密码进行登录，由 AppAuthController (opens new window) 提供 /app-api/member/auth/login 接口。代码如下：

@PostMapping("/login")
@Operation(summary = "使用手机 + 密码登录")
public CommonResult<AppAuthLoginRespVO> login(@RequestBody @Valid AppAuthLoginReqVO reqVO) {
    String token = authService.login(reqVO, getClientIP(), getUserAgent());
    // 返回结果
    return success(AppAuthLoginRespVO.builder().token(token).build());
}

4. 手机验证码登录

4.1 管理后台的实现

① 使用 mobile 手机号获得验证码，由 AuthController (opens new window) 提供 /admin-api/system/auth/send-sms-code 接口。代码如下：

@PostMapping("/send-sms-code")
@Operation(summary = "发送手机验证码")
public CommonResult<Boolean> sendSmsCode(@RequestBody @Valid AuthSendSmsReqVO reqVO) {
    authService.sendSmsCode(getLoginUserId(), reqVO);
    return success(true);
}

② 使用 mobile 手机 + code 验证码进行登录，由 AppAuthController (opens new window) 提供 /admin-api/system/auth/sms-login 接口。代码如下：

@PostMapping("/sms-login")
@Operation(summary = "使用短信验证码登录")
public CommonResult<AuthLoginRespVO> smsLogin(@RequestBody @Valid AuthSmsLoginReqVO reqVO) {
    String token = authService.smsLogin(reqVO, getClientIP(), getUserAgent());
    // 返回结果
    return success(AuthLoginRespVO.builder().token(token).build());
}

4.2 用户 App 的实现

① 使用 mobile 手机号获得验证码，由 AppAuthController (opens new window) 提供 /app-api/member/auth/send-sms-code 接口。代码如下：

@PostMapping("/send-sms-code")
@Operation(summary = "发送手机验证码")
public CommonResult<Boolean> sendSmsCode(@RequestBody @Valid AppAuthSendSmsReqVO reqVO) {
    authService.sendSmsCode(getLoginUserId(), reqVO);
    return success(true);
}

② 使用 mobile 手机 + code 验证码进行登录，由 AppAuthController (opens new window) 提供 /app-api/member/auth/sms-login 接口。代码如下：

@PostMapping("/sms-login")
@Operation(summary = "使用手机 + 验证码登录")
public CommonResult<AppAuthLoginRespVO> smsLogin(@RequestBody @Valid AppAuthSmsLoginReqVO reqVO) {
    String token = authService.smsLogin(reqVO, getClientIP(), getUserAgent());
    // 返回结果
    return success(AppAuthLoginRespVO.builder().token(token).build());
}

如果用户未注册，会自动使用手机号进行注册会员用户。所以，/app-api/member/user/sms-login 接口也提供了用户注册的功能。

5. 三方登录

详细参见 《开发指南 —— 三方登录》 文章。

5.1 管理后台的实现

① 跳转第三方平台，来获得三方授权码，由 AuthController (opens new window) 提供 /admin-api/system/auth/social-auth-redirect 接口。代码如下：

@GetMapping("/social-auth-redirect")
@Operation(summary = "社交授权的跳转")
@Parameters({
        @Parameter(name = "type", description = "社交类型", required = true),
        @Parameter(name = "redirectUri", description = "回调路径")
})
public CommonResult<String> socialAuthRedirect(@RequestParam("type") Integer type,
                                                @RequestParam("redirectUri") String redirectUri) {
    return CommonResult.success(socialUserService.getAuthorizeUrl(type, redirectUri));
}

② 使用 code 三方授权码进行快登录，由 AuthController (opens new window) 提供 /admin-api/system/auth/social-login 接口。代码如下：

@PostMapping("/social-login")
@Operation(summary = "社交快捷登录，使用 code 授权码")
public CommonResult<AuthLoginRespVO> socialQuickLogin(@RequestBody @Valid AuthSocialQuickLoginReqVO reqVO) {
    String token = authService.socialLogin(reqVO, getClientIP(), getUserAgent());
    // 返回结果
    return success(AuthLoginRespVO.builder().token(token).build());
}

③ 使用 socialCode 三方授权码 + username + password 进行绑定登录，直接使用 /admin-api/system/auth/login 账号密码登录的接口，区别在于额外带上 socialType + socialCode + socialState 参数。

5.2 用户 App 的实现

① 跳转第三方平台，来获得三方授权码，由 AppAuthController (opens new window) 提供 /app-api/member/auth/social-auth-redirect 接口。代码如下：

@GetMapping("/social-auth-redirect")
@Operation(summary = "社交授权的跳转")
@Parameters({
        @Parameter(name = "type", description = "社交类型", required = true),
        @Parameter(name = "redirectUri", description = "回调路径")
})
public CommonResult<String> socialAuthRedirect(@RequestParam("type") Integer type,
                                               @RequestParam("redirectUri") String redirectUri) {
    return CommonResult.success(socialUserService.getAuthorizeUrl(type, redirectUri));
}

② 使用 code 三方授权码进行快登录，由 AppAuthController (opens new window) 提供 /app-api/member/auth/social-login 接口。代码如下：

@PostMapping("/social-login")
@Operation(summary = "社交快捷登录，使用 code 授权码")
public CommonResult<AppAuthLoginRespVO> socialQuickLogin(@RequestBody @Valid AuthSocialQuickLoginReqVO reqVO) {
    String token = authService.socialLogin(reqVO, getClientIP(), getUserAgent());
    // 返回结果
    return success(AuthLoginRespVO.builder().token(token).build());
}

③ 使用 socialCode 三方授权码 + username + password 进行绑定登录，直接使用 /app-api/system/auth/login 手机验证码登录的接口，区别在于额外带上 socialType + socialCode + socialState 参数。

④ 【微信小程序特有】使用 phoneCode + loginCode 实现获取手机号并一键登录，由 AppAuthController (opens new window) 提供 /app-api/member/auth/weixin-mini-app-login 接口。代码如下：

@PostMapping("/weixin-mini-app-login")
@Operation(summary = "微信小程序的一键登录")
public CommonResult<AppAuthLoginRespVO> weixinMiniAppLogin(@RequestBody @Valid AppAuthWeixinMiniAppLoginReqVO reqVO) {
    return success(authService.weixinMiniAppLogin(reqVO));
}

6. 扫码登录

管理后台的电脑登录页展示二维码，使用已登录的 yudao-ui-admin-uniapp (opens new window) 手机端扫码并确认后，电脑领取自己独立的 Token 完成登录。

与三方登录的区别

扫码登录是本系统的管理员用户「用手机授权电脑」，不依赖企业微信、钉钉等第三方平台。三方登录参见 《开发指南 —— 三方登录》 文档。

6.1 交互流程

① 电脑调用 create-qrcode 接口，获得 qrcodeId 二维码编号、secret 领取凭证、qrContent 二维码内容，展示二维码并开始轮询。

② 手机扫码，识别 YuDaoLogin:{qrcodeId} 后进入确认页，用户点击【确认登录】后，调用 confirm-qrcode 接口。

③ 电脑使用 qrcodeId + secret 轮询 qrcode-login 接口：status 为 0 表示等待确认；为 1 表示已确认，同时返回 login 登录结果。

接口	调用方	是否需要登录	说明
/admin-api/system/auth/create-qrcode	电脑	否	生成二维码
/admin-api/system/auth/confirm-qrcode	手机	是	当前登录用户确认
/admin-api/system/auth/qrcode-login	电脑	否	轮询并领取登录结果

6.2 后端实现

在 yudao-module-system 模块中，调用链如下：

• 生成、确认：AuthController 直接调用 AdminAuthQrcodeService 的 createAuthQrcode、confirmAuthQrcode 方法。
• 领取登录：AuthController → AdminAuthService#qrcodeLogin → AdminAuthQrcodeService#pollAuthQrcode → AdminAuthQrcodeRedisDAO。确认成功后，为电脑创建独立的 Token，并记录 LOGIN_QRCODE(105) 类型的登录日志。

二维码数据存储在 Redis 的一个 Hash 中，由 AdminAuthQrcodeRedisDAO 使用 Lua 脚本保证原子性：

• key 为 auth_qrcode:{qrcodeId}，开启多租户时追加当前租户编号作为后缀，进行隔离。
• 字段只有 status（0 等待确认、1 已确认）、userId、secretHash（secret 的 SHA-256 摘要），不存储租户编号和 Token。
• 固定 180 秒过期，确认时不续期；电脑领取成功后立即删除，只能领取一次。

二维码中只包含 YuDaoLogin: 前缀和 32 位编号，不包含 secret，所以拍到二维码的其他人，无法领取电脑的登录结果。

二维码过期、已被领取或凭证错误时，返回 AUTH_QRCODE_INVALID 错误；被其他用户抢先确认时，返回 AUTH_QRCODE_ALREADY_CONFIRMED 错误。此时，电脑刷新生成新的二维码，重新扫码即可。

多租户

电脑和手机必须属于同一个租户：电脑在登录页先选择租户，3 个接口都携带 tenant-id 请求头，走正常的 HTTP 租户校验，未使用 @TenantIgnore 注解。其他租户的手机扫码，会因 Redis key 不同而提示二维码失效。详细参见 《开发指南 —— SaaS 多租户【字段隔离】》 文档。

6.3 前端实现

① 电脑端：

• yudao-ui-admin-vue3 (opens new window)：src/api/login/index.ts、src/views/Login/components/QrCodeForm.vue
• yudao-ui-admin-vben (opens new window)：apps/web-antd、apps/web-antdv-next、apps/web-ele 下的 src/api/core/auth.ts、src/views/_core/authentication/qrcode-login.vue

② 手机端 yudao-ui-admin-uniapp (opens new window)：

• src/pages/index/index.vue：首页右上角的扫一扫入口，只接受 YuDaoLogin: + 32 位编号的二维码。
• src/pages-core/auth/qrcode/index.vue：确认页，用户点击后才调用 src/api/login.ts 的 confirmQrcode 方法。

扫一扫的平台限制

扫一扫基于 uni.scanCode 实现，仅 App 和微信小程序支持，H5 不显示扫码入口。手机端的运行，可见 《前端手册 Admin Uniapp —— 运行发布》 文档。

7. 注册

7.1 管理后台的实现

管理后台暂不支持用户注册，而是通过在 [系统管理 -> 用户管理] 菜单，进行添加用户，由 UserController (opens new window) 提供 /admin-api/system/user/create 接口。代码如下：

@PostMapping("/create")
@Operation(summary = "新增用户")
@PreAuthorize("@ss.hasPermission('system:user:create')")
public CommonResult<Long> createUser(@Valid @RequestBody UserCreateReqVO reqVO) {
    Long id = userService.createUser(reqVO);
    return success(id);
}

7.2 用户 App 的实现

手机验证码登录时，如果用户未注册，会自动使用手机号进行注册会员用户。所以，/app-api/system/user/sms-login 接口也提供了用户注册的功能。

8. 用户登出

用户登出的功能，统一使用 Spring Security 框架，通过删除用户 Token 的方式来实现。代码如下：

差别在于使用的 API 接口不同，管理员用户使用 /admin-api/system/logout，会员用户使用 /app-api/member/logout。

666. 社区贡献相关

• 《Pull Request：新增单账号登录限制功能，限制后台账号（admin类型）在同一端（PC、APP、H5等）无法同时登录，功能开启在配置管理中有配置开关》 (opens new window)、前端部分 (opens new window)
• 新增是否允许账号多设备登录的配置 (opens new window)
• 同一账号同时登录多台设备的个数配置 (opens new window)
• 《后端如何转发 static 静态资源》 (opens new window)
• 《Pull Request：添加部门路径》 (opens new window)