1. 扫码登录解决的到底是什么问题1.1 用户不是记不住密码是不愿意在键盘上敲做过PC端登录改造的人大概都遇过这个场景用户在手机App里天天登录着一切到电脑前就得重新回忆那串大小写混合、带特殊符号、还要求不能和上次重复的密码。输错三次触发验证码验证码看不清再刷新刷新完发现密码又锁了。绝大多数找回密码工单本质上不是用户忘了密码而是用户压根不想在键盘上打密码。二维码扫描登录就是从这个痛点里长出来的方案把身份认证的动作从输入凭证迁移到已登录设备的一次确认。用户手机上本来就有一个已经完成认证的会话PC端只需要借用这个会话的信任就完成了登录。这个方案的价值不只是体验。从安全角度看扫码登录把密码输入这个高风险动作从PC端彻底移除了键盘记录器、钓鱼页面伪造表单这类攻击手法直接失效因为PC端从头到尾没有出现过任何密码。从产品角度看它把用户从账号密码体系推到设备账号体系为后面的多端同步、设备管理、安全风控都留了口子。这篇文章想讲清楚的就是这套机制背后的完整链路二维码里到底装了什么、服务端维护了一个什么样的状态机、手机端和PC端各自扮演什么角色、为什么主流实现都选择了相似的分工方式以及我在这类系统里踩过的那些坑。这篇文章适合三类人看。第一类是正在给自家产品做PC端登录改造的后端和前端工程师想知道轮询接口该怎么设计、状态枚举怎么定第二类是对身份认证体系感兴趣、想搞明白扫一下就这么登录了背后逻辑的技术爱好者第三类是做安全测试或者架构评审的同学关心这套流程有哪些可被利用的边界。我会按设计思路—核心机制—落地代码—安全边界—故障排查的顺序往下走中间会给出可以直接抄的参数表和代码骨架。1.2 一次扫码涉及三个角色、两条信道先把参与方摆清楚后面所有的设计选择都是围绕这三个角色之间的关系展开的。第一个角色是待登录设备通常是一台浏览器打开的PC页面。它的特点是显示能力好、输入能力差、本身没有任何已认证的会话。它是整个流程的发起方也是最终要拿到登录态的一方。第二个角色是已登录设备通常是用户手里那台装着App的手机。它的特点是已经持有有效的身份凭证、有摄像头、有生物识别或锁屏密码可以做二次确认。它是整个流程的授权方。第三个角色是认证服务端它夹在两者中间负责生成临时票据、维护会话状态、校验双方身份、最终签发正式令牌。它是唯一同时信任两端的角色也是整个流程可信性的根基。三个角色之间其实只走两条信道。一条是PC端与服务端之间的信道走的是浏览器环境能力受限但可控用来拉取二维码、轮询状态、最终换取令牌。另一条是手机端与服务端之间的信道走的是App内已经鉴权的接口用来上报扫描事件和确认事件。注意手机端和PC端之间没有任何直接通信所有的信息交换都必须经过服务端中转。这一点非常关键它保证了整个流程的可审计性——每一次状态跃迁都在服务端留下了记录任何异常都能被追溯。理解了这个三方两信道的结构后面所有的设计就有了依据为什么二维码要有有效期因为第一条信道是不可信环境票据暴露在公网上。为什么手机端要二次确认因为扫描动作本身不能等同于授权手机可能在包里被误触发。为什么PC端拿到的是令牌而不是用户密码因为认证服务端只应该下发最小权限的凭证。这些设计决策都不是拍脑袋定的而是从信道信任模型里推导出来的。1.3 和传统登录方式比它换掉了哪一环把扫码登录和账号密码登录摆在一起对比会看得更清楚。传统的账号密码登录本质是你知道什么something you know凭证是静态的、可被复制的、可被猜测的。短信验证码登录是你拥有什么something you have凭证动态但依赖运营商通道有延迟、有成本、有被拦截风险。而扫码登录严格来说不是一种新的认证因子它是把一次已有的强认证会话通过一次物理邻近性证明扩展到另一台设备上。这里的物理邻近性是它最微妙也最有价值的部分。用户能在手机上看到二维码并完成扫描这个动作隐含了一个前提这台手机和这台电脑在物理空间上足够接近接近到人可以同时操作两者。这个隐含前提在绝大多数正常场景下成立也正好构成了它的安全边界——如果一个攻击者拿到了二维码截图但人不在旁边他就无法完成手机上确认这一步。当然这个边界是有漏洞的后面第 4 章会展开讲。从工程实现看扫码登录还有一个隐性优势它天然支持多端会话管理。传统登录方式里服务端很难知道这个人现在登录了几台设备只能靠额外的设备指纹去猜。而扫码登录的每一次授权都是一条明确的服务端记录哪台设备、什么时间、通过哪台手机授权的全部清清楚楚。这对后续做异地登录提醒、设备下线、异常行为分析都是现成的数据基础。2. 流程拆解一次扫码背后的状态机2.1 二维码里装的不是账号是一个临时票据很多人第一反应会以为二维码里编码的是用户ID或者加密后的密码这个理解是错的。二维码里装的通常就是一个短生命周期的随机票据标识业界习惯叫 ticket、qrId 或者 sceneId。它的长度一般是 32 位左右的随机字符串字符集用 base62 或者十六进制目的是让熵足够大、无法被枚举同时让二维码的图形密度保持在手机摄像头容易识别的范围内。二维码承载的内容一般有两种形态。一种是纯标识型二维码里就是一串随机串手机端扫到之后直接把它当作参数去打服务端接口另一种是带地址型二维码里是一个完整的短链接形如{协议}://{域名}/qr/authorize?ticketxxxxxxxx手机端扫码后既可以用内置的扫码器解析也可以走链接跳转拉起指定的App。后者的好处是兼容性更好用户用系统相机扫也能识别能通过链接直接拉起App坏处是二维码内容变长图形变密对低端机摄像头的识别成功率不友好。我自己的选择是带地址但不带业务信息。二维码容量上限撑死也就不到 3KB没必要塞复杂内容把票据放在 query 参数里就够。业务信息、过期时间、签名这些全部由服务端在收到 ticket 之后去查客户端拿到的永远只是一个可以拿去问服务端的凭证。这样做的直接好处是票据可以被随时作废——服务端删掉这条记录二维码立刻就失效不需要考虑已经印出去的二维码怎么回收。票据本身的生成有几点要注意。第一必须用密码学安全的随机源别用时间戳或者普通的伪随机数前者可预测后者在种子泄露的情况下可推测。第二必须全局唯一且不可复用最好在存储层用唯一索引兜底避免并发下生成出重复票据。第三票据本身不携带任何用户信息哪怕被截获攻击者也只知道有这么一张票不知道票属于谁、会登录到哪个账号。这三条看起来是常识但我在代码评审里见过太多用System.currentTimeMillis()拼一个随机数就当作票据的实现。2.2 完整状态流转五个状态、四次跃迁扫码登录的核心就是一个状态机。这是整个系统里最值得画清楚的部分因为所有的接口设计、前端展示、异常处理都是从它推导出来的。一个典型的状态集合是这样状态值状态名触发方含义0WAITING服务端生成票据时二维码已下发等待被扫描1SCANNED手机端上报扫描已被某台手机扫到但用户尚未确认2CONFIRMED手机端上报确认用户已在手机上点了同意PC端可换取令牌3EXPIRED服务端定时/懒过期超过有效期票据作废4CANCELED手机端或PC端主动取消用户拒绝或被主动作废状态跃迁的路径只有四条WAITING → SCANNED、SCANNED → CONFIRMED、WAITING/SCANNED → EXPIRED、WAITING/SCANNED → CANCELED。已经到达 CONFIRMED 的票据绝对不能再回退这是防重放的第一道闸门。同样EXPIRED和CANCELED是终态任何针对终态票据的写操作都应该被拒绝并记录一条审计日志——这条日志在排查异常时非常有用它能告诉你有人在尝试用一个已经消费过的票据。这里有个容易忽略的细节SCANNED 状态不等于授权。很多早期实现图省事手机扫到就直接把状态置为 CONFIRMEDPC端立刻登录成功。这等于把扫码这个动作直接当成了同意用户掏出手机只是想看看二维码里是什么结果PC端啪一下登进去了。正确的做法是扫描归扫描、确认归确认中间必须有一次显式的用户操作而且这次操作要有足够强的意图表达——比如按钮上写清楚登录XXX账号而不是一个模糊的确定。在存储层面这个状态机最适合放进带 TTL 的键值存储里。key 用qr:ticket:{ticket}value 存一个精简结构包含状态、创建时间、扫描设备的标识、确认用户的ID、以及一个随机生成的 PC 侧密钥。TTL 建议设在 120 到 300 秒之间具体取值后面 3.1 会算。用 TTL 而不是定时任务扫过期好处是不需要维护一个额外的调度器坏处是过期是被动的——如果一张票在过期前一刻被确认了你得保证在消费它的接口里做一次时间校验别只依赖存储层的 TTL。2.3 为什么分工是PC轮询、手机确认而不是反过来这条分工看起来理所当然但背后的逻辑值得说清楚因为它解释了为什么这套方案在浏览器环境里能跑通。PC端之所以只能轮询是因为浏览器拿不到服务端的主动推送。严格来说浏览器有 WebSocket、有 SSE、有 Server-Sent Events但它们的兼容性和穿透性在企业内网、老旧浏览器、代理环境下都不够稳。而扫码登录这个场景的特点是低频、短时、用户在场——一个用户从打开登录页到扫码完成平均也就十几秒他不介意等。所以在实现复杂度和实时性之间绝大多数团队选择了实现更简单、兼容性更好的轮询。手机端之所以必须确认是因为它是唯一可信的角色。手机上有已认证的会话、有锁屏密码或生物识别作为最后一道门。让手机承担授权动作等于把这套系统里最敏感的决定权交给了一个本身已经受保护的设备。这个设计还有个副作用授权动作天然带有用户在场的证明。用户必须在手机上亲手点一下这一点的法律意义和审计意义都比系统自动完成要强得多。还有一层考虑是风险的隔离。PC端是一个不可信环境——可能有恶意插件、可能被投屏、可能被人旁观。所以PC端在确认完成之前拿到的信息应该尽可能少只知道还没被扫、被扫了但没确认、确认了可以拿了仅此而已。它不应该知道是哪个账号扫的不应该知道授权设备的型号更不应该知道用户的其他信息。信息越少被侧信道利用的空间就越小。这个原则在接口设计上体现得很直接轮询接口的返回体里账号信息只应该在 CONFIRMED 之后的换取令牌接口里出现而且是加密之后作为令牌下发的。3. 落地实现从生成票据到拿到登录态3.1 票据参数设计有效期到底该设多少参数取值不能拍脑袋得从用户行为和攻击窗口两头夹。先看用户行为一个正常的扫码流程用户看到二维码、掏出手机、解锁、打开App、点扫码、对准、识别、确认这个链路在熟练用户身上大约 8 到 15 秒在不熟练用户身上可能 30 到 60 秒。再加上可能出现的识别失败重扫、App 冷启动、网络抖动合理的上限应该在 2 分钟左右。再看攻击窗口票据的有效期越长一张被偷拍的二维码可被利用的时间就越长。假设有效期内攻击者有概率拿到这张图那有效期就是攻击窗口的长度。从这个角度越短越好。两头夹下来120 秒是一个比较平衡的取值比较激进的实现会用 60 秒保守一点的用 300 秒。我给的建议是分层默认 120 秒如果检测到异常同一 IP 段短时间内大量生成二维码、或者票据被扫描后长时间不确认则动态缩短到 60 秒。前端展示的倒计时应该比服务端 TTL 少 5 到 10 秒留一个缓冲避免用户看到还剩 1 秒去扫扫完发现接口返回过期。轮询频率也要算。假设前端每 2 秒轮询一次一个 120 秒的会话最多产生 60 次请求。这个数字本身不大但乘以并发量就很可观了。我按一个中等规模的场景算一下假设峰值每秒新增 2000 个登录会话平均每个会话持续 40 秒就被完成或放弃那稳态并发会话数是 2000 × 40 8 万轮询接口的 QPS 就是 8 万 / 2 4 万。这个量级对一个普通业务的后端来说已经不算轻松了如果每个请求还要查一次数据库基本就崩了。所以三个优化是必须做的第一状态查询走缓存不走数据库票据本身就该放在内存型存储里过期自动清理。第二在 WAITING 状态用低频轮询、在 SCANNED 状态切到高频因为用户扫完之后是最焦急的时候需要立刻给他反馈而扫之前他不着急。具体做法是前端在 WAITING 时 3 秒一次收到 SCANNED 后改成 1 秒一次。第三如果条件允许用长轮询替代短轮询服务端 hold 住请求最多 30 秒状态一变立刻返回这样 QPS 能从 4 万降到大约 13008 万 / 30 秒 × 长连接平均提前返回系数实际在 2000 到 3000 之间。这个数量级的差距在真实业务里就是要不要加机器的区别。3.2 三种获取结果的方式各有各的适用场景短轮询、长轮询、WebSocket 推送这三种方式在扫码登录里都有人用选型主要看你的基础设施和并发规模。短轮询是最容易实现的前端setInterval每 2 秒打一次状态查询接口服务端直接读缓存返回当前状态。优点是实现零成本、排查零成本、对网关和负载均衡完全透明。缺点是请求量大、有无用请求状态没变也照打、实时性有最多 2 秒的延迟。适合日活几万以内、或者内部系统这种量级。长轮询是短轮询的优化版请求打过来之后服务端不立刻返回而是挂起 20 到 30 秒期间如果状态发生跃迁就立即返回超时未变则返回一个空结果让前端重连。它的实现要点是必须用异步非阻塞的方式挂起请求千万别用Thread.sleep占着线程池的线程一个 200 线程的池子在长轮询下能撑住的并发连 2000 都不到。用 Servlet 3.0 的异步支持或者响应式框架的Mono/Flux才是正确姿势。另外要注意网关的超时配置必须大于长轮询的 hold 时间否则网关先断前端会收到一堆 504。WebSocket是实时性最好的二维码生成的时候就把连接建好服务端状态一变直接推。优点是零轮询、延迟最低、还能顺带做心跳检测用户是否还在页面上。缺点是连接要保持对连接数敏感而且需要网关支持协议升级某些企业代理环境下会被拦。还有一个隐性成本连接断开的检测和处理用户切到别的标签页、笔记本合盖、网络切换都会导致连接断开前端必须有重连逻辑而重连过程中可能错过一次状态推送所以还得保留一个兜底的查询接口。我个人的倾向是首次接入用短轮询量上来之后升级到长轮询WebSocket 只在连接数可控且已有基础设施的情况下才上。3.3 手机端确认与令牌签发一步都不能省手机端的动作拆成两步第一步是扫描上报第二步是用户确认。这两步都不能省而且第二步必须带用户身份。扫描上报接口的职责很轻接收 ticket校验票据存在且状态是 WAITING把状态改成 SCANNED记录扫描者的标识和扫描时间返回一个你正在登录 XXX 账号是否确认的提示页。注意这里返回的账号信息是给手机端自己看的不能透传给 PC 端。同时这个接口要带上频率限制防止有人写脚本批量扫描票据去做状态探测。确认接口的职责就重了它要校验当前用户是否有权授权这张票、票据是否还在有效期内、状态是否确实是 SCANNED、这张票是否已经被确认过。四个条件全过之后才把状态改成 CONFIRMED并写入授权用户 ID同时生成一个一次性的兑换码。PC 端拿到 CONFIRMED 状态后用 ticket 加上自己在生成时拿到的那个 PC 侧密钥去调换取令牌的接口服务端校验两者匹配才下发正式的访问令牌。这里的关键设计是两段式兑换。PC 端在生成二维码时除了拿到 ticket还会拿到一个只能自己知道的 secret存在内存或者 sessionStorage 里不放进二维码。确认之后PC 端必须同时提供 ticket 和 secret 才能换到令牌。这个设计防的是票据被偷看——就算攻击者通过某种方式看到了二维码里的 ticket他也没有 secret换不到令牌。代价是刷新页面之后 secret 丢了二维码得重新生成但这个代价可以接受。还有一个必须做的动作票据的一次性消费。换取令牌成功后立刻把这条票据记录标记为已消费或者直接删除。这样即使 ticket 和 secret 同时泄露也只能用一次。我给的做法是在换取接口里先做一次原子性的取并删操作比如 Redis 的GETDEL或者用 Lua 脚本保证读和删的原子性。别用先 GET 再 DELETE 两步中间有并发窗口。3.4 代码骨架服务端三个接口的最小实现下面这段是基于常见实践写的服务端骨架用 Java 表达重点看状态校验的顺序和原子性处理不要照抄框架细节。// 1. 生成二维码票据 PostMapping(/qr/generate) public QrGenerateResp generate() { String ticket RandomUtil.base62(32); // 密码学安全随机 String secret RandomUtil.base62(32); // PC 侧私有密钥 QrSession s new QrSession(); s.setTicket(ticket); s.setSecret(secret); s.setState(WAITING); s.setCreateAt(now()); // TTL 120 秒value 存整个会话对象 redis.opsForValue().set(qr:ticket: ticket, s, Duration.ofSeconds(120)); // 二维码内容只放 ticket不放 secret String content qrBaseUrl ?ticket ticket; return new QrGenerateResp(ticket, secret, content, 120); } // 2. PC 端轮询状态只返回状态不返回账号信息 GetMapping(/qr/state) public QrStateResp state(RequestParam String ticket) { QrSession s redis.opsForValue().get(qr:ticket: ticket); if (s null) return QrStateResp.expired(); return QrStateResp.of(s.getState()); // 0/1/2注意 no-store } // 3. 手机端扫描上报 PostMapping(/qr/scan) public void scan(RequestParam String ticket, CurrentUser Long uid) { String key qr:ticket: ticket; // 用 Lua 保证「检查状态 改状态」的原子性 Long ret redis.execute(SCAN_LUA, Arrays.asList(key), String.valueOf(uid)); if (ret 0) throw new BizException(二维码已失效); } // 4. 手机端确认授权 PostMapping(/qr/confirm) public void confirm(RequestParam String ticket, CurrentUser Long uid) { String key qr:ticket: ticket; Long ret redis.execute(CONFIRM_LUA, Arrays.asList(key), String.valueOf(uid)); if (ret 0) throw new BizException(二维码状态异常); } // 5. PC 端兑换令牌ticket secret 双因子一次性消费 PostMapping(/qr/exchange) public TokenResp exchange(RequestParam String ticket, RequestParam String secret) { String key qr:ticket: ticket; QrSession s redis.opsForValue().get(key); // 先读 if (s null || s.getState() ! CONFIRMED) throw new BizException(未授权); if (!s.getSecret().equals(secret)) throw new BizException(凭证不匹配); redis.delete(key); // 再删生产中应用 GETDEL return tokenService.issue(s.getAuthorizedUid()); // 签发正式令牌 }前端的轮询逻辑同样有讲究核心是别用固定间隔死轮要根据状态动态调整并且处理好页面隐藏时的暂停。let timer null; let interval 3000; async function poll(ticket) { const resp await fetch(/qr/state?ticket${ticket}, { cache: no-store }); const data await resp.json(); if (data.state 2) { // CONFIRMED clearInterval(timer); const tr await fetch(/qr/exchange, { method: POST, body: new URLSearchParams({ ticket, secret: localStorage.getItem(qr_secret) }) }); const token await tr.json(); location.href /home; // 令牌已写入 Cookie 或内存 return; } if (data.state 1 interval ! 1000) { // 已扫描提速 clearInterval(timer); interval 1000; timer setInterval(() poll(ticket), interval); } if (data.state 3 || data.state 4) { // 过期或取消 clearInterval(timer); showExpiredAndRefresh(); } } // 页面隐藏时暂停轮询避免用户切走后还在空转 document.addEventListener(visibilitychange, () { if (document.hidden) clearInterval(timer); else timer setInterval(() poll(ticket), interval); });这段代码里有两个点值得单独说。第一个是cache: no-store状态查询接口如果不加这个头某些浏览器或者中间的代理层会缓存 GET 响应导致前端拿到的永远是第一次的结果二维码看着一直不动。这个坑我踩过排查了半天才发现是 CDN 缓存了状态接口。第二个是visibilitychange的处理一个用户开了五个标签页每个都在轮询服务端压力直接翻五倍而这个用户可能只是在另一个标签页里干活。暂停轮询这个动作能省下相当一部分无效请求。4. 安全边界这套流程最容易被撬开的几个点4.1 二维码被截图转发怎么防这是扫码登录最经典的攻击场景行业内一般叫它扫码钓鱼。攻击者的手法很直接想办法拿到一张有效的登录二维码图片转发给受害者骗受害者扫一下并确认然后攻击者在自己那台设备上完成登录。整个过程中受害者的手机确实完成了授权服务端的所有校验都通过日志上看不出任何异常。这个攻击之所以成立是因为扫码登录隐含的物理邻近性假设被打破了。二维码被转发之后能扫到不再意味着在旁边。要防它单一的招数都不够得叠几层。第一层是确认页上的信息要足够吓人。手机端在显示确认按钮之前必须明确告诉用户你正在登录一台位于 XX 城市的 Windows 设备把设备类型、大致归属地、浏览器信息都亮出来。用户如果没在电脑前操作看到这条信息就会警觉。这一层不解决技术问题但它把攻击成本从骗人扫一下提高到了骗人扫一下并且无视明显的异常提示。第二层是压缩确认窗口。票据在 SCANNED 状态之后给一个很短的确认时限比如 60 秒超时自动转为 CANCELED。攻击者转发图片、等受害者扫码、再等受害者点确认这个链路很容易超过时限。正常用户扫完马上就点了不受影响。第三层是绑定生成端的环境指纹。生成二维码的时候服务端记录下请求的来源 IP 段、User-Agent 的关键特征。兑换令牌的时候做一次比对如果差异过大就要求额外的验证。这一层会有误伤用户换网络、换浏览器所以只能作为风控信号而不是硬拦截。第四层也是最有效的一层限制票据的可转移性。生成二维码时服务端下发一个 HttpOnly 的 Cookie 作为会话标识兑换令牌时必须带上这个 Cookie。攻击者转发的只是图片拿不到受害者的 Cookie所以就算受害者扫了并确认了攻击者那台设备也换不到令牌。这个做法牺牲了一点兼容性跨域、隐私模式会有问题但防钓鱼效果是实打实的。4.2 票据的生命周期管理比想象中更容易出事票据是这套系统的核心资产它的生命周期里有几个点特别容易出问题。生成环节的枚举风险。如果票据的随机性不够攻击者可以批量生成候选票据去探测状态一旦命中一个 CONFIRMED 的票据就能尝试兑换。防这个的办法很简单票据长度不低于 32 位、字符集不小于 62、使用密码学安全随机源。这样暴力枚举的空间是 62^32天文数字实际不可行。顺便说一句生成接口本身也要限流按 IP 和设备指纹做防止有人刷爆存储。存储环节的信息泄露。票据记录里会存授权用户 ID这个字段是敏感的。如果存储被未授权访问等于泄露了某张票对应某个用户。所以存储层的访问控制要做严别把缓存实例暴露在公网也别在日志里打印完整的票据对象。我见过有实现直接把整个会话对象序列化打进日志里面带着用户 ID 和手机号这个在合规审查里是硬伤。消费环节的重放风险。前面说过票据必须一次性消费但实际实现里经常出问题。常见错误有三个一是用先查后删的两步操作并发下两张请求都能查到都能兑换二是删除失败但没抛异常接口照样返回成功三是把消费标记写在了另一个存储里主存储的票据没删下次还能用。正确的做法是用原子操作Redis 的GETDEL或者 Lua 脚本一步搞定读和删失败就整个失败。过期环节的时钟问题。如果服务端是多实例部署各机器的时钟可能有偏差导致 A 机器认为票据没过期、B 机器认为过期了。这个问题的根源是把过期判断交给了本地时钟。解决办法是统一用存储层的 TTL 作为唯一权威业务代码里不要再自己做时间比较或者所有实例都对接同一个时间源。4.3 三类攻击面逐一对照把上面的分析收拢成一张表方便做架构评审的时候逐条对。攻击类型攻击路径主要防护手段残留风险二维码转发钓鱼截取图片转发给受害者诱导确认确认页展示设备信息、短确认窗口、绑定生成端 Cookie用户无视提示仍然确认票据枚举批量猜测 ticket 探测状态32 位以上随机票据、生成接口限流几乎为零票据重放复用已确认的票据换取令牌原子性一次性消费、ticket secret 双因子若 secret 同时泄露则失效中间人窃听在 PC 与服务端之间截获流量全链路 HTTPS、Cookie 加 Secure 与 SameSite客户端被植入根证书点击劫持用透明 iframe 覆盖二维码区域诱导点击二维码区域加 X-Frame-Options、用图片渲染老旧浏览器兼容问题扫码后信息泄露轮询接口返回过多账号信息状态接口只返回状态枚举账号信息只在兑换后下发实现疏忽表格里最后一列是我特意加的。安全方案没有完全防住这回事只有把攻击成本抬高到不划算。做架构评审的时候与其争论某个攻击能不能防住不如把残留风险明确写出来让业务方知道自己在承担什么。5. 实战踩坑与排查速查表5.1 六种典型故障对应的定位思路这套系统上线之后我遇到过的问题基本集中在状态不同步和请求打不通两类。整理成速查表遇到现象直接对。现象最可能的原因排查动作二维码刚出来就显示过期服务端 TTL 与前端倒计时不一致或前端倒计时用了本地时间对比接口返回的 expireIn 与前端展示值检查是否有客户端时钟偏移手机扫了PC 端毫无反应状态接口被缓存或状态枚举前后端不一致看响应头有没有 Cache-Control抓包比对返回的 state 值PC 卡在已扫描不动手机端确认接口失败或确认后没写回存储查手机端网络请求查服务端确认接口的错误日志兑换令牌报凭证不匹配secret 丢失刷新页面、开了新标签或跨域导致 Cookie 没带上检查 secret 的存储位置检查跨域配置和 SameSite多标签页互相踢下线同一 ticket 被多个页面并发兑换一次性消费只成功一个让每个标签页独立生成二维码或做页面间广播高峰期状态接口大面积超时轮询 QPS 打满或长轮询占满了线程池看接口 QPS 曲线与线程池活跃数检查是否误用了阻塞式挂起表格里第二条特别值得展开。状态接口被缓存这个问题我第一次遇到的时候完全没往缓存上想因为本地开发环境一切正常一上生产就不行。后来发现是前置的代理层对 GET 请求做了默认缓存而我们的接口又没显式声明不可缓存。修复很简单响应头加上Cache-Control: no-store, no-cache, must-revalidate同时把状态查询改成 POST虽然不符合 REST 风格但能绕开绝大多数中间层的 GET 缓存策略。这个坑的教训是任何返回实时状态的接口都必须显式声明不可缓存别指望中间层猜你的意图。第三条也常见。手机端确认成功之后服务端要写回状态这个写回如果失败了存储抖动、超时PC 端就永远等不到。我的做法是在确认接口里做重试并且把确认成功但写回失败这个情况单独打一条告警日志。另外前端要有兜底超过 30 秒还停在 SCANNED就提示用户如果已确认请刷新重试并给一个手动刷新的按钮。别让用户对着一个不动的界面干等。5.2 轮询风暴的治理从三个角度下手轮询风暴是这类系统最常见的性能问题尤其在早晚高峰。治理思路分三层。第一层是减少请求数量。前面提到的页面隐藏暂停、WAITING 低频 SCANNED 高频这两个改动能砍掉一大半无效请求。还有一个容易被忽略的点二维码过期之后前端必须停止轮询。我见过有实现过期了还在每秒打一次接口用户把登录页开着去吃饭回来发现后台打了几千次请求。加一个过期判断clearInterval一下的事。第二层是降低单次请求的成本。状态查询接口里不能有任何数据库操作、不能有复杂的序列化、不能打业务日志。理想情况下它就是一次内存读取加一次枚举返回响应时间在 1 毫秒以内。如果状态数据量小甚至可以把整个会话对象缓存在本地内存里做二级缓存只在状态跃迁时才同步。注意二级缓存会带来一致性问题得用发布订阅或者短 TTL 来兜。第三层是横向削峰。如果前面两层做完 QPS 还是高那就上长轮询把轮询次数换成连接数。长轮询的关键是异步挂起用 Servlet 的AsyncContext或者响应式框架一个线程能挂几千个请求。同时要注意网关的空闲超时和负载均衡的连接数上限这两个地方经常成为新的瓶颈。还有一个细节长轮询的连接在网关侧断开时服务端要能感知到并释放资源否则会积压一堆僵尸连接。最后分享一个我在实际项目里用的小技巧。给状态查询接口加一个版本号参数前端每次带上自己已知的状态版本服务端如果发现版本没变直接返回 304 或者一个极简的未变化响应连 JSON 序列化都省了。这个改动在请求量大的时候能省下可观的 CPU实现成本也就十几行代码。当然前提是前端要正确处理这个响应别把它当成错误。5.3 一些不太好归类但很实用的经验关于二维码的渲染。别用前端 canvas 现画用服务端生成图片返回。原因有三个一是尺寸和纠错等级可控低端机识别率高二是可以防止二维码被覆盖这类点击劫持三是缓存友好。纠错等级建议用 M 级太高会让图形变密反而降低识别率。图片尺寸别低于 200×200太小了手机对焦困难。关于多端登录的冲突。用户可能同时开着手机App和PC网页扫码登录之后两边的会话是什么关系我的建议是两套会话独立维护PC端的令牌和手机端的令牌互不干扰但都归属于同一个用户。这样任何一端退出不会影响另一端符合用户预期。如果业务上要求一端登录挤掉另一端那要在签发令牌的时候做全局的单点控制这个逻辑最好放在统一的会话服务里别散落在各个业务模块。关于测试环境的坑。本地开发的时候手机和电脑通常在同一个局域网二维码里如果写的是localhost手机根本扫不开。常见的做法是把二维码内容改成局域网 IP但这会带来跨域和 Cookie 域名的问题。我一般会在开发环境加一个开关把二维码内容指向一个固定的测试域名然后在 hosts 里做映射。另外测试环境的 HTTPS 证书往往是自签的手机端会拦得提前把证书装好否则调试半天以为是代码问题。关于灰度发布。这套流程涉及前后端和移动端三方任何一方先上线都可能出问题。比较稳的顺序是先上服务端新老接口并存再上PC端走新的生成和轮询接口但兑换接口保留旧逻辑的兼容分支最后上移动端新版本才支持扫码确认。整个过程要保留一个强制走老流程的降级开关出问题能一键切回。我在一个项目里就是因为移动端灰度没控制好一批旧版本用户扫了新二维码但客户端不认识直接白屏回滚花了半小时。关于监控指标。至少要有这么几个二维码生成量、扫码成功率SCANNED / 生成量、确认成功率CONFIRMED / SCANNED、端到端耗时分布、状态接口的 P99 延迟、过期率。这几个指标能覆盖绝大多数异常生成量突增说明有人刷接口扫码成功率骤降说明二维码识别出了问题确认成功率掉说明确认接口有故障端到端耗时变长说明某一环卡住了。我当时就是靠确认成功率掉了 15 个点这条告警提前发现了一个存储集群的写入抖动。6. 这套机制还能怎么用扫码登录本质上是用一台已认证设备授权另一台设备的通用模式把它抽象出来能复用的场景其实不少。最常见的是扫码支付确认逻辑几乎一样只是最后一步不是签发登录令牌而是发起一笔交易安全要求更高通常还要加支付密码或者生物识别。另一类是扫码加好友、扫码进群这个是扫码后的业务动作不同状态机可以简化成扫到即执行不需要二次确认。还有一类是设备配网智能硬件扫二维码把自己的标识上报服务端把设备和账号绑定本质上是把设备当成了那个待登录的PC端。还有一个稍微冷门但很有用的场景扫码完成跨端的数据同步。比如用户在手机上编辑了一半的文档想在电脑上接着写扫个码把编辑会话搬过去。这个场景里二维码承载的不是登录凭证而是一个会话的交接票据服务端要保证交接过程中数据的一致性比登录要复杂一些。我在实际做这套东西的过程中最深的一点体会是扫码登录的复杂度不在二维码本身而在状态机的一致性上。二维码的生成和渲染都是成熟方案随便找个库就能用真正花时间的是状态在什么时机变、由谁来变、变了之后怎么保证两端都能看到。很多线上问题的根因都是某个状态跃迁没有被正确持久化或者两端对同一个状态的理解不一致。所以如果你的团队要接这套东西我建议把三分之一的时间花在把状态机画清楚、把每个状态的入口和出口都列出来、把异常情况下应该落到哪个状态定死剩下的时间再动手写代码。这个顺序反了后面排查问题的成本会翻好几倍。
1. 扫码登录解决的到底是什么问题1.1 用户不是记不住密码是不愿意在键盘上敲做过PC端登录改造的人大概都遇过这个场景用户在手机App里天天登录着一切到电脑前就得重新回忆那串大小写混合、带特殊符号、还要求不能和上次重复的密码。输错三次触发验证码验证码看不清再刷新刷新完发现密码又锁了。绝大多数找回密码工单本质上不是用户忘了密码而是用户压根不想在键盘上打密码。二维码扫描登录就是从这个痛点里长出来的方案把身份认证的动作从输入凭证迁移到已登录设备的一次确认。用户手机上本来就有一个已经完成认证的会话PC端只需要借用这个会话的信任就完成了登录。这个方案的价值不只是体验。从安全角度看扫码登录把密码输入这个高风险动作从PC端彻底移除了键盘记录器、钓鱼页面伪造表单这类攻击手法直接失效因为PC端从头到尾没有出现过任何密码。从产品角度看它把用户从账号密码体系推到设备账号体系为后面的多端同步、设备管理、安全风控都留了口子。这篇文章想讲清楚的就是这套机制背后的完整链路二维码里到底装了什么、服务端维护了一个什么样的状态机、手机端和PC端各自扮演什么角色、为什么主流实现都选择了相似的分工方式以及我在这类系统里踩过的那些坑。这篇文章适合三类人看。第一类是正在给自家产品做PC端登录改造的后端和前端工程师想知道轮询接口该怎么设计、状态枚举怎么定第二类是对身份认证体系感兴趣、想搞明白扫一下就这么登录了背后逻辑的技术爱好者第三类是做安全测试或者架构评审的同学关心这套流程有哪些可被利用的边界。我会按设计思路—核心机制—落地代码—安全边界—故障排查的顺序往下走中间会给出可以直接抄的参数表和代码骨架。1.2 一次扫码涉及三个角色、两条信道先把参与方摆清楚后面所有的设计选择都是围绕这三个角色之间的关系展开的。第一个角色是待登录设备通常是一台浏览器打开的PC页面。它的特点是显示能力好、输入能力差、本身没有任何已认证的会话。它是整个流程的发起方也是最终要拿到登录态的一方。第二个角色是已登录设备通常是用户手里那台装着App的手机。它的特点是已经持有有效的身份凭证、有摄像头、有生物识别或锁屏密码可以做二次确认。它是整个流程的授权方。第三个角色是认证服务端它夹在两者中间负责生成临时票据、维护会话状态、校验双方身份、最终签发正式令牌。它是唯一同时信任两端的角色也是整个流程可信性的根基。三个角色之间其实只走两条信道。一条是PC端与服务端之间的信道走的是浏览器环境能力受限但可控用来拉取二维码、轮询状态、最终换取令牌。另一条是手机端与服务端之间的信道走的是App内已经鉴权的接口用来上报扫描事件和确认事件。注意手机端和PC端之间没有任何直接通信所有的信息交换都必须经过服务端中转。这一点非常关键它保证了整个流程的可审计性——每一次状态跃迁都在服务端留下了记录任何异常都能被追溯。理解了这个三方两信道的结构后面所有的设计就有了依据为什么二维码要有有效期因为第一条信道是不可信环境票据暴露在公网上。为什么手机端要二次确认因为扫描动作本身不能等同于授权手机可能在包里被误触发。为什么PC端拿到的是令牌而不是用户密码因为认证服务端只应该下发最小权限的凭证。这些设计决策都不是拍脑袋定的而是从信道信任模型里推导出来的。1.3 和传统登录方式比它换掉了哪一环把扫码登录和账号密码登录摆在一起对比会看得更清楚。传统的账号密码登录本质是你知道什么something you know凭证是静态的、可被复制的、可被猜测的。短信验证码登录是你拥有什么something you have凭证动态但依赖运营商通道有延迟、有成本、有被拦截风险。而扫码登录严格来说不是一种新的认证因子它是把一次已有的强认证会话通过一次物理邻近性证明扩展到另一台设备上。这里的物理邻近性是它最微妙也最有价值的部分。用户能在手机上看到二维码并完成扫描这个动作隐含了一个前提这台手机和这台电脑在物理空间上足够接近接近到人可以同时操作两者。这个隐含前提在绝大多数正常场景下成立也正好构成了它的安全边界——如果一个攻击者拿到了二维码截图但人不在旁边他就无法完成手机上确认这一步。当然这个边界是有漏洞的后面第 4 章会展开讲。从工程实现看扫码登录还有一个隐性优势它天然支持多端会话管理。传统登录方式里服务端很难知道这个人现在登录了几台设备只能靠额外的设备指纹去猜。而扫码登录的每一次授权都是一条明确的服务端记录哪台设备、什么时间、通过哪台手机授权的全部清清楚楚。这对后续做异地登录提醒、设备下线、异常行为分析都是现成的数据基础。2. 流程拆解一次扫码背后的状态机2.1 二维码里装的不是账号是一个临时票据很多人第一反应会以为二维码里编码的是用户ID或者加密后的密码这个理解是错的。二维码里装的通常就是一个短生命周期的随机票据标识业界习惯叫 ticket、qrId 或者 sceneId。它的长度一般是 32 位左右的随机字符串字符集用 base62 或者十六进制目的是让熵足够大、无法被枚举同时让二维码的图形密度保持在手机摄像头容易识别的范围内。二维码承载的内容一般有两种形态。一种是纯标识型二维码里就是一串随机串手机端扫到之后直接把它当作参数去打服务端接口另一种是带地址型二维码里是一个完整的短链接形如{协议}://{域名}/qr/authorize?ticketxxxxxxxx手机端扫码后既可以用内置的扫码器解析也可以走链接跳转拉起指定的App。后者的好处是兼容性更好用户用系统相机扫也能识别能通过链接直接拉起App坏处是二维码内容变长图形变密对低端机摄像头的识别成功率不友好。我自己的选择是带地址但不带业务信息。二维码容量上限撑死也就不到 3KB没必要塞复杂内容把票据放在 query 参数里就够。业务信息、过期时间、签名这些全部由服务端在收到 ticket 之后去查客户端拿到的永远只是一个可以拿去问服务端的凭证。这样做的直接好处是票据可以被随时作废——服务端删掉这条记录二维码立刻就失效不需要考虑已经印出去的二维码怎么回收。票据本身的生成有几点要注意。第一必须用密码学安全的随机源别用时间戳或者普通的伪随机数前者可预测后者在种子泄露的情况下可推测。第二必须全局唯一且不可复用最好在存储层用唯一索引兜底避免并发下生成出重复票据。第三票据本身不携带任何用户信息哪怕被截获攻击者也只知道有这么一张票不知道票属于谁、会登录到哪个账号。这三条看起来是常识但我在代码评审里见过太多用System.currentTimeMillis()拼一个随机数就当作票据的实现。2.2 完整状态流转五个状态、四次跃迁扫码登录的核心就是一个状态机。这是整个系统里最值得画清楚的部分因为所有的接口设计、前端展示、异常处理都是从它推导出来的。一个典型的状态集合是这样状态值状态名触发方含义0WAITING服务端生成票据时二维码已下发等待被扫描1SCANNED手机端上报扫描已被某台手机扫到但用户尚未确认2CONFIRMED手机端上报确认用户已在手机上点了同意PC端可换取令牌3EXPIRED服务端定时/懒过期超过有效期票据作废4CANCELED手机端或PC端主动取消用户拒绝或被主动作废状态跃迁的路径只有四条WAITING → SCANNED、SCANNED → CONFIRMED、WAITING/SCANNED → EXPIRED、WAITING/SCANNED → CANCELED。已经到达 CONFIRMED 的票据绝对不能再回退这是防重放的第一道闸门。同样EXPIRED和CANCELED是终态任何针对终态票据的写操作都应该被拒绝并记录一条审计日志——这条日志在排查异常时非常有用它能告诉你有人在尝试用一个已经消费过的票据。这里有个容易忽略的细节SCANNED 状态不等于授权。很多早期实现图省事手机扫到就直接把状态置为 CONFIRMEDPC端立刻登录成功。这等于把扫码这个动作直接当成了同意用户掏出手机只是想看看二维码里是什么结果PC端啪一下登进去了。正确的做法是扫描归扫描、确认归确认中间必须有一次显式的用户操作而且这次操作要有足够强的意图表达——比如按钮上写清楚登录XXX账号而不是一个模糊的确定。在存储层面这个状态机最适合放进带 TTL 的键值存储里。key 用qr:ticket:{ticket}value 存一个精简结构包含状态、创建时间、扫描设备的标识、确认用户的ID、以及一个随机生成的 PC 侧密钥。TTL 建议设在 120 到 300 秒之间具体取值后面 3.1 会算。用 TTL 而不是定时任务扫过期好处是不需要维护一个额外的调度器坏处是过期是被动的——如果一张票在过期前一刻被确认了你得保证在消费它的接口里做一次时间校验别只依赖存储层的 TTL。2.3 为什么分工是PC轮询、手机确认而不是反过来这条分工看起来理所当然但背后的逻辑值得说清楚因为它解释了为什么这套方案在浏览器环境里能跑通。PC端之所以只能轮询是因为浏览器拿不到服务端的主动推送。严格来说浏览器有 WebSocket、有 SSE、有 Server-Sent Events但它们的兼容性和穿透性在企业内网、老旧浏览器、代理环境下都不够稳。而扫码登录这个场景的特点是低频、短时、用户在场——一个用户从打开登录页到扫码完成平均也就十几秒他不介意等。所以在实现复杂度和实时性之间绝大多数团队选择了实现更简单、兼容性更好的轮询。手机端之所以必须确认是因为它是唯一可信的角色。手机上有已认证的会话、有锁屏密码或生物识别作为最后一道门。让手机承担授权动作等于把这套系统里最敏感的决定权交给了一个本身已经受保护的设备。这个设计还有个副作用授权动作天然带有用户在场的证明。用户必须在手机上亲手点一下这一点的法律意义和审计意义都比系统自动完成要强得多。还有一层考虑是风险的隔离。PC端是一个不可信环境——可能有恶意插件、可能被投屏、可能被人旁观。所以PC端在确认完成之前拿到的信息应该尽可能少只知道还没被扫、被扫了但没确认、确认了可以拿了仅此而已。它不应该知道是哪个账号扫的不应该知道授权设备的型号更不应该知道用户的其他信息。信息越少被侧信道利用的空间就越小。这个原则在接口设计上体现得很直接轮询接口的返回体里账号信息只应该在 CONFIRMED 之后的换取令牌接口里出现而且是加密之后作为令牌下发的。3. 落地实现从生成票据到拿到登录态3.1 票据参数设计有效期到底该设多少参数取值不能拍脑袋得从用户行为和攻击窗口两头夹。先看用户行为一个正常的扫码流程用户看到二维码、掏出手机、解锁、打开App、点扫码、对准、识别、确认这个链路在熟练用户身上大约 8 到 15 秒在不熟练用户身上可能 30 到 60 秒。再加上可能出现的识别失败重扫、App 冷启动、网络抖动合理的上限应该在 2 分钟左右。再看攻击窗口票据的有效期越长一张被偷拍的二维码可被利用的时间就越长。假设有效期内攻击者有概率拿到这张图那有效期就是攻击窗口的长度。从这个角度越短越好。两头夹下来120 秒是一个比较平衡的取值比较激进的实现会用 60 秒保守一点的用 300 秒。我给的建议是分层默认 120 秒如果检测到异常同一 IP 段短时间内大量生成二维码、或者票据被扫描后长时间不确认则动态缩短到 60 秒。前端展示的倒计时应该比服务端 TTL 少 5 到 10 秒留一个缓冲避免用户看到还剩 1 秒去扫扫完发现接口返回过期。轮询频率也要算。假设前端每 2 秒轮询一次一个 120 秒的会话最多产生 60 次请求。这个数字本身不大但乘以并发量就很可观了。我按一个中等规模的场景算一下假设峰值每秒新增 2000 个登录会话平均每个会话持续 40 秒就被完成或放弃那稳态并发会话数是 2000 × 40 8 万轮询接口的 QPS 就是 8 万 / 2 4 万。这个量级对一个普通业务的后端来说已经不算轻松了如果每个请求还要查一次数据库基本就崩了。所以三个优化是必须做的第一状态查询走缓存不走数据库票据本身就该放在内存型存储里过期自动清理。第二在 WAITING 状态用低频轮询、在 SCANNED 状态切到高频因为用户扫完之后是最焦急的时候需要立刻给他反馈而扫之前他不着急。具体做法是前端在 WAITING 时 3 秒一次收到 SCANNED 后改成 1 秒一次。第三如果条件允许用长轮询替代短轮询服务端 hold 住请求最多 30 秒状态一变立刻返回这样 QPS 能从 4 万降到大约 13008 万 / 30 秒 × 长连接平均提前返回系数实际在 2000 到 3000 之间。这个数量级的差距在真实业务里就是要不要加机器的区别。3.2 三种获取结果的方式各有各的适用场景短轮询、长轮询、WebSocket 推送这三种方式在扫码登录里都有人用选型主要看你的基础设施和并发规模。短轮询是最容易实现的前端setInterval每 2 秒打一次状态查询接口服务端直接读缓存返回当前状态。优点是实现零成本、排查零成本、对网关和负载均衡完全透明。缺点是请求量大、有无用请求状态没变也照打、实时性有最多 2 秒的延迟。适合日活几万以内、或者内部系统这种量级。长轮询是短轮询的优化版请求打过来之后服务端不立刻返回而是挂起 20 到 30 秒期间如果状态发生跃迁就立即返回超时未变则返回一个空结果让前端重连。它的实现要点是必须用异步非阻塞的方式挂起请求千万别用Thread.sleep占着线程池的线程一个 200 线程的池子在长轮询下能撑住的并发连 2000 都不到。用 Servlet 3.0 的异步支持或者响应式框架的Mono/Flux才是正确姿势。另外要注意网关的超时配置必须大于长轮询的 hold 时间否则网关先断前端会收到一堆 504。WebSocket是实时性最好的二维码生成的时候就把连接建好服务端状态一变直接推。优点是零轮询、延迟最低、还能顺带做心跳检测用户是否还在页面上。缺点是连接要保持对连接数敏感而且需要网关支持协议升级某些企业代理环境下会被拦。还有一个隐性成本连接断开的检测和处理用户切到别的标签页、笔记本合盖、网络切换都会导致连接断开前端必须有重连逻辑而重连过程中可能错过一次状态推送所以还得保留一个兜底的查询接口。我个人的倾向是首次接入用短轮询量上来之后升级到长轮询WebSocket 只在连接数可控且已有基础设施的情况下才上。3.3 手机端确认与令牌签发一步都不能省手机端的动作拆成两步第一步是扫描上报第二步是用户确认。这两步都不能省而且第二步必须带用户身份。扫描上报接口的职责很轻接收 ticket校验票据存在且状态是 WAITING把状态改成 SCANNED记录扫描者的标识和扫描时间返回一个你正在登录 XXX 账号是否确认的提示页。注意这里返回的账号信息是给手机端自己看的不能透传给 PC 端。同时这个接口要带上频率限制防止有人写脚本批量扫描票据去做状态探测。确认接口的职责就重了它要校验当前用户是否有权授权这张票、票据是否还在有效期内、状态是否确实是 SCANNED、这张票是否已经被确认过。四个条件全过之后才把状态改成 CONFIRMED并写入授权用户 ID同时生成一个一次性的兑换码。PC 端拿到 CONFIRMED 状态后用 ticket 加上自己在生成时拿到的那个 PC 侧密钥去调换取令牌的接口服务端校验两者匹配才下发正式的访问令牌。这里的关键设计是两段式兑换。PC 端在生成二维码时除了拿到 ticket还会拿到一个只能自己知道的 secret存在内存或者 sessionStorage 里不放进二维码。确认之后PC 端必须同时提供 ticket 和 secret 才能换到令牌。这个设计防的是票据被偷看——就算攻击者通过某种方式看到了二维码里的 ticket他也没有 secret换不到令牌。代价是刷新页面之后 secret 丢了二维码得重新生成但这个代价可以接受。还有一个必须做的动作票据的一次性消费。换取令牌成功后立刻把这条票据记录标记为已消费或者直接删除。这样即使 ticket 和 secret 同时泄露也只能用一次。我给的做法是在换取接口里先做一次原子性的取并删操作比如 Redis 的GETDEL或者用 Lua 脚本保证读和删的原子性。别用先 GET 再 DELETE 两步中间有并发窗口。3.4 代码骨架服务端三个接口的最小实现下面这段是基于常见实践写的服务端骨架用 Java 表达重点看状态校验的顺序和原子性处理不要照抄框架细节。// 1. 生成二维码票据 PostMapping(/qr/generate) public QrGenerateResp generate() { String ticket RandomUtil.base62(32); // 密码学安全随机 String secret RandomUtil.base62(32); // PC 侧私有密钥 QrSession s new QrSession(); s.setTicket(ticket); s.setSecret(secret); s.setState(WAITING); s.setCreateAt(now()); // TTL 120 秒value 存整个会话对象 redis.opsForValue().set(qr:ticket: ticket, s, Duration.ofSeconds(120)); // 二维码内容只放 ticket不放 secret String content qrBaseUrl ?ticket ticket; return new QrGenerateResp(ticket, secret, content, 120); } // 2. PC 端轮询状态只返回状态不返回账号信息 GetMapping(/qr/state) public QrStateResp state(RequestParam String ticket) { QrSession s redis.opsForValue().get(qr:ticket: ticket); if (s null) return QrStateResp.expired(); return QrStateResp.of(s.getState()); // 0/1/2注意 no-store } // 3. 手机端扫描上报 PostMapping(/qr/scan) public void scan(RequestParam String ticket, CurrentUser Long uid) { String key qr:ticket: ticket; // 用 Lua 保证「检查状态 改状态」的原子性 Long ret redis.execute(SCAN_LUA, Arrays.asList(key), String.valueOf(uid)); if (ret 0) throw new BizException(二维码已失效); } // 4. 手机端确认授权 PostMapping(/qr/confirm) public void confirm(RequestParam String ticket, CurrentUser Long uid) { String key qr:ticket: ticket; Long ret redis.execute(CONFIRM_LUA, Arrays.asList(key), String.valueOf(uid)); if (ret 0) throw new BizException(二维码状态异常); } // 5. PC 端兑换令牌ticket secret 双因子一次性消费 PostMapping(/qr/exchange) public TokenResp exchange(RequestParam String ticket, RequestParam String secret) { String key qr:ticket: ticket; QrSession s redis.opsForValue().get(key); // 先读 if (s null || s.getState() ! CONFIRMED) throw new BizException(未授权); if (!s.getSecret().equals(secret)) throw new BizException(凭证不匹配); redis.delete(key); // 再删生产中应用 GETDEL return tokenService.issue(s.getAuthorizedUid()); // 签发正式令牌 }前端的轮询逻辑同样有讲究核心是别用固定间隔死轮要根据状态动态调整并且处理好页面隐藏时的暂停。let timer null; let interval 3000; async function poll(ticket) { const resp await fetch(/qr/state?ticket${ticket}, { cache: no-store }); const data await resp.json(); if (data.state 2) { // CONFIRMED clearInterval(timer); const tr await fetch(/qr/exchange, { method: POST, body: new URLSearchParams({ ticket, secret: localStorage.getItem(qr_secret) }) }); const token await tr.json(); location.href /home; // 令牌已写入 Cookie 或内存 return; } if (data.state 1 interval ! 1000) { // 已扫描提速 clearInterval(timer); interval 1000; timer setInterval(() poll(ticket), interval); } if (data.state 3 || data.state 4) { // 过期或取消 clearInterval(timer); showExpiredAndRefresh(); } } // 页面隐藏时暂停轮询避免用户切走后还在空转 document.addEventListener(visibilitychange, () { if (document.hidden) clearInterval(timer); else timer setInterval(() poll(ticket), interval); });这段代码里有两个点值得单独说。第一个是cache: no-store状态查询接口如果不加这个头某些浏览器或者中间的代理层会缓存 GET 响应导致前端拿到的永远是第一次的结果二维码看着一直不动。这个坑我踩过排查了半天才发现是 CDN 缓存了状态接口。第二个是visibilitychange的处理一个用户开了五个标签页每个都在轮询服务端压力直接翻五倍而这个用户可能只是在另一个标签页里干活。暂停轮询这个动作能省下相当一部分无效请求。4. 安全边界这套流程最容易被撬开的几个点4.1 二维码被截图转发怎么防这是扫码登录最经典的攻击场景行业内一般叫它扫码钓鱼。攻击者的手法很直接想办法拿到一张有效的登录二维码图片转发给受害者骗受害者扫一下并确认然后攻击者在自己那台设备上完成登录。整个过程中受害者的手机确实完成了授权服务端的所有校验都通过日志上看不出任何异常。这个攻击之所以成立是因为扫码登录隐含的物理邻近性假设被打破了。二维码被转发之后能扫到不再意味着在旁边。要防它单一的招数都不够得叠几层。第一层是确认页上的信息要足够吓人。手机端在显示确认按钮之前必须明确告诉用户你正在登录一台位于 XX 城市的 Windows 设备把设备类型、大致归属地、浏览器信息都亮出来。用户如果没在电脑前操作看到这条信息就会警觉。这一层不解决技术问题但它把攻击成本从骗人扫一下提高到了骗人扫一下并且无视明显的异常提示。第二层是压缩确认窗口。票据在 SCANNED 状态之后给一个很短的确认时限比如 60 秒超时自动转为 CANCELED。攻击者转发图片、等受害者扫码、再等受害者点确认这个链路很容易超过时限。正常用户扫完马上就点了不受影响。第三层是绑定生成端的环境指纹。生成二维码的时候服务端记录下请求的来源 IP 段、User-Agent 的关键特征。兑换令牌的时候做一次比对如果差异过大就要求额外的验证。这一层会有误伤用户换网络、换浏览器所以只能作为风控信号而不是硬拦截。第四层也是最有效的一层限制票据的可转移性。生成二维码时服务端下发一个 HttpOnly 的 Cookie 作为会话标识兑换令牌时必须带上这个 Cookie。攻击者转发的只是图片拿不到受害者的 Cookie所以就算受害者扫了并确认了攻击者那台设备也换不到令牌。这个做法牺牲了一点兼容性跨域、隐私模式会有问题但防钓鱼效果是实打实的。4.2 票据的生命周期管理比想象中更容易出事票据是这套系统的核心资产它的生命周期里有几个点特别容易出问题。生成环节的枚举风险。如果票据的随机性不够攻击者可以批量生成候选票据去探测状态一旦命中一个 CONFIRMED 的票据就能尝试兑换。防这个的办法很简单票据长度不低于 32 位、字符集不小于 62、使用密码学安全随机源。这样暴力枚举的空间是 62^32天文数字实际不可行。顺便说一句生成接口本身也要限流按 IP 和设备指纹做防止有人刷爆存储。存储环节的信息泄露。票据记录里会存授权用户 ID这个字段是敏感的。如果存储被未授权访问等于泄露了某张票对应某个用户。所以存储层的访问控制要做严别把缓存实例暴露在公网也别在日志里打印完整的票据对象。我见过有实现直接把整个会话对象序列化打进日志里面带着用户 ID 和手机号这个在合规审查里是硬伤。消费环节的重放风险。前面说过票据必须一次性消费但实际实现里经常出问题。常见错误有三个一是用先查后删的两步操作并发下两张请求都能查到都能兑换二是删除失败但没抛异常接口照样返回成功三是把消费标记写在了另一个存储里主存储的票据没删下次还能用。正确的做法是用原子操作Redis 的GETDEL或者 Lua 脚本一步搞定读和删失败就整个失败。过期环节的时钟问题。如果服务端是多实例部署各机器的时钟可能有偏差导致 A 机器认为票据没过期、B 机器认为过期了。这个问题的根源是把过期判断交给了本地时钟。解决办法是统一用存储层的 TTL 作为唯一权威业务代码里不要再自己做时间比较或者所有实例都对接同一个时间源。4.3 三类攻击面逐一对照把上面的分析收拢成一张表方便做架构评审的时候逐条对。攻击类型攻击路径主要防护手段残留风险二维码转发钓鱼截取图片转发给受害者诱导确认确认页展示设备信息、短确认窗口、绑定生成端 Cookie用户无视提示仍然确认票据枚举批量猜测 ticket 探测状态32 位以上随机票据、生成接口限流几乎为零票据重放复用已确认的票据换取令牌原子性一次性消费、ticket secret 双因子若 secret 同时泄露则失效中间人窃听在 PC 与服务端之间截获流量全链路 HTTPS、Cookie 加 Secure 与 SameSite客户端被植入根证书点击劫持用透明 iframe 覆盖二维码区域诱导点击二维码区域加 X-Frame-Options、用图片渲染老旧浏览器兼容问题扫码后信息泄露轮询接口返回过多账号信息状态接口只返回状态枚举账号信息只在兑换后下发实现疏忽表格里最后一列是我特意加的。安全方案没有完全防住这回事只有把攻击成本抬高到不划算。做架构评审的时候与其争论某个攻击能不能防住不如把残留风险明确写出来让业务方知道自己在承担什么。5. 实战踩坑与排查速查表5.1 六种典型故障对应的定位思路这套系统上线之后我遇到过的问题基本集中在状态不同步和请求打不通两类。整理成速查表遇到现象直接对。现象最可能的原因排查动作二维码刚出来就显示过期服务端 TTL 与前端倒计时不一致或前端倒计时用了本地时间对比接口返回的 expireIn 与前端展示值检查是否有客户端时钟偏移手机扫了PC 端毫无反应状态接口被缓存或状态枚举前后端不一致看响应头有没有 Cache-Control抓包比对返回的 state 值PC 卡在已扫描不动手机端确认接口失败或确认后没写回存储查手机端网络请求查服务端确认接口的错误日志兑换令牌报凭证不匹配secret 丢失刷新页面、开了新标签或跨域导致 Cookie 没带上检查 secret 的存储位置检查跨域配置和 SameSite多标签页互相踢下线同一 ticket 被多个页面并发兑换一次性消费只成功一个让每个标签页独立生成二维码或做页面间广播高峰期状态接口大面积超时轮询 QPS 打满或长轮询占满了线程池看接口 QPS 曲线与线程池活跃数检查是否误用了阻塞式挂起表格里第二条特别值得展开。状态接口被缓存这个问题我第一次遇到的时候完全没往缓存上想因为本地开发环境一切正常一上生产就不行。后来发现是前置的代理层对 GET 请求做了默认缓存而我们的接口又没显式声明不可缓存。修复很简单响应头加上Cache-Control: no-store, no-cache, must-revalidate同时把状态查询改成 POST虽然不符合 REST 风格但能绕开绝大多数中间层的 GET 缓存策略。这个坑的教训是任何返回实时状态的接口都必须显式声明不可缓存别指望中间层猜你的意图。第三条也常见。手机端确认成功之后服务端要写回状态这个写回如果失败了存储抖动、超时PC 端就永远等不到。我的做法是在确认接口里做重试并且把确认成功但写回失败这个情况单独打一条告警日志。另外前端要有兜底超过 30 秒还停在 SCANNED就提示用户如果已确认请刷新重试并给一个手动刷新的按钮。别让用户对着一个不动的界面干等。5.2 轮询风暴的治理从三个角度下手轮询风暴是这类系统最常见的性能问题尤其在早晚高峰。治理思路分三层。第一层是减少请求数量。前面提到的页面隐藏暂停、WAITING 低频 SCANNED 高频这两个改动能砍掉一大半无效请求。还有一个容易被忽略的点二维码过期之后前端必须停止轮询。我见过有实现过期了还在每秒打一次接口用户把登录页开着去吃饭回来发现后台打了几千次请求。加一个过期判断clearInterval一下的事。第二层是降低单次请求的成本。状态查询接口里不能有任何数据库操作、不能有复杂的序列化、不能打业务日志。理想情况下它就是一次内存读取加一次枚举返回响应时间在 1 毫秒以内。如果状态数据量小甚至可以把整个会话对象缓存在本地内存里做二级缓存只在状态跃迁时才同步。注意二级缓存会带来一致性问题得用发布订阅或者短 TTL 来兜。第三层是横向削峰。如果前面两层做完 QPS 还是高那就上长轮询把轮询次数换成连接数。长轮询的关键是异步挂起用 Servlet 的AsyncContext或者响应式框架一个线程能挂几千个请求。同时要注意网关的空闲超时和负载均衡的连接数上限这两个地方经常成为新的瓶颈。还有一个细节长轮询的连接在网关侧断开时服务端要能感知到并释放资源否则会积压一堆僵尸连接。最后分享一个我在实际项目里用的小技巧。给状态查询接口加一个版本号参数前端每次带上自己已知的状态版本服务端如果发现版本没变直接返回 304 或者一个极简的未变化响应连 JSON 序列化都省了。这个改动在请求量大的时候能省下可观的 CPU实现成本也就十几行代码。当然前提是前端要正确处理这个响应别把它当成错误。5.3 一些不太好归类但很实用的经验关于二维码的渲染。别用前端 canvas 现画用服务端生成图片返回。原因有三个一是尺寸和纠错等级可控低端机识别率高二是可以防止二维码被覆盖这类点击劫持三是缓存友好。纠错等级建议用 M 级太高会让图形变密反而降低识别率。图片尺寸别低于 200×200太小了手机对焦困难。关于多端登录的冲突。用户可能同时开着手机App和PC网页扫码登录之后两边的会话是什么关系我的建议是两套会话独立维护PC端的令牌和手机端的令牌互不干扰但都归属于同一个用户。这样任何一端退出不会影响另一端符合用户预期。如果业务上要求一端登录挤掉另一端那要在签发令牌的时候做全局的单点控制这个逻辑最好放在统一的会话服务里别散落在各个业务模块。关于测试环境的坑。本地开发的时候手机和电脑通常在同一个局域网二维码里如果写的是localhost手机根本扫不开。常见的做法是把二维码内容改成局域网 IP但这会带来跨域和 Cookie 域名的问题。我一般会在开发环境加一个开关把二维码内容指向一个固定的测试域名然后在 hosts 里做映射。另外测试环境的 HTTPS 证书往往是自签的手机端会拦得提前把证书装好否则调试半天以为是代码问题。关于灰度发布。这套流程涉及前后端和移动端三方任何一方先上线都可能出问题。比较稳的顺序是先上服务端新老接口并存再上PC端走新的生成和轮询接口但兑换接口保留旧逻辑的兼容分支最后上移动端新版本才支持扫码确认。整个过程要保留一个强制走老流程的降级开关出问题能一键切回。我在一个项目里就是因为移动端灰度没控制好一批旧版本用户扫了新二维码但客户端不认识直接白屏回滚花了半小时。关于监控指标。至少要有这么几个二维码生成量、扫码成功率SCANNED / 生成量、确认成功率CONFIRMED / SCANNED、端到端耗时分布、状态接口的 P99 延迟、过期率。这几个指标能覆盖绝大多数异常生成量突增说明有人刷接口扫码成功率骤降说明二维码识别出了问题确认成功率掉说明确认接口有故障端到端耗时变长说明某一环卡住了。我当时就是靠确认成功率掉了 15 个点这条告警提前发现了一个存储集群的写入抖动。6. 这套机制还能怎么用扫码登录本质上是用一台已认证设备授权另一台设备的通用模式把它抽象出来能复用的场景其实不少。最常见的是扫码支付确认逻辑几乎一样只是最后一步不是签发登录令牌而是发起一笔交易安全要求更高通常还要加支付密码或者生物识别。另一类是扫码加好友、扫码进群这个是扫码后的业务动作不同状态机可以简化成扫到即执行不需要二次确认。还有一类是设备配网智能硬件扫二维码把自己的标识上报服务端把设备和账号绑定本质上是把设备当成了那个待登录的PC端。还有一个稍微冷门但很有用的场景扫码完成跨端的数据同步。比如用户在手机上编辑了一半的文档想在电脑上接着写扫个码把编辑会话搬过去。这个场景里二维码承载的不是登录凭证而是一个会话的交接票据服务端要保证交接过程中数据的一致性比登录要复杂一些。我在实际做这套东西的过程中最深的一点体会是扫码登录的复杂度不在二维码本身而在状态机的一致性上。二维码的生成和渲染都是成熟方案随便找个库就能用真正花时间的是状态在什么时机变、由谁来变、变了之后怎么保证两端都能看到。很多线上问题的根因都是某个状态跃迁没有被正确持久化或者两端对同一个状态的理解不一致。所以如果你的团队要接这套东西我建议把三分之一的时间花在把状态机画清楚、把每个状态的入口和出口都列出来、把异常情况下应该落到哪个状态定死剩下的时间再动手写代码。这个顺序反了后面排查问题的成本会翻好几倍。
