WebSocket on 牛哥聊技术

扫码登录的完整设计

Fri, 21 Feb 2025 15:30:00 +0800

写在前面

PC 浏览器扫手机端二维码自动登录——12306、知乎、京东、网易邮箱、微信网页版……这种交互在国内已经是标配。

它看着简单——但背后是一套涉及前端轮询、后端状态机、长连接、安全控制的完整设计。新人接这块时常常忽略关键细节 ，做出来要么不安全、要么体验差。

本文从协议、状态机、API 设计、安全考虑几个层面把扫码登录讲清楚。

一、整体流程

sequenceDiagram
 participant Browser as PC 浏览器
 participant Server as 后端
 participant Phone as 手机 App

 Browser->>Server: GET /qr/create
 Server->>Server: 生成 sceneId + 二维码
 Server-->>Browser: { sceneId, qrUrl, expiresIn }
 Browser->>Browser: 展示二维码
 Browser->>Server: 长轮询 / SSE 等待状态
 Phone->>Phone: 扫描二维码
 Phone->>Server: POST /qr/scan { sceneId, token }
 Server->>Server: 标记 sceneId 为 SCANNED
 Server-->>Browser: SCANNED（手机已扫，等确认）
 Phone->>Server: POST /qr/confirm { sceneId, token }
 Server->>Server: 标记 sceneId 为 CONFIRMED + 颁发 PC 端 token
 Server-->>Browser: CONFIRMED + token
 Browser->>Browser: 设置 cookie/storage 跳转登录页

四个核心环节：

PC 请求二维码
手机扫描（标记 sceneId 状态变化）
手机确认登录（颁发 PC 端 token）
PC 拿到 token 完成登录

二、状态机

sceneId 是整个流程的核心标识——它在后端经历几个状态：

stateDiagram-v2
 [*] --> PENDING: 创建二维码
 PENDING --> SCANNED: 手机扫描
 SCANNED --> CONFIRMED: 手机确认
 SCANNED --> CANCELLED: 手机取消
 PENDING --> EXPIRED: 超时
 SCANNED --> EXPIRED: 超时
 CONFIRMED --> [*]: PC 拿到 token
 CANCELLED --> [*]
 EXPIRED --> [*]

为什么"扫描"和"确认"要分两步？

手机扫到的是任意二维码，不一定是登录用的——必须显式确认才算同意登录
防止"路边贴的恶意二维码骗你扫"——扫描后用户能看到"是否登录到 xxx 网站"的确认页

存储用 Redis 自然——key 是 sceneId，value 是 status + 关联数据，TTL 5 分钟。

三、API 设计

1. 创建二维码

1
2


GET /api/qr/create
Response: { sceneId, qrPayload, expireSeconds }

qrPayload 是二维码内容——通常包含：

1

https://your-app.com/qrlogin?scene=<sceneId>&t=<timestamp>&sign=<signature>

带签名防止伪造——后端校验签名才允许处理。

2. PC 端轮询/订阅状态

方式 A：长轮询

1
2


GET /api/qr/wait?sceneId=xxx&from=PENDING
（后端阻塞，直到状态变化或 30 秒超时返回）

PC 端循环调用，每次带上"我现在知道的状态"——后端只在状态变化时返回。

方式 B：SSE（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


GET /api/qr/stream?sceneId=xxx
Accept: text/event-stream

event: status
data: {"status": "PENDING"}

event: status
data: {"status": "SCANNED"}

event: status
data: {"status": "CONFIRMED", "token": "..."}

SSE 比长轮询省连接、省服务端线程，强烈推荐。

方式 C：WebSocket

适合"长连接 + 双向通信"场景——但做扫码登录是杀鸡用牛刀。

3. 手机扫描

1
2
3


POST /api/qr/scan
Body: { sceneId }
Headers: Authorization: Bearer <user_token>

手机已登录用户扫码后，App 调这个接口——后端把 sceneId 标记 SCANNED，记录是哪个 user 扫的。

返回内容包括"PC 端要登录哪个账号"信息，让 App 显示二次确认页面：

1
2


是否使用账号 zhangsan@example.com 登录到 PC 端？
[确认] [取消]

4. 手机确认

1
2


POST /api/qr/confirm
Body: { sceneId }

后端：

校验 sceneId 状态是 SCANNED
校验当前 user 和扫描时的 user 一致
颁发 PC 端 token
把 sceneId 状态改为 CONFIRMED + 关联 token

