用户投诉账号异常登录，CTO 让我 5 分钟内解决

用户反馈："我的账号被人登了！" 运营催你："赶紧把那个违规用户踢掉！" 安全审计："检测到异常登录，需要立即强制下线！"

作为后端开发，会话管控能力是绑不开的刚需。

今天咱们就来聊聊 Sa-Token 框架里的「踢人下线」功能——只需一行代码，就能把指定用户"请"出去。

核心原理

踢人下线的本质非常简单：

找到目标用户的 Token → 让它失效。

就这么直接，没有弯弯绕绕。

踢下线

踢下线

Sa-Token 提供了 3 种不同的下线方式，适用于不同的业务场景。咱们一个个来看。

方式一：强制注销（logout）

这是最"干净"的方式，直接销毁用户的登录态。

StpUtil.logout();                    // 强制指定账号注销下线 

StpUtil.logout(, "PC");              // 强制指定账号指定端注销下线 

StpUtil.logoutByTokenValue("token");      // 强制指定 Token 注销下线

适用场景：

• • 用户主动申请注销账号
• • 后台管理员封禁某用户
• • 密码被修改后，强制旧会话失效

用户再次访问时，系统会提示：Token 无效。

方式二：踢人下线（kickout）

跟强制注销不同，踢人下线不会删除 Token，而是给它打上一个「被踢」的标记。

StpUtil.kickout();                    // 将指定账号踢下线

StpUtil.kickout(, "PC");              // 将指定账号指定端踢下线

StpUtil.kickoutByTokenValue("token");      // 将指定 Token 踢下线

适用场景：

• • 检测到异常登录行为，临时踢出
• • 需要让用户知道「你被踢了」而不是「Token 过期了」
• • 保留登录记录用于安全审计

用户再次访问时，系统会提示：Token 已被踢下线。

重点区分：强制注销 vs 踢人下线

一句话总结：logout 是"你没了"，kickout 是"你被请走了"。

方式三：顶人下线（replaced）

这是一个比较特殊的 API。

"顶人下线" 通常发生在登录时——当同一账号在新设备登录，框架自动把旧设备顶掉。

一般情况下，你不需要手动调用这个方法，框架会自动处理。

但如果你有特殊需求，也可以手动触发：

StpUtil.replaced();                    // 将指定账号顶下线 

StpUtil.replaced(, "PC");              // 将指定账号指定端顶下线

StpUtil.replacedByTokenValue("token");      // 将指定 Token 顶下线

适用场景：

• • 实现"单点登录"效果（同一账号只能一处在线）
• • 模拟"新设备登录，旧设备被挤下去"的行为

实战建议

根据我的项目经验，给你几点建议：

1. 1. 后台封禁用户 → 用 logout，彻底清理
2. 2. 检测到异地登录 → 用 kickout，保留痕迹便于排查
3. 3. 单设备登录限制 → 用 replaced，或者直接配置框架的并发登录策略

写在最后

会话管控看起来是个小功能，但在实际业务中却至关重要。

账号安全、运营管理、合规审计... 都离不开它。

Sa-Token 把这些能力封装成了简单的一行代码，拿来即用，这就是好框架的价值。

好的技术选型，能让复杂问题变得简单。

相关文章推荐：

• • 智谱 GLM-4.7 编程第一
• • LangChain4j 结构化输出实战
• • 让 AI 不再失忆
• • Claude Code 免费指南
• • Agent Skills，让 AI 像老员工一样靠谱

如果这篇文章帮到了你，不妨点个分享给同样需要的朋友吧！ 你的每一次支持，都是我持续创作的动力！💪