多端登录不是功能，是账号策略

同一个账号，没人改密码，也没人申诉盗号，但用户就是反复掉线。 一查才发现，不是系统崩了，而是两个同类型设备在来回抢登录态。

我第一次接这个需求时，也以为就是配一个“是否允许并发登录”的开关。 但真放到项目里才发现，麻烦根本不在“能不能同时登录”，而在 你怎么定义设备边界、怎么处理互踢、怎么给前端一个能解释清楚的结果。

这篇文章，我就结合 Sa-Token 里的实现，把 同端互斥登录 这件事彻底拆开。

流程演示 Gif，https://img2024.cnblogs.com/blog/2105804/202603/2105804-20260324235519618-1893812181.gif

这类需求，为什么总在上线前冒出来

说实话，如果只是写 Demo，登录策略怎么搞都能跑。 但一旦到了真实生产环境，问题马上就来了。

最常见的几个场景是：

• • 后台账号被多人共用，运营、客服、测试拿着同一个账号四处登录。
• • 风控或审计要求更强，不希望同一类终端同时持有多个有效会话。
• • 用户体验要可控，允许手机和电脑同时在线，但不希望两个手机互相抢状态。
• • 运维排障要有边界，出了问题得知道到底是谁把谁顶下去了。

很多团队一开始会把需求理解成两种极端：

• • 要么全部允许多端并发。
• • 要么全部禁止多端并发。

但真实业务里，通常不是这么粗暴。 更常见的诉求是：不同端可以共存，同端只能保留一个在线会话。

这就是“同端互斥登录”的价值。

什么叫同端互斥，不要一上来就理解错

这个概念最容易误解的地方，其实是“互斥”两个字。

它不是说：

• • 一个账号任何时候只能登录一个地方。

它更像是说：

• • 同一种设备类型，只保留一个登录态。
• • 不同设备类型，可以同时在线。

如果你经常用腾讯 QQ，其实对这个体验不会陌生。 它可以手机和电脑同时在线，但一般不会允许你在两台手机上长期共用同一个账号。

💡 这背后不是单纯的技术限制，而是一种很典型的登录策略设计：

• • 既保留跨端使用体验。
• • 又控制同端会话泛滥。
• • 还能降低共享账号带来的管理成本。

在 Sa-Token 里，这件事怎么做

这套能力在 Sa-Token 里并不复杂。 核心思路就两步：

• • 把 isConcurrent 配置为 false。
• • 登录时显式声明当前设备类型。

先看最关键的一步。

指定设备类型登录

// 指定`账号id`和`设备类型`进行登录
StpUtil.login(10001, "PC");    

调用这段代码后，如果同一个账号已经在同设备登录过，那么旧会话会被顶下线。 注意，这里影响的是同设备类型，不同设备不受影响。

被顶下线的一方再次访问系统时，会抛出 NotLoginException 异常，场景值=-4。

如果你需要主动把某个设备类型踢下线，可以这样做：

指定设备类型强制注销

// 指定`账号id`和`设备类型`进行强制注销 
StpUtil.logout(10001, "PC");    

这里有个特别容易误伤的点。 如果第二个参数填写 null 或者不填，代表的是 把这个账号所有在线端全部强制注销。

这时，被踢出者再次访问系统时会抛出 NotLoginException 异常，场景值=-2。

另外两个接口在排查问题时也很有用：

查询当前登录的设备类型

// 返回当前token的登录设备类型
StpUtil.getLoginDevice();    

Id 反查 Token

// 获取指定loginId指定设备类型端的tokenValue 
StpUtil.getTokenValueByLoginId(10001, "APP");    

如果你只是为了跑通功能，到这里其实已经够了。 但如果你真打算把它放进生产，后面的细节才是最容易出事的地方。

我当时踩过的几个坑，挺真实的

1. 以为“关闭并发”就等于“全端互踢”

这是很多人第一眼的理解。 但 Sa-Token 这套设计，不是简单粗暴地把所有端都干掉，而是把“设备类型”这层维度交给你来定义。

也就是说，真正决定策略边界的，不只是 isConcurrent=false。 还包括你传进去的这个设备标识，到底是不是统一、稳定、可控。

如果你们项目里：

