手机扫码登录详细设计-洪萨配资

手机扫码登录（Web/PC 扫码）详细设计

目标：用户在Web/PC 端看到二维码，用手机 App扫码确认后，Web/PC 端自动登录。
关键词：一次性二维码、短时会话、状态机、WebSocket/轮询、JWT/Session、风控与安全。

1. 场景与需求

1.1 核心场景

Web/PC 打开登录页 → 展示二维码
手机 App 扫码 → 告知“是否在某某设备登录？”
用户在手机确认/取消 → Web/PC 实时得到结果并完成登录

1.2 业务需求

低延迟：扫码后 1s 内让 Web/PC 感知状态变化（理想）
高可用：登录链路要抗抖动（网络波动、页面刷新、重复扫码）
安全：防伪造二维码、防重放、防钓鱼、防越权
可观测：全链路埋点、日志、指标、告警
可扩展：支持多端（H5/PC/小程序）、支持二次确认、支持风控

1.3 非功能指标建议

二维码有效期：60–120s
单二维码最多允许：N 次状态查询（防刷，如 60 次/分钟）
扫码确认超时：60s
登录态：
- Web 端：HttpOnly Cookie Session 或 JWT Cookie（同站策略）
- App 端：已有登录态（AccessToken + RefreshToken）

2. 总体架构

2.1 角色

Web/PC：展示二维码、监听状态变化、拿到登录态
App：扫码、拉取二维码信息、展示确认页、提交确认/取消
Auth 服务：生成二维码、维护状态机、签发 Web 登录态
Redis：保存二维码会话（短期）、状态、一次性票据
消息通道：WebSocket（优先）或长轮询/短轮询（兜底）
风控/安全：设备指纹、IP 风险、地理位置异常、黑名单等（可选）

2.2 数据与通道选择

状态存储：Redis（TTL 强制过期）
状态通知：
- 首选：WebSocket（服务端推送）
- 兜底：长轮询（30s）或短轮询（1–2s）
Web 登录态颁发：
- 方案 A（推荐）：一次性 ticket 交换 cookie/session
- 方案 B：扫码确认后直接写入 Web session（需要能定位到 Web 连接）

3. 核心状态机设计

3.1 状态定义

DISPLAYED：二维码已生成（Web 已拿到并展示）
SCANNED：手机已扫码（已识别二维码）
CONFIRMED：用户在手机确认
CANCELLED：用户在手机取消
EXPIRED：二维码过期
CONSUMED：Web 已完成登录（票据已使用）

3.2 状态转换（严格）

DISPLAYED -> SCANNED -> CONFIRMED -> CONSUMED DISPLAYED -> SCANNED -> CANCELLED DISPLAYED -> EXPIRED SCANNED -> EXPIRED CONFIRMED -> EXPIRED (若 Web 长时间不换票据，ticket 可单独更短 TTL)

3.3 幂等与并发

扫码可能重复：SCANNED状态写入应幂等（SETNX 或 Lua）
确认可能重复提交：确认接口应幂等（状态已 CONFIRMED 则返回成功）
Web 页面刷新：同一个qrId允许重新订阅状态（WebSocket 重新连/轮询继续）

4. 二维码内容设计（非常关键）

4.1 二维码里放什么？

不要直接放 userId / token。
只放一个随机、不可预测的会话标识：

qrId：128-bit 随机数（Base64URL / Hex）
可选：sig：服务端签名（防伪造二维码）
可选：ts：生成时间戳（辅助校验）

示例（URL Scheme）：

myapp://qr-login?qrId=AbCd...&ts=173...&sig=...

或（HTTPS Deep Link / Universal Link）：

https://auth.example.com/qr/scan?qrId=...&ts=...&sig=...

4.2 防伪造（建议做）

sig = HMAC-SHA256(secret, qrId + "." + ts)
服务端校验：abs(now - ts) <= 120s且HMAC一致

5. Redis Key 设计

5.1 Key 结构（示例）

qr:login:{qrId}→ Hash
- status：DISPLAYED / SCANNED / CONFIRMED / CANCELLED
- createdAt
- expireAt
- webClientId（可选：WebSocket 连接标识）
- deviceHint（可选：扫码设备信息，用于 Web 展示提示）
- confirmedUserId（CONFIRMED 后写入）
- ticket（CONFIRMED 后写入一次性票据）
TTL：120s（二维码本体）
qr:ticket:{ticket}→ String(userId 或会话信息)
- TTL：30s（短！一次性！）

5.2 原子更新建议

用 Lua 做状态推进，确保：

不允许从 CANCELLED 再 CONFIRMED
不允许过期后再 CONFIRMED
CONFIRMED 只生成一次 ticket

6. 交互流程

