1. 为什么需要踢人下线功能在开发后台管理系统时我们经常会遇到这样的场景管理员发现某个账号存在异常操作需要立即终止该用户的会话或者用户密码泄露后需要强制所有已登录设备下线。这些场景都需要踢人下线功能来保障系统安全。传统做法是直接删除用户的Session或Token但这种方式存在几个问题分布式环境下Session同步困难Token过期时间不可控无法主动通知客户端会话已终止Sa-Token提供的踢人下线功能完美解决了这些问题。它通过一套精巧的设计实现了单点登录与踢出多端互斥登录强制下线指定用户实时会话监控2. Sa-Token踢人下线实现原理2.1 核心数据结构Sa-Token使用三个关键组件实现踢人功能Token签名机制每个Token包含用户ID、设备类型、登录时间等元数据会话记录中心Redis中存储活跃会话的Token签名踢出标记队列维护需要被踢出的Token列表// Token数据结构示例 { userId: 10001, device: PC, loginTime: 1659325687, sign: a1b2c3d4e5 }2.2 踢人流程详解当调用踢人API时Sa-Token会执行以下操作将该用户的Token签名加入踢出队列广播事件通知所有节点更新本地缓存客户端下次请求时网关层会校验Token是否在踢出队列中重要提示踢出操作是异步执行的通常有1-3秒延迟在金融等高安全场景需要特殊处理3. 完整实现步骤3.1 基础环境搭建首先引入Sa-Token依赖以Maven为例dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version1.45.0/version /dependency配置Redis连接application.ymlsa-token: jwt-secret-key: your-secret-key-here token-name: satoken timeout: 86400 is-share: true token-style: uuid is-read-body: false is-read-head: true is-read-cookie: false is-v: false is-log: false >// 使当前会话立即失效 StpUtil.logout();踢出指定用户// 将用户10001踢下线 StpUtil.kickout(10001); // 踢出并禁止再次登录封禁 StpUtil.disable(10001, 3600); // 封禁1小时查询登录状态// 检查用户是否在线 boolean isLogin StpUtil.isLogin(10001); // 获取所有登录的Token ListString tokenList StpUtil.searchTokenValue(10001, 0, 10);3.3 高级配置选项多端登录控制// 允许同一账号在3个设备同时登录 StpUtil.setMaxLoginCount(3); // 设置为只允许单设备登录 StpUtil.setMaxLoginCount(1);自定义踢出策略Configuration public class SaTokenConfig implements SaTokenListener { // 每次踢出操作触发 Override public void doKickout(String loginType, Object loginId, String tokenValue) { // 发送WebSocket通知 WebSocketServer.sendMessage(loginId, 您已被强制下线); // 记录操作日志 LogService.logSecurityEvent(loginId, FORCE_LOGOUT); } }4. 实战中的坑与解决方案4.1 分布式环境一致性问题现象集群环境下有时踢人操作不立即生效解决方案确保Redis配置正确且网络通畅调整广播模式在配置中启用Redis消息通知sa-token: is-concurrent: true is-share: true4.2 移动端特殊处理问题现象iOS应用在后台时可能不会立即感知被踢出解决方案实现心跳检测机制结合APNs发送推送通知// 在踢出时发送推送 if(deviceType.equals(IOS)) { PushService.sendApplePush(loginId, 您的账号已在其他设备登录); }4.3 性能优化建议当用户量较大时10万在线用户建议使用独立的Redis集群存储会话数据对searchTokenValue操作添加分页限制禁用不必要的监听器日志5. 扩展应用场景5.1 敏感操作二次验证在修改密码等关键操作前强制其他设备下线public void changePassword(String newPwd) { // 执行踢出 StpUtil.kickout(StpUtil.getLoginId()); // 更新密码 userService.updatePassword(newPwd); // 重新登录 StpUtil.login(StpUtil.getLoginId()); }5.2 会话监控看板利用Sa-Token的API构建管理界面GetMapping(/admin/sessions) public PageResultSessionVO getActiveSessions( RequestParam(defaultValue 1) int page, RequestParam(defaultValue 20) int size) { // 获取分页Token列表 ListString tokens StpUtil.searchTokenValue( null, (page-1)*size, size); // 转换为VO对象 ListSessionVO list tokens.stream() .map(token - { SessionVO vo new SessionVO(); vo.setToken(token); vo.setUserId(StpUtil.getLoginIdByToken(token)); vo.setLoginTime(StpUtil.getTokenSession(token).getCreateTime()); return vo; }).collect(Collectors.toList()); return PageResult.success(list, page, size); }6. 安全增强建议日志审计记录所有踢人操作SaCheckLogin PostMapping(/admin/kickout) public Result kickoutUser(RequestParam Long userId) { // 操作日志 adminLogService.log( StpUtil.getLoginId(), KICKOUT, 踢出用户: userId); // 执行踢出 StpUtil.kickout(userId); return Result.success(); }频率限制防止恶意踢人SaCheckRole(admin) PostMapping(/admin/kickout) SaCheckSafe(level 2, mode SaMode.REQUIRE) // 需要二级认证 public Result kickoutUser(RequestParam Long userId) { // 方法实现同上 }客户端处理前端收到踢出通知后的标准处理流程// 全局拦截器 axios.interceptors.response.use(response { return response; }, error { if(error.response.status 401 error.response.data.code 40101) { // 收到踢出通知 alert(您的账号已在其他地方登录); localStorage.clear(); router.push(/login); } return Promise.reject(error); });在实际项目中我们团队发现Sa-Token的踢人功能在以下场景特别有用当检测到异常登录地点时自动触发踢出员工离职后批量清理会话权限变更后强制重新认证一个实用的技巧是为关键账号设置禁止踢出标记// 对超级管理员账号添加保护 if(!StpUtil.getLoginId().equals(1L)) { StpUtil.kickout(loginId); }