Sa-Token实现多账号认证体系的技术实践-拓冰建站

1. Sa-Token框架的多账号认证需求背景

在现代企业级应用开发中，多账号类型并存是极为常见的场景。以典型的CMS系统为例，通常需要同时支持Admin管理员账号和User普通用户账号的登录与权限控制。这两种账号类型在权限粒度、会话时长、安全等级等方面往往存在显著差异：

Admin账号：需要更高的安全防护，通常要求强制二次验证、频繁的会话过期检查、细粒度的操作日志记录
User账号：更注重用户体验，会话保持时间较长，权限控制相对简单

传统做法是为每种账号类型单独实现一套认证逻辑，但这会导致代码重复和维护成本增加。Sa-Token作为轻量级Java权限认证框架，其多账号认证体系正是为解决这类问题而设计。

2. 基础环境搭建与Sa-Token配置

2.1 依赖引入与基础配置

首先在Spring Boot项目中引入Sa-Token依赖（以Maven为例）：

<dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-spring-boot-starter</artifactId> <version>1.45.0</version> </dependency>

然后在application.yml中进行基础配置：

sa-token: # 令牌名称 token-name: satoken # 令牌有效期（单位：秒） timeout: 86400 # 临时令牌有效期（用于记住我功能） activity-timeout: 2592000 # 是否允许同一账号并发登录 is-concurrent: true # 在多人登录同一账号时，是否共用一个token is-share: false

2.2 多账号认证的核心配置

在config包下创建SaTokenConfig.java，配置多账号认证体系：

@Configuration public class SaTokenConfig implements SaTokenConfigurator { @Override public void configure(SaManagerConfig config) { // 配置多账号体系 config.setTokenStyle("uuid") .setTokenSessionCheckLogin(true) .setTokenActiveTimeout(3600); } }

3. 实现Admin与User双账号认证体系

3.1 账号类型枚举定义

首先定义账号类型常量，便于后续区分：

public class AccountType { public static final String ADMIN = "admin"; public static final String USER = "user"; }

3.2 登录认证实现

创建AuthService处理登录逻辑：

@Service public class AuthService { @Autowired private AdminMapper adminMapper; @Autowired private UserMapper userMapper; public String login(String accountType, String username, String password) { switch (accountType) { case AccountType.ADMIN: Admin admin = adminMapper.selectByUsername(username); if (admin == null || !admin.getPassword().equals(password)) { throw new ApiException("管理员账号或密码错误"); } // 管理员登录 StpUtil.login(admin.getId(), new SaLoginModel() .setDevice("PC") .setExtra("accountType", AccountType.ADMIN)); break; case AccountType.USER: User user = userMapper.selectByUsername(username); if (user == null || !user.getPassword().equals(password)) { throw new ApiException("用户账号或密码错误"); } // 用户登录 StpUtil.login(user.getId(), new SaLoginModel() .setDevice("APP") .setExtra("accountType", AccountType.USER)); break; default: throw new ApiException("不支持的账号类型"); } return StpUtil.getTokenValue(); } }

3.3 权限校验实现

创建自定义权限拦截器：

@Component public class AuthInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { // 获取当前登录账号类型 String accountType = (String) StpUtil.getExtra("accountType"); // 管理员专属接口校验 if (request.getRequestURI().startsWith("/admin/")) { if (!AccountType.ADMIN.equals(accountType)) { throw new NotPermissionException("无管理员权限"); } } // 用户专属接口校验 if (request.getRequestURI().startsWith("/user/")) { if (!AccountType.USER.equals(accountType)) { throw new NotPermissionException("无用户权限"); } } return true; } }

4. 高级特性与安全增强

4.1 差异化会话配置

在SaTokenConfig中扩展配置：

// 管理员会话配置 StpUtil.StpLogic adminStpLogic = new StpUtil.StpLogic(AccountType.ADMIN) .setTokenTimeout(7200) // 2小时过期 .setTokenActiveTimeout(1800); // 30分钟无操作过期 // 用户会话配置 StpUtil.StpLogic userStpLogic = new StpUtil.StpLogic(AccountType.USER) .setTokenTimeout(259200) // 3天过期 .setTokenActiveTimeout(86400); // 1天无操作过期

4.2 安全防护措施

针对管理员账号增加安全防护：

public class AdminSecurityService { // 管理员登录需验证验证码 public void checkAdminLogin(String username, String code) { if (!CaptchaUtil.verify(code)) { throw new ApiException("验证码错误"); } // 登录失败次数限制 String key = "admin:login:fail:" + username; Integer failCount = RedisUtil.get(key); if (failCount != null && failCount >= 5) { throw new ApiException("账号已锁定，请30分钟后重试"); } } // 敏感操作需二次验证 public void checkAdminOperation(Long adminId) { if (!StpUtil.getExtra("secondAuth", false)) { throw new ApiException("请先完成二次验证"); } } }

5. 实战中的问题排查与优化

5.1 常见问题排查

问题1：账号类型混淆导致权限错误

现象：用户账号可以访问管理员接口排查步骤：

检查StpUtil.getExtra("accountType")返回值
确认拦截器中的URI匹配规则
验证登录时设置的extra参数

问题2：会话过期时间不生效

解决方案：

确认是否为对应账号类型设置了正确的StpLogic实例
检查是否有其他配置覆盖了超时设置
通过StpUtil.getTokenInfo()查看实际生效的配置

5.2 性能优化建议

缓存优化：为管理员和用户账号使用不同的缓存命名空间

// 管理员缓存前缀 adminStpLogic.setTokenName("admin-token") .setJwtSecret("different-secret-for-admin"); // 用户缓存前缀 userStpLogic.setTokenName("user-token") .setJwtSecret("different-secret-for-user");

批量操作：使用Sa-Token的批量API提升效率

// 批量获取多个管理员登录状态 List<Long> adminIds = Arrays.asList(1L, 2L, 3L); Map<Long, Boolean> loginStatus = StpUtil.checkLogin(adminIds);

6. 扩展功能实现

6.1 基于账号类型的权限注解

创建自定义权限注解：

@Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface SaCheckAccountType { String value(); }

实现注解处理器：

public class SaCheckAccountTypeInterceptor implements SaInterceptor { @Override public boolean preHandle(Object handler) { Method method = ((HandlerMethod) handler).getMethod(); SaCheckAccountType annotation = method.getAnnotation(SaCheckAccountType.class); if (annotation != null) { String requiredType = annotation.value(); String actualType = (String) StpUtil.getExtra("accountType"); if (!requiredType.equals(actualType)) { throw new NotPermissionException("账号类型不符"); } } return true; } }

使用示例：

@SaCheckAccountType("admin") @PostMapping("/admin/resetPassword") public Result resetPassword() { // 管理员专属方法 }

6.2 多设备登录管理

实现不同账号类型的设备管理：

public class DeviceService { // 获取管理员所有登录设备 public List<SaSession> getAdminDevices(Long adminId) { return StpUtil.searchSession( session -> AccountType.ADMIN.equals(session.get("accountType")) && adminId.equals(session.getLoginId()), 0, -1 ); } // 强制下线指定设备 public void kickoutDevice(String deviceId, String accountType) { StpUtil.kickoutByDevice(deviceId, accountType); } }

在实际项目中，我曾遇到一个典型场景：某电商系统需要支持商家管理员（Admin）和消费者用户（User）同时在线。通过Sa-Token的多账号认证体系，我们实现了：