• • 有的入口传 "PC"。
• • 有的入口传 "WEB"。
• • 有的地方干脆不传，后面再补逻辑。

那最后的结果大概率就是：

• • 策略看起来配了。
• • 线上表现却不一致。
• • 排查的时候谁都说自己没问题。

⚠️ 这类问题最烦的地方，不是直接报错，而是它会表现成偶发性登录异常。

2. 前端只知道“掉线了”，但不知道为什么掉线

很多系统做完互斥登录后，前端收到未登录异常，就统一弹一句“登录已失效，请重新登录”。

这当然能跑。 但用户体验其实很差。

因为 -4 和 -2 的含义并不一样：

• • -4 更像是 同设备被新登录顶下线。
• • -2 更像是 被显式强制注销。

这两种情况，前端提示、日志记录、风控判断，最好别混在一起。 否则用户会觉得系统“莫名其妙掉登录”，而不是知道自己是被互斥策略顶掉了。

3. 需求说的是安全，最后做成了互相折磨

这个我在后台系统里见得挺多。

业务方一开始会说： “为了安全，账号不能多人同时登录。”

听起来很合理。 但如果这个账号本身就是共享账号，或者业务流程天然会在多个地点切换登录，那同端互斥做完之后，结果往往不是更安全，而是大家开始互相顶号。

所以这个策略真正适合的是：

• • 明确一人一号。
• • 设备边界清晰。
• • 需要审计登录来源。
• • 能接受后登录覆盖前登录。

如果这些前提不成立，你就要慎用。 不然它解决的不是安全问题，而是制造更多工单。

真要上生产，我更建议你补上这几件事

光把 API 调起来，只能算“功能完成”。 要让这套方案真正稳定，最好再补几层工程兜底。

👇 我自己的经验里，至少要补这 4 件事：

• • 统一设备类型枚举。不要让不同入口随便传设备标识，同一类终端一定要收口。
• • 把互斥登录当成策略，不只是开关。哪些端可以共存，哪些端必须互斥，最好在设计阶段就讲清楚。
• • 把异常场景翻译成可理解的提示。用户看到的不该只是“未登录”，而应该知道自己是“被顶下线”还是“被管理员强制注销”。
• • 保留必要的登录审计信息。至少要能知道是谁、在哪个设备类型上、什么时候触发了互斥替换。

这几件事写起来不复杂。 但少做任何一件，后面排查体验都会明显变差。

一个很容易被忽略的认知点

很多人会把“同端互斥登录”理解成认证框架里的一个小功能。 我现在更倾向于把它看成 账号体系治理的一部分。

因为它真正回答的是这几个问题：

• • 一个账号允许被几个人用。
• • 一个账号允许在哪些设备共存。
• • 当冲突发生时，谁留下，谁离开。
• • 被踢的人，系统要不要解释原因。

你会发现，这已经不只是登录代码了。 它背后连着的是：

• • 安全。
• • 体验。
• • 运维。
• • 审计。
• • 组织管理习惯。

所以我后来做这类需求，第一步已经不是先写代码了。 而是先把这几个边界跟业务说清楚。

代码只是在执行策略，真正难的是把策略定义对。

最后把核心 API 再串一下

如果你准备在项目里落地，可以先按这个顺序理解：

1. 1. 先把 isConcurrent 配置为 false。
2. 2. 登录时通过 StpUtil.login(10001, "PC"); 指定设备类型。
3. 3. 需要踢某个设备时，用 StpUtil.logout(10001, "PC");。
4. 4. 需要识别当前端类型时，用 StpUtil.getLoginDevice();。
5. 5. 需要按账号 + 设备找 token 时，用 StpUtil.getTokenValueByLoginId(10001, "APP");。

这套 API 本身不复杂。 真正拉开项目质量差距的，反而是你有没有把“设备类型”和“异常语义”这两层处理干净。

工程金句

登录并发不是一个布尔开关，它本质上是账号边界、设备边界和用户体验之间的平衡。

你们项目里，多端登录策略是怎么做的？

• • 是 全放开、全互斥，还是 按设备类型做策略？
• • 你们有没有踩过那种“用户以为系统掉线，其实是被别人顶号了”的坑？

相关文章推荐：

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

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