6.1 Web/PC 端流程

GET /api/qr-login/init→ 返回qrId、二维码图片/URL、过期时间
Web 建立订阅：
- WebSocket：ws://.../ws/qr-login?qrId=...
- 或轮询：GET /api/qr-login/poll?qrId=...
收到状态：
- SCANNED：UI 提示“已扫码，请在手机确认”
- CONFIRMED：拿到ticket，调用POST /api/qr-login/exchange换取登录态
- CANCELLED/EXPIRED：提示并刷新二维码

6.2 App 端流程

扫码解析qrId/ts/sig
调用POST /api/qr-login/scan（App 已登录，带 App Token）
服务端返回 Web 端信息（设备、地点、浏览器）用于确认页展示
用户点击确认：
- POST /api/qr-login/confirm
或取消：
- POST /api/qr-login/cancel

7. API 设计（REST 示例）

7.1 生成二维码

GET/api/qr-login/init

响应：

{"qrId":"AbCdEf...","qrUrl":"myapp://qr-login?qrId=...&ts=...&sig=...","expireInSeconds":120}

7.2 Web 轮询状态（兜底）

GET/api/qr-login/poll?qrId=...&sinceVersion=...

响应：

{"status":"SCANNED","deviceHint":"iPhone 15 · 上海","ticket":null,"expireInSeconds":80}

7.3 App 扫码上报

POST/api/qr-login/scan

{"qrId":"...","ts":1730000000,"sig":"..."}

返回（给 App 确认页展示）：

{"status":"SCANNED","webInfo":{"ipCity":"New York","browser":"Chrome","os":"Windows","time":"2026-01-31T12:00:00Z"}}

7.4 App 确认登录

POST/api/qr-login/confirm

{"qrId":"..."}

7.5 App 取消

POST/api/qr-login/cancel

{"qrId":"..."}

7.6 Web 换票据拿登录态

POST/api/qr-login/exchange

{"qrId":"...","ticket":"TICKET_..."}

响应：Set-Cookie（Session/JWT Cookie） +{ "ok": true }

8. WebSocket 推送设计（推荐）

8.1 建连

GET ws://auth.example.com/ws/qr-login?qrId=...

服务端验证：

qrId存在且未过期
绑定连接connId到qr:login:{qrId}.webClientId

8.2 推送消息

{"qrId":"...","status":"SCANNED","deviceHint":"..."}

CONFIRMED推送可带ticket（建议只带 ticket，不带 userId）：

{"qrId":"...","status":"CONFIRMED","ticket":"TICKET_..."}

8.3 多实例

Redis Pub/Sub 或 MQ 广播状态变更
各节点维护本地qrId -> wsSession映射，收到事件后推送

9. 安全设计清单

ticket一次性：GETDEL或 Lua 原子删除
sig+ts防伪造二维码
Web 端 Cookie：HttpOnly + Secure + SameSite
exchange校验Origin/Referer
限流：init/poll/scan/confirm 分别按 IP/userId 维度
App 确认页展示 Web 端信息（地点/浏览器/时间），让用户识别异常
风控扩展：异地登录/代理/VPN/黑名单/二次验证

10. 可观测性

关键指标：

init 成功率/耗时
扫码率（init→scan）
确认率（scan→confirm）
换票成功率（confirm→exchange）
过期率、取消率

日志：

qrId贯穿全链路（trace tag）
userId 脱敏（hash），IP/UA 记录用于风控追踪

11. Java 落地要点（Spring Boot）

关键组件：

QrLoginService：状态机推进（Lua）
RedisRepository：Key/TTL 封装
WebSocketHandler：连接管理与推送
AuthTokenService：签发 Web session/JWT
RateLimit：限流（网关优先）

Lua（伪代码简化）：

-- KEYS[1] = qr:login:{qrId}-- ARGV[1] = targetStatuslocalst=redis.call('HGET',KEYS[1],'status')ifnotstthenreturn{err="NOT_FOUND"}endifst=='CANCELLED'orst=='CONSUMED'orst=='EXPIRED'thenreturn{ok=0,status=st}end-- ...按状态推进（略）return{ok=1}

12. 必测用例清单

正常：init → scan → confirm → exchange
cancel：scan → cancel（Web 及时感知）
过期：init 后不扫码，Web 刷新二维码
重复扫码/重复确认/重复 exchange（幂等 + ticket 一次性）
Web 刷新/断网重连（仍能继续）
限流触发与恢复
伪造 sig / 篡改 qrId / 过期 ts 全部失败

13. 常见坑

把用户信息/Token 塞进二维码（等于送号）
ticket TTL 太长（被截获风险更大）
只做轮询（高并发下把服务打爆）
不做幂等（重复扫码/确认导致状态乱）