PC 端的 SSE 收到 CONFIRMED 状态 + token，完成登录。

5. 手机取消

1
2


POST /api/qr/cancel
Body: { sceneId }

把 sceneId 状态改为 CANCELLED——PC 端收到通知后展示"已取消"。

四、安全考虑

扫码登录是登录入口——安全比体验更重要。

1. sceneId 必须不可猜

用 UUID v4 或 nanoid——不要用自增 ID。攻击者枚举 sceneId 可能尝试劫持别人的登录会话。

2. 二维码 URL 带签名

1

https://app.com/qrlogin?scene=xxx&t=1700000000&sign=hmac(secret, scene+t)

App 扫码后先校验签名——拒绝伪造的二维码。

3. PC 端和手机要校验"会话一致性"

PC 端轮询时带一个浏览器随机 token——手机确认时如果发现 token 不一致，说明可能被中间人劫持。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


PC: GET /qr/create
 Browser生成 browserNonce 存 cookie
 qrPayload 中包含 browserNonce 的 hash

Phone: 扫码后 POST /qr/scan
 后端记录 nonce hash

PC: GET /qr/stream
 带上 browserNonce
 后端校验 nonce hash 一致才返回 token

4. 二维码必须短时间过期

5 分钟内不被扫描就 EXPIRED——避免有人贴在公共场所"骗扫"。

5. 已扫描状态也要超时

SCANNED 状态如果 1 分钟内没确认 → EXPIRED——避免"用户扫了但没确认就走了，攻击者后续接管"。

6. 手机端必须已登录

扫描接口要求用户已登录——不允许游客状态扫码。否则任何人扫了都能"以游客身份登录 PC 端"，毫无意义。

7. 防 CSRF

PC 端的 sceneId 是会话级的——一个 sceneId 只能绑定一个浏览器 session。换浏览器轮询同一个 sceneId 应该被拒绝。

8. 异地登录提醒

PC 端登录成功后发送邮件/短信通知用户——异地登录是常见的"安全感"配置。

五、UX 上的几个细节

1. 扫描后的状态展示

UX 不要只显示"等待扫描"和"登录成功"——SCANNED 状态要专门展示：

1
2
3


[二维码图] [二维码灰色 + 中央对勾] [跳转中...]

请扫码登录 扫描成功，请在手机上确认 登录成功

让用户知道"手机端在做什么"，不会以为系统卡住。

2. 二维码刷新

5 分钟过期后自动刷新——而不是显示"过期请重新打开"。

3. 手机和 PC 一定不能在同一浏览器

PC 浏览器扫描 PC 浏览器二维码——必须拒绝。手机端 App 才有资格扫——通过 User-Agent 简单判断。

4. 取消的反馈

用户在手机上"取消"后——PC 应该立刻看到"已取消"，并提供"重新生成二维码"按钮。

六、技术实现要点

1. SSE 比长轮询好

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


const evt = new EventSource(`/api/qr/stream?sceneId=${sceneId}`);
evt.addEventListener('status', e => {
 const data = JSON.parse(e.data);
 if (data.status === 'CONFIRMED') {
 localStorage.setItem('token', data.token);
 location.href = '/dashboard';
 evt.close();
 }
});
evt.onerror = () => {
 // 重连
};

记得在 nginx 配置 proxy_buffering off，否则消息要等 buffer 满才推送。

2. 后端用 Redis 维护状态

1
2
3


String sceneId = UUID.randomUUID().toString();
SceneState state = new SceneState("PENDING", null, System.currentTimeMillis());
redis.setex("qr:" + sceneId, 300, JSON.toJSONString(state));

状态变更用 Lua 脚本保证原子性：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


local key = KEYS[1]
local expectStatus = ARGV[1]
local newStatus = ARGV[2]
local current = redis.call('GET', key)
if current == false then return -1 end
local state = cjson.decode(current)
if state.status ~= expectStatus then return 0 end
state.status = newStatus
redis.call('SETEX', key, 300, cjson.encode(state))
return 1

3. 跨进程通信

后端可能多实例——手机端命中实例 A，PC 端命中实例 B。状态变更需要广播：

简单：后端只读 Redis 状态——所有实例数据一致
进阶：用 Redis Pub/Sub 主动推送实例 B 触发 SSE

4. 二维码生成

后端不一定要生成图片——返回二维码内容字符串，前端用 qrcode.js 渲染：

1
2


import QRCode from 'qrcode';
QRCode.toCanvas(canvasEl, qrPayload);

省了后端 PNG 编码、节省带宽。

七、移动 App 端的实现要点

1. 调用系统相机扫码

iOS / Android 都有原生 API——读取二维码内容。

2. 内容解析

1
2
3
4
5
6
7
8


// 二维码内容
https://app.com/qrlogin?scene=abc&t=...&sign=...

// App 端：
- 校验是不是自家域名
- 校验签名
- 校验时间（防重放）
- 调用 /qr/scan 接口

如果二维码不是自家——不要打开浏览器跳转 URL，那等于把扫码结果给到不可信的网站。

3. 显示确认页面

不要扫描后直接跳过——展示明确的"是否登录到 PC？“对话框，用户主动点确认才下一步。

4. 异常处理

网络断开 → 提示重试
二维码过期 → 提示用户刷新 PC 端
重复扫描 → 提示"该二维码已被扫描”

八、扩展场景

1. 关注公众号即登录（微信）

二维码生成时带上"场景值"——用户扫码并关注公众号后，公众号收到事件回调——等同于"扫描+确认"一次完成。

适合"既要登录又要涨粉"的场景。

2. 跨端会话同步

PC 扫码登录后，手机端是不是也算"已登录"？ 通常是——扫码本身就证明了用户身份。

3. 桌面客户端扫码

很多桌面 App（如 Microsoft Teams、Slack）也支持二维码登录——逻辑和 Web 完全相同。

4. 离线扫码

部分场景下手机断网时扫描——可以先在本地校验签名 + 缓存意图，联网后再上报后端。

小结

把全文压一句：

扫码登录的核心是『二维码 + sceneId + 状态机 + 双端协同』——看似 5 分钟能写完，做对要考虑安全、体验、跨实例同步十几个点。

工程要点：

状态机：PENDING → SCANNED → CONFIRMED——不要跳过 SCANNED
二维码 URL 带签名
PC 端用 SSE 等状态变化
手机端必须已登录 + 显式确认
sceneId UUID + 短期 TTL
跨实例用 Redis 共享状态

掌握这套，你做的"扫码登录"在体验和安全上能直接对标主流产品。

服务端到客户端的进度推送：SSE 与 WebSocket 选型

Thu, 12 Mar 2020 16:00:00 +0800

一个看似简单的需求

用户在管理后台点"导出报表"——服务端要生成一个 200MB 的 Excel，前端等 30 秒。最差的体验是这样：

点了按钮，前端转圈圈。30 秒过去——用户以为卡住了，开始连点。后端被点出三次重复任务，最后崩了。

合格的体验应该是：

点了按钮，立刻看到"正在生成 Excel…12%"，每秒进度条往上跳，用户安心等待。

实现这种"实时进度反馈"看起来不复杂——但坑很多：

HTTP 是请求-响应模型，服务端没法主动告诉前端"现在 20% 了"
进度怎么从生成 Excel 的线程"流"到 HTTP 响应里
浏览器有 Range 请求、有 chunked 编码、有 SSE、有 WebSocket——该选哪个

本文把三种主流方案讲清楚——HTTP 流式响应、SSE、WebSocket。各自的优劣、代码、踩坑都覆盖。

一、需求拆解：什么叫"下载进度"

要讲清进度反馈，先把"下载"分两类：

类型 A：纯文件传输

文件已存在，浏览器直接下载——进度信息浏览器自己能算（Content-Length / 已接收字节）。前端不需要服务端告诉，可以自己监听 progress 事件。这种场景根本不需要后端反馈。

1
2
3
4
5
6
7
8


const xhr = new XMLHttpRequest();
xhr.responseType = 'blob';
xhr.onprogress = e => {
 const percent = (e.loaded / e.total * 100).toFixed(1);
 setProgress(percent); // 浏览器自己算
};
xhr.open('GET', '/file/download/1');
xhr.send();

这种是大部分场景——多数情况下不需要后端介入，避免加不必要的复杂度。

类型 B：服务端要先"做事"才有文件

真正复杂的——服务端先生成 Excel（30 秒）、再让前端下载。生成过程中浏览器看到的是 0 字节、Content-Length 还没确定。**进度只有服务端知道 **。

类型 B 才是本文的主场。

二、方案 1：HTTP 流式响应（chunked）

最简单的姿势——把"任务进度"和"最终文件"塞到一个 HTTP 响应里。

服务端用 StreamingResponseBody，每行输出一个 JSON（NDJSON / JSON-Lines）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@GetMapping("/export")
public ResponseEntity<StreamingResponseBody> export() {
 StreamingResponseBody stream = output -> {
 for (int i = 0; i <= 100; i += 10) {
 // 输出一行 JSON + \n
 String line = String.format("{\"progress\":%d}\n", i);
 output.write(line.getBytes(StandardCharsets.UTF_8));
 output.flush();
 Thread.sleep(500); // 模拟工作
 }
 output.write("{\"done\":true,\"url\":\"/file/123\"}\n".getBytes(StandardCharsets.UTF_8));
 };
 return ResponseEntity.ok()
 .contentType(MediaType.parseMediaType("application/x-ndjson"))
 .body(stream);
}

这里故意不用 SSE 的 data: …\n\n 协议格式——避免和方案 2 混淆。要 SSE 就直接用 SseEmitter（见方案 2），这里就是普通的"按行 JSON 流"。

前端用 fetch + ReadableStream 读：

1
2
3
4
5
6
7
8


const resp = await fetch('/export');
const reader = resp.body.getReader();
while (true) {
 const {done, value} = await reader.read();
 if (done) break;
 const text = new TextDecoder().decode(value);
 // 解析进度
}

优点：

实现简单，一个接口搞定
浏览器原生支持

缺点：

进度信息和文件内容混在一个流里，前端要自己解析协议
不是标准协议，每个项目都可能不一样

适合简单场景——不推荐做复杂业务。

三、方案 2：SSE（Server-Sent Events）

SSE 是 HTML5 的标准——专门为"服务端推送给客户端"设计，比 WebSocket 简单一半。

服务端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@GetMapping(value = "/export/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter exportStream() {
 SseEmitter emitter = new SseEmitter(60_000L); // 60s 超时

 executor.execute(() -> {
 try {
 for (int i = 0; i <= 100; i += 5) {
 emitter.send(SseEmitter.event()
 .name("progress")
 .data(Map.of("percent", i, "msg", "处理中...")));
 Thread.sleep(500);
 }
 // 最终输出文件下载链接
 emitter.send(SseEmitter.event()
 .name("done")
 .data(Map.of("url", "/file/12345")));
 emitter.complete();
 } catch (Exception e) {
 emitter.completeWithError(e);
 }
 });
 return emitter;
}

前端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


const evt = new EventSource('/export/stream');

evt.addEventListener('progress', e => {
 const data = JSON.parse(e.data);
 setProgress(data.percent);
});

evt.addEventListener('done', e => {
 const data = JSON.parse(e.data);
 window.location.href = data.url;
 evt.close();
});

evt.onerror = err => {
 console.error('SSE error', err);
 evt.close();
};

SSE 的特点

服务端 → 客户端单向——客户端不能用同一通道发消息
基于 HTTP——不需要握手协议升级，CDN 能转发
自动重连——网络断了浏览器自动重连
协议极简——event 名 + data 行
比 WebSocket 轻量——但功能少一半

一个常被忽视的细节

很多 PaaS / Nginx 默认 buffer 响应，SSE 推送的消息要等 buffer 满了才到前端。要在 nginx 里关闭：

1
2
3
4
5
6


location /export/ {
 proxy_pass http://backend;
 proxy_buffering off; # ★ 关键
 proxy_read_timeout 3600s;
 chunked_transfer_encoding on;
}

不开就是"明明代码 emit 了但前端 30 秒后才一次性收到所有进度"。

四、方案 3：WebSocket

最重量级的——双向通信，服务端推前端、前端发命令到服务端都行。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


@Component
public class ExportWebSocketHandler extends TextWebSocketHandler {

 @Override
 public void handleTextMessage(WebSocketSession session, TextMessage msg) throws Exception {
 // 收到前端"开始导出"指令后启动任务
 ExportRequest req = JSON.parseObject(msg.getPayload(), ExportRequest.class);
 executor.execute(() -> doExport(session, req));
 }

 private void doExport(WebSocketSession session, ExportRequest req) {
 try {
 for (int i = 0; i <= 100; i += 5) {
 session.sendMessage(new TextMessage(JSON.toJSONString(
 Map.of("type", "progress", "percent", i))));
 Thread.sleep(500);
 }
 session.sendMessage(new TextMessage(JSON.toJSONString(
 Map.of("type", "done", "url", "/file/123"))));
 } catch (Exception e) {
 log.error("export error", e);
 }
 }
}

适用场景：

同一连接里要前端 → 后端发指令（如取消任务、调整参数）
已经有 WebSocket 长连接复用
复杂双向交互（如客服聊天 + 文件传输）

但单纯做"进度反馈"上 WebSocket 是杀鸡用牛刀——SSE 已经够了。

五、三方案对比

	StreamingResponseBody	SSE	WebSocket
实现复杂度	极简	简单	中
协议	HTTP	HTTP（standard）	HTTP Upgrade
双向	✗	✗ 单向	✓
自动重连	✗	✓	✗（要自己写）
Nginx 兼容	△	△（要关 buffer）	△（要 upgrade 配置）
浏览器支持	✓ 全部	✓ 全部	✓ 全部
适用场景	进度+文件混合	单向进度反馈	双向交互

给一个直接的建议：

类型 A（纯文件下载）：浏览器原生 progress；类型 B（服务端做事 + 进度）：99% 用 SSE 就够。WebSocket 留给真正的双向场景。

六、生产细节

1. 进度的"真实性"

1
2
3
4


for (int i = 0; i <= 100; i += 5) {
 emit(i);
 Thread.sleep(500);
}

写成这样的进度是假进度——看着舒服但和真实工作进度无关。生产代码进度要从真实业务里取：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public void doExport(SseEmitter emitter, List<User> users) {
 int total = users.size();
 for (int i = 0; i < total; i++) {
 process(users.get(i));
 if (i % 100 == 0 || i == total - 1) { // 每 100 条推一次
 emitter.send(SseEmitter.event()
 .name("progress")
 .data(Map.of("percent", i * 100 / total)));
 }
 }
}

2. 异常处理

1

emitter.send(...); // 客户端断开会抛 IllegalStateException

客户端关页面、断网、超时——服务端继续 send 会异常。要 catch 后调 emitter.completeWithError(e)，并停止剩余工作（节省服务器资源）。

3. 资源清理

SseEmitter 是要释放的——onCompletion、onTimeout、onError 三个回调要注册：

1
2
3


emitter.onCompletion(() -> log.info("client disconnected"));
emitter.onTimeout(() -> log.warn("session timeout"));
emitter.onError(err -> log.error("session error", err));

4. 不要在 SSE 通道传文件本体

进度通道传进度元数据，文件本体走单独下载链接：

1
2


SSE 推送 → 任务完成时给一个临时下载 URL
前端拿到 URL → 触发标准下载

不要硬塞 base64 文件到 SSE，体积和性能都差。

5. 限流

SseEmitter 是长连接——大流量场景要限连接数（防止有人开 1 万个连接）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@RestController
public class ExportController {
 private final Semaphore connections = new Semaphore(100); // 最多 100 并发

 @GetMapping("/export/stream")
 public SseEmitter export() {
 if (!connections.tryAcquire()) {
 throw new BusinessException("服务繁忙");
 }
 SseEmitter emitter = new SseEmitter();
 emitter.onCompletion(connections::release);
 emitter.onTimeout(connections::release);
 emitter.onError(e -> connections.release());
 // ...
 return emitter;
 }
}

6. 跨进程任务进度

如果导出任务是异步发到 MQ 或别的进程执行——进度数据要走 Redis：

flowchart LR
 Front --> SSE[SSE Endpoint]
 SSE -. poll .-> Redis[(Redis)]
 Worker[(异步 Worker)] -. write .-> Redis

SSE 通道每秒查一次 Redis 拿进度推给前端，Worker 进度写 Redis。进度生产和消费解耦。

小结

把全文压一句：

HTTP 是请求响应模型，要做"实时进度反馈"，就要打开一个『可以持续推送』的通道——单向选 SSE，双向选 WebSocket，文件本体永远走标准 HTTP 下载。

工程要点：

浏览器原生 progress 能算的进度，别让后端反馈
后端进度反馈优先 SSE
真实进度比假进度重要
Nginx proxy_buffering off 是 SSE 必配
进度和文件本体分离

把这套方案吃透，“导出报表"这种烦人功能能瞬间从 1 星体验变成 5 星。