登录 | 扫码登录 | 对比文档#

核心思路：PC 端生成带唯一标识的二维码，手机端扫码确认后，服务端更新 Redis 状态，PC 端通过 WebSocket 实时感知状态变更并获取 Token。评审重点：二维码状态机的 5 种状态转换是否完整、WebSocket 与长轮询的降级策略是否可靠、安全防御是否覆盖二维码劫持和重放攻击。

一、背景#

用户在 PC 端访问 Web 应用时，输入账号密码是最直接的登录方式。但在以下场景中，扫码登录体验更优：

场景	密码登录的问题	扫码登录的优势
公共电脑	键盘记录器窃取密码	无需输入密码，凭证不经过 PC
移动端已登录	重复输入密码体验差	手机一键确认，零输入
大屏设备	虚拟键盘输入效率低	扫码即登，3 秒完成
安全敏感场景	密码可能泄露	Token 在手机端签发，PC 端不接触凭证

扫码登录的本质是将手机端已有的登录态”转移”到 PC 端，而非重新认证。这要求手机端用户必须已登录——扫码确认时，手机端携带的 Token 证明身份，服务端据此为 PC 端签发新 Token。

二、扫码登录核心流程#

2.1 完整时序#

sequenceDiagram participant PC as PC浏览器 participant Server as 认证服务 participant Redis as Redis participant App as 手机APP Note over PC, App: Phase 1: 生成二维码 PC->>Server: POST /auth/qr-code/generate Server->>Server: 生成 qrCodeId (UUID) Server->>Redis: SET qr_code:{qrCodeId} {status:PENDING, ttl:120s} Server-->>PC: 返回 qrCodeId + 二维码图片URL Note over PC, App: Phase 2: PC端建立WebSocket连接 PC->>Server: WebSocket 连接 /ws/qr-code?qrCodeId=xxx Server->>Redis: GET qr_code:{qrCodeId} Redis-->>Server: status=PENDING Server-->>PC: 当前状态 PENDING Note over PC, App: Phase 3: 手机扫码 App->>Server: POST /auth/qr-code/scan {qrCodeId, accessToken} Server->>Redis: 校验 accessToken 有效性 Server->>Redis: GET qr_code:{qrCodeId} alt 二维码未过期 Server->>Redis: SET qr_code:{qrCodeId} {status:SCANNED, userId:xxx} Server-->>App: 返回确认页面信息（用户昵称、头像） Server->>PC: WebSocket 推送 SCANNED 状态 else 二维码已过期 Server-->>App: 返回二维码已过期 Server->>PC: WebSocket 推送 EXPIRED 状态 end Note over PC, App: Phase 4: 手机确认登录 App->>Server: POST /auth/qr-code/confirm {qrCodeId, accessToken} Server->>Redis: GET qr_code:{qrCodeId} Server->>Redis: SET qr_code:{qrCodeId} {status:CONFIRMED, userId:xxx, pcToken:xxx, pcRefreshToken:xxx} Server-->>App: 返回确认成功 Server->>PC: WebSocket 推送 CONFIRMED 状态 + pcToken Note over PC, App: Phase 5: PC端完成登录 PC->>PC: 存储 Token，跳转首页 Note over PC, App: 异常: 手机取消登录 App->>Server: POST /auth/qr-code/cancel {qrCodeId, accessToken} Server->>Redis: SET qr_code:{qrCodeId} {status:CANCELED} Server->>PC: WebSocket 推送 CANCELED 状态

2.2 二维码状态机#

二维码有 5 种状态，转换关系如下：

1
                    ┌─────────────────────────────────────┐
2
                    │          生成二维码                    │
3
                    │          (PENDING)                    │
4
                    └──────────┬──────────────────────────┘
5
                               │
6
                    ┌──────────▼──────────────────────────┐
7
              ┌─────┤         等待扫码                      │
8
              │     │         (PENDING)                    │
9
              │     └──┬──────────────────┬───────────────┘
10
              │        │                  │
11
              │   ┌────▼─────┐     ┌─────▼──────┐
12
              │   │  超时     │     │  手机扫码    │
13
              │   │ (EXPIRED) │     │ (SCANNED)   │
14
              │   └──────────┘     └──┬───────┬──┘
15
              │                        │       │
16
              │                   ┌────▼──┐ ┌──▼────────┐
17
              │                   │ 确认   │ │  取消      │
18
              │                   │(CONFIRMED)│(CANCELED) │
19
              │                   └────┬──┘ └───────────┘
20
              │                        │
21
              └────────────────────────┘
22
                    (任何非PENDING状态
23
                     均为终态，不可逆)

状态	含义	可转换到	触发条件
`PENDING`	等待扫码	SCANNED / EXPIRED	手机扫码 / 超时
`SCANNED`	已扫码待确认	CONFIRMED / CANCELED / EXPIRED	手机确认 / 手机取消 / 超时
`CONFIRMED`	已确认	—	终态，PC 端获取 Token
`CANCELED`	已取消	—	终态，PC 端提示取消
`EXPIRED`	已过期	—	终态，PC 端提示刷新

关键约束：状态只能单向流转，不可回退。CONFIRMED / CANCELED / EXPIRED 均为终态。

三、方案对比：PC 端如何感知状态变更#

PC 端生成二维码后，需要实时感知”手机已扫码/已确认/已取消”的状态变更。四种主流方案的对比如下：

3.1 方案总览#

维度	短轮询	长轮询	WebSocket	SSE
通信方向	客户端→服务端	客户端→服务端	双向	服务端→客户端
实时性	取决于轮询间隔（1-5s 延迟）	近实时（状态变更即返回）	实时	实时
服务端资源	每次请求都查 Redis	等待期间占用线程	连接建立后无额外请求（NIO不占线程）	同 WebSocket
连接复杂度	无需维持连接	无需维持连接	需维持长连接 + 心跳	需维持长连接
兼容性	全平台	全平台	IE10+，移动端需注意	IE 不支持
断线重连	天然支持（下次轮询即可）	需客户端重发请求	需心跳 + 重连机制	内置重连（EventSource）
防火墙/代理	无问题	部分代理提前返回	可能被拦截	可能被拦截
实现复杂度	★☆☆	★★☆	★★★	★★☆

3.2 资源消耗对比#

以 10,000 个并发等待扫码的 PC 端为例：

方案	每秒请求数	线程占用	Redis 查询次数/秒	带宽消耗
短轮询 (2s 间隔)	5,000 QPS	低（请求即释放）	5,000 次	高（频繁 HTTP 头）
长轮询 (30s 超时)	~333 QPS	中（hold 线程）	~333 次	低
WebSocket	0（仅心跳）	低（NIO 不占线程）	仅状态变更时	极低
SSE	0（仅心跳）	低	仅状态变更时	极低

3.3 方案选型结论#

1
┌──────────────────────────────────────────────────────────────────┐
2
│                    扫码登录方案选择决策树                            │
3
├──────────────────────────────────────────────────────────────────┤
4
│                                                                   │
5
│  企业级首选：WebSocket                                             │
6
│  └── 实时性最好，资源占用最低，体验最佳                            │
7
│                                                                   │
8
│  降级方案：长轮询                                                  │
9
│  └── WebSocket 连接失败时自动降级，保证兼容性                      │
10
│                                                                   │
11
│  快速验证：短轮询                                                  │
12
│  └── 实现简单，适合原型验证                                        │
13
│                                                                   │
14
│  需兼容旧浏览器：短轮询 + 长轮询                                    │
15
│  └── 最差体验，最强兼容性                                          │
16
│                                                                   │
17
│  企业级推荐：WebSocket 为主 + 长轮询降级                            │
18
│  └── 优先 WebSocket，连接失败自动降级为长轮询                       │
19
│                                                                   │
20
└──────────────────────────────────────────────────────────────────┘

本文选择 WebSocket 为主方案，长轮询为降级方案，原因：

实时性最好，状态变更立即推送
资源占用最低，NIO 不占用 Servlet 线程
用户体验最佳，无延迟感
长轮询降级保证兼容性

四、后端实现：基于 Spring Boot + Redis#

4.1 Maven 依赖配置#

1
<parent>
2
    <groupId>org.springframework.boot</groupId>
3
    <artifactId>spring-boot-starter-parent</artifactId>
4
    <version>3.2.0</version>
5
    <relativePath/>
6
</parent>
7

8
<dependencies>
9
    <!-- WebSocket 支持 -->
10
    <dependency>
11
        <groupId>org.springframework.boot</groupId>
12
        <artifactId>spring-boot-starter-websocket</artifactId>
13
    </dependency>
14

15
    <!-- Redis 支持 -->
16
    <dependency>
17
        <groupId>org.springframework.boot</groupId>
18
        <artifactId>spring-boot-starter-data-redis</artifactId>
19
    </dependency>
20

21
    <!-- Web 支持 -->
22
    <dependency>
23
        <groupId>org.springframework.boot</groupId>
24
        <artifactId>spring-boot-starter-web</artifactId>
25
    </dependency>
26

27
    <!-- JWT 支持 -->
28
    <dependency>
29
        <groupId>io.jsonwebtoken</groupId>
30
        <artifactId>jjwt-api</artifactId>
31
        <version>0.12.3</version>
32
    </dependency>
33
    <dependency>
34
        <groupId>io.jsonwebtoken</groupId>
35
        <artifactId>jjwt-impl</artifactId>
36
        <version>0.12.3</version>
37
        <scope>runtime</scope>
38
    </dependency>
39
    <dependency>
40
        <groupId>io.jsonwebtoken</groupId>
41
        <artifactId>jjwt-jackson</artifactId>
42
        <version>0.12.3</version>
43
        <scope>runtime</scope>
44
    </dependency>
45

46
    <!-- Lombok -->
47
    <dependency>
48
        <groupId>org.projectlombok</groupId>
49
        <artifactId>lombok</artifactId>
50
        <optional>true</optional>
51
    </dependency>
52

53
    <!-- Swagger/OpenAPI -->
54
    <dependency>
55
        <groupId>org.springdoc</groupId>
56
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
57
        <version>2.3.0</version>
58
    </dependency>
59
</dependencies>

4.2 数据模型#

1
@Data
2
@Builder
3
@NoArgsConstructor
4
@AllArgsConstructor
5
public class QrCodeStatus {
6
    private String qrCodeId;
7
    private QrCodeStatusEnum status;
8
    private Long userId;
9
    private String nickname;
10
    private String avatar;
11
    private String pcAccessToken;
12
    private String pcRefreshToken;
13
    private LocalDateTime createdAt;
14
    private LocalDateTime expireAt;
15
}

1
public enum QrCodeStatusEnum {
2
    PENDING(0, "等待扫码"),
3
    SCANNED(1, "已扫码待确认"),
4
    CONFIRMED(2, "已确认"),
5
    CANCELED(3, "已取消"),
6
    EXPIRED(4, "已过期");
7

8
    private final int code;
9
    private final String desc;
10
}

4.2 Redis 存储设计#

Key	类型	TTL	说明
`qr_code:{qrCodeId}`	Hash	120s	二维码状态数据
`qr_code:scan_lock:{qrCodeId}`	String (NX)	120s	扫码操作分布式锁，防并发扫码

Hash 字段：

Field	说明
`status`	状态码（0-4）
`userId`	扫码用户 ID
`nickname`	扫码用户昵称
`avatar`	扫码用户头像
`pcAccessToken`	PC 端访问 Token
`pcRefreshToken`	PC 端刷新 Token
`createdAt`	创建时间戳

4.3 WebSocket 配置#

1
@Configuration
2
@EnableWebSocket
3
public class WebSocketConfig implements WebSocketConfigurer {
4

5
    private final QrCodeWebSocketHandler qrCodeWebSocketHandler;
6

7
    @Override
8
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
9
        registry.addHandler(qrCodeWebSocketHandler, "/ws/qr-code")
10
                .setAllowedOrigins("*");
11
    }
12
}

1
@Component
2
public class QrCodeWebSocketHandler extends TextWebSocketHandler {
3

4
    private final ConcurrentHashMap<String, WebSocketSession> sessions = new ConcurrentHashMap<>();
5
    private final RedisService redisService;
6

7
    private static final String QR_CODE_KEY_PREFIX = "qr_code:";
8

9
    @Override
10
    public void afterConnectionEstablished(WebSocketSession session) throws Exception {
11
        String qrCodeId = getQrCodeId(session);
12
        if (qrCodeId == null) {
13
            session.close();
14
            return;
15
        }
16

17
        sessions.put(qrCodeId, session);
18

19
        QrCodeStatus current = getQrCodeStatusFromRedis(qrCodeId);
20
        if (current != null) {
21
            sendStatus(session, current);
22
        }
23
    }
24

25
    @Override
26
    public void afterConnectionClosed(WebSocketSession session, CloseStatus status) throws Exception {
27
        String qrCodeId = getQrCodeId(session);
28
        if (qrCodeId != null) {
29
            sessions.remove(qrCodeId);
30
        }
31
    }
32

33
    public void pushStatusUpdate(String qrCodeId, QrCodeStatus status) {
34
        WebSocketSession session = sessions.get(qrCodeId);
35
        if (session != null && session.isOpen()) {
36
            sendStatus(session, status);
37
        }
38
    }
39

40
    private void sendStatus(WebSocketSession session, QrCodeStatus status) {
41
        try {
42
            ObjectMapper mapper = new ObjectMapper();
43
            session.sendMessage(new TextMessage(mapper.writeValueAsString(buildResponse(status))));
44
        } catch (Exception e) {
45
            e.printStackTrace();
46
        }
47
    }
48

49
    private QrCodeStatusResponse buildResponse(QrCodeStatus status) {
50
        return QrCodeStatusResponse.builder()
51
                .qrCodeId(status.getQrCodeId())
52
                .status(status.getStatus())
53
                .userId(status.getUserId())
54
                .nickname(status.getNickname())
55
                .avatar(status.getAvatar())
56
                .pcAccessToken(status.getPcAccessToken())
57
                .pcRefreshToken(status.getPcRefreshToken())
58
                .build();
59
    }
60

61
    private String getQrCodeId(WebSocketSession session) {
62
        String query = session.getUri().getQuery();
63
        if (query == null) return null;
64
        for (String param : query.split("&")) {
65
            String[] pair = param.split("=");
66
            if ("qrCodeId".equals(pair[0])) {
67
                return pair[1];
68
            }
69
        }
70
        return null;
71
    }
72

73
    private QrCodeStatus getQrCodeStatusFromRedis(String qrCodeId) {
74
        String key = QR_CODE_KEY_PREFIX + qrCodeId;
75
        Map<String, String> hash = redisService.hGetAll(key);
76
        if (hash == null || hash.isEmpty()) {
77
            return null;
78
        }
79
        return QrCodeStatus.builder()
80
                .qrCodeId(qrCodeId)
81
                .status(QrCodeStatusEnum.fromCode(Integer.parseInt(hash.get("status"))))
82
                .userId(hash.containsKey("userId") ? Long.parseLong(hash.get("userId")) : null)
83
                .nickname(hash.get("nickname"))
84
                .avatar(hash.get("avatar"))
85
                .pcAccessToken(hash.get("pcAccessToken"))
86
                .pcRefreshToken(hash.get("pcRefreshToken"))
87
                .build();
88
    }
89
}

4.4 生成二维码#

1
@Service
2
@RequiredArgsConstructor
3
@Slf4j
4
public class QrCodeLoginServiceImpl implements QrCodeLoginService {
5

6
    private final RedisService redisService;
7
    private final JwtUtils jwtUtils;
8
    private final QrCodeWebSocketHandler webSocketHandler;
9

10
    private static final long QR_CODE_TTL_SECONDS = 120;
11
    private static final String QR_CODE_KEY_PREFIX = "qr_code:";
12
    private static final String QR_CODE_SCAN_LOCK_PREFIX = "qr_code:scan_lock:";
13

14
    @Override
15
    public QrCodeGenerateResponse generate() {
16
        String qrCodeId = UUID.randomUUID().toString().replace("-", "");
17

18
        QrCodeStatus status = QrCodeStatus.builder()
19
                .qrCodeId(qrCodeId)
20
                .status(QrCodeStatusEnum.PENDING)
21
                .createdAt(LocalDateTime.now())
22
                .expireAt(LocalDateTime.now().plusSeconds(QR_CODE_TTL_SECONDS))
23
                .build();
24

25
        String key = QR_CODE_KEY_PREFIX + qrCodeId;
26
        Map<String, String> hash = new HashMap<>();
27
        hash.put("status", String.valueOf(QrCodeStatusEnum.PENDING.getCode()));
28
        hash.put("createdAt", String.valueOf(System.currentTimeMillis()));
29
        redisService.hPutAll(key, hash);
30
        redisService.expire(key, QR_CODE_TTL_SECONDS, TimeUnit.SECONDS);
31

32
        String qrCodeUrl = buildQrCodeUrl(qrCodeId);
33

34
        return QrCodeGenerateResponse.builder()
35
                .qrCodeId(qrCodeId)
36
                .qrCodeUrl(qrCodeUrl)
37
                .expireIn(QR_CODE_TTL_SECONDS)
38
                .build();
39
    }
40

41
    private String buildQrCodeUrl(String qrCodeId) {
42
        return "https://your-domain.com/scan?qrCodeId=" + qrCodeId;
43
    }

4.5 手机扫码#

1
    @Override
2
    public QrCodeScanResponse scan(String qrCodeId, String accessToken) {
3
        Long userId = jwtUtils.getUserIdAsLong(accessToken);
4
        String lockKey = QR_CODE_SCAN_LOCK_PREFIX + qrCodeId;
5

6
        Boolean locked = redisService.setIfAbsent(lockKey, String.valueOf(userId), 5, TimeUnit.SECONDS);
7
        if (Boolean.FALSE.equals(locked)) {
8
            throw new AuthException("二维码正在被其他设备处理，请稍后重试");
9
        }
10

11
        try {
12
            String key = QR_CODE_KEY_PREFIX + qrCodeId;
13
            Map<String, String> hash = redisService.hGetAll(key);
14

15
            if (hash == null || hash.isEmpty()) {
16
                QrCodeStatus expiredStatus = QrCodeStatus.builder()
17
                        .qrCodeId(qrCodeId)
18
                        .status(QrCodeStatusEnum.EXPIRED)
19
                        .build();
20
                webSocketHandler.pushStatusUpdate(qrCodeId, expiredStatus);
21
                throw new AuthException("二维码已过期，请刷新重试");
22
            }
23

24
            QrCodeStatusEnum currentStatus = QrCodeStatusEnum.fromCode(
25
                    Integer.parseInt(hash.get("status")));
26

27
            if (currentStatus == QrCodeStatusEnum.SCANNED) {
28
                Long existUserId = Long.parseLong(hash.get("userId"));
29
                if (!existUserId.equals(userId)) {
30
                    throw new AuthException("该二维码已被其他用户扫描");
31
                }
32
                return QrCodeScanResponse.alreadyScanned();
33
            }
34

35
            if (currentStatus != QrCodeStatusEnum.PENDING) {
36
                throw new AuthException("二维码状态异常: " + currentStatus.getDesc());
37
            }
38

39
            hash.put("status", String.valueOf(QrCodeStatusEnum.SCANNED.getCode()));
40
            hash.put("userId", String.valueOf(userId));
41
            SysUserApi user = remoteUserService.getUserById(userId);
42
            hash.put("nickname", user.getNickName());
43
            hash.put("avatar", user.getAvatar());
44
            redisService.hPutAll(key, hash);
45
            redisService.expire(key, 60, TimeUnit.SECONDS);
46

47
            QrCodeStatus scannedStatus = QrCodeStatus.builder()
48
                    .qrCodeId(qrCodeId)
49
                    .status(QrCodeStatusEnum.SCANNED)
50
                    .userId(userId)
51
                    .nickname(user.getNickName())
52
                    .avatar(user.getAvatar())
53
                    .build();
54
            webSocketHandler.pushStatusUpdate(qrCodeId, scannedStatus);
55

56
            return QrCodeScanResponse.builder()
57
                    .qrCodeId(qrCodeId)
58
                    .nickname(user.getNickName())
59
                    .avatar(user.getAvatar())
60
                    .build();
61
        } finally {
62
            redisService.deleteObject(lockKey);
63
        }
64
    }

4.7 手机确认登录#

1
    @Override
2
    public QrCodeConfirmResponse confirm(String qrCodeId, String accessToken) {
3
        Long userId = jwtUtils.getUserIdAsLong(accessToken);
4

5
        String key = QR_CODE_KEY_PREFIX + qrCodeId;
6
        Map<String, String> hash = redisService.hGetAll(key);
7

8
        if (hash == null || hash.isEmpty()) {
9
            QrCodeStatus expiredStatus = QrCodeStatus.builder()
10
                    .qrCodeId(qrCodeId)
11
                    .status(QrCodeStatusEnum.EXPIRED)
12
                    .build();
13
            webSocketHandler.pushStatusUpdate(qrCodeId, expiredStatus);
14
            throw new AuthException("二维码已过期");
15
        }
16

17
        QrCodeStatusEnum currentStatus = QrCodeStatusEnum.fromCode(
18
                Integer.parseInt(hash.get("status")));
19

20
        if (currentStatus != QrCodeStatusEnum.SCANNED) {
21
            throw new AuthException("二维码状态异常，当前状态: " + currentStatus.getDesc());
22
        }
23

24
        Long scannedUserId = Long.parseLong(hash.get("userId"));
25
        if (!scannedUserId.equals(userId)) {
26
            throw new AuthException("确认用户与扫码用户不一致");
27
        }
28

29
        Map<String, Object> claims = new HashMap<>();
30
        claims.put(SecurityConstants.USER_ID, userId);
31
        claims.put(SecurityConstants.USER_NAME, hash.get("nickname"));
32
        claims.put("token_type", "access");
33
        String pcAccessToken = jwtUtils.createToken(claims);
34

35
        String refreshToken = jwtUtils.createRefreshToken(userId);
36

37
        String accessTokenKey = CacheConstants.CACHE_LOGIN_TOKEN + userId;
38
        String refreshTokenKey = CacheConstants.CACHE_LOGIN_REFRESH + userId;
39
        redisService.setSetCacheObject(accessTokenKey, pcAccessToken);
40
        redisService.expire(accessTokenKey, SecurityConstants.TOKEN_EXPIRE, TimeUnit.MINUTES);
41
        redisService.setSetCacheObject(refreshTokenKey, refreshToken);
42
        redisService.expire(refreshTokenKey, SecurityConstants.REFRESH_TOKEN_EXPIRE, TimeUnit.DAYS);
43

44
        hash.put("status", String.valueOf(QrCodeStatusEnum.CONFIRMED.getCode()));
45
        hash.put("pcAccessToken", pcAccessToken);
46
        hash.put("pcRefreshToken", refreshToken);
47
        redisService.hPutAll(key, hash);
48

49
        QrCodeStatus confirmedStatus = QrCodeStatus.builder()
50
                .qrCodeId(qrCodeId)
51
                .status(QrCodeStatusEnum.CONFIRMED)
52
                .userId(userId)
53
                .nickname(hash.get("nickname"))
54
                .avatar(hash.get("avatar"))
55
                .pcAccessToken(pcAccessToken)
56
                .pcRefreshToken(refreshToken)
57
                .build();
58
        webSocketHandler.pushStatusUpdate(qrCodeId, confirmedStatus);
59

60
        redisService.deleteObject(key);
61

62
        return QrCodeConfirmResponse.success(qrCodeId);
63
    }

4.8 手机取消登录#

1
    @Override
2
    public void cancel(String qrCodeId, String accessToken) {
3
        Long userId = jwtUtils.getUserIdAsLong(accessToken);
4

5
        String key = QR_CODE_KEY_PREFIX + qrCodeId;
6
        Map<String, String> hash = redisService.hGetAll(key);
7

8
        if (hash == null || hash.isEmpty()) {
9
            QrCodeStatus expiredStatus = QrCodeStatus.builder()
10
                    .qrCodeId(qrCodeId)
11
                    .status(QrCodeStatusEnum.EXPIRED)
12
                    .build();
13
            webSocketHandler.pushStatusUpdate(qrCodeId, expiredStatus);
14
            return;
15
        }
16

17
        QrCodeStatusEnum currentStatus = QrCodeStatusEnum.fromCode(
18
                Integer.parseInt(hash.get("status")));
19

20
        if (currentStatus != QrCodeStatusEnum.SCANNED) {
21
            return;
22
        }
23

24
        Long scannedUserId = Long.parseLong(hash.get("userId"));
25
        if (!scannedUserId.equals(userId)) {
26
            throw new AuthException("取消用户与扫码用户不一致");
27
        }
28

29
        hash.put("status", String.valueOf(QrCodeStatusEnum.CANCELED.getCode()));
30
        redisService.hPutAll(key, hash);
31

32
        QrCodeStatus canceledStatus = QrCodeStatus.builder()
33
                .qrCodeId(qrCodeId)
34
                .status(QrCodeStatusEnum.CANCELED)
35
                .userId(userId)
36
                .build();
37
        webSocketHandler.pushStatusUpdate(qrCodeId, canceledStatus);
38
    }

4.9 长轮询降级实现#

1
    @Override
2
    public QrCodeStatusResponse getStatus(String qrCodeId, long timeoutSeconds) {
3
        long startTime = System.currentTimeMillis();
4
        long timeoutMillis = TimeUnit.SECONDS.toMillis(Math.min(timeoutSeconds, 25));
5

6
        while (System.currentTimeMillis() - startTime < timeoutMillis) {
7
            QrCodeStatus status = getQrCodeStatusFromRedis(qrCodeId);
8

9
            if (status == null) {
10
                return QrCodeStatusResponse.expired(qrCodeId);
11
            }
12

13
            if (status.getStatus() != QrCodeStatusEnum.PENDING) {
14
                return buildResponse(status);
15
            }
16

17
            try {
18
                Thread.sleep(500);
19
            } catch (InterruptedException e) {
20
                Thread.currentThread().interrupt();
21
                return buildResponse(status);
22
            }
23
        }
24

25
        QrCodeStatus status = getQrCodeStatusFromRedis(qrCodeId);
26
        if (status == null) {
27
            return QrCodeStatusResponse.expired(qrCodeId);
28
        }
29
        return buildResponse(status);
30
    }
31

32
    private QrCodeStatusResponse buildResponse(QrCodeStatus status) {
33
        return QrCodeStatusResponse.builder()
34
                .qrCodeId(status.getQrCodeId())
35
                .status(status.getStatus())
36
                .userId(status.getUserId())
37
                .nickname(status.getNickname())
38
                .avatar(status.getAvatar())
39
                .pcAccessToken(status.getPcAccessToken())
40
                .pcRefreshToken(status.getPcRefreshToken())
41
                .build();
42
    }
43

44
    private QrCodeStatus getQrCodeStatusFromRedis(String qrCodeId) {
45
        String key = QR_CODE_KEY_PREFIX + qrCodeId;
46
        Map<String, String> hash = redisService.hGetAll(key);
47
        if (hash == null || hash.isEmpty()) {
48
            return null;
49
        }
50
        return QrCodeStatus.builder()
51
                .qrCodeId(qrCodeId)
52
                .status(QrCodeStatusEnum.fromCode(Integer.parseInt(hash.get("status"))))
53
                .userId(hash.containsKey("userId") ? Long.parseLong(hash.get("userId")) : null)
54
                .nickname(hash.get("nickname"))
55
                .avatar(hash.get("avatar"))
56
                .pcAccessToken(hash.get("pcAccessToken"))
57
                .pcRefreshToken(hash.get("pcRefreshToken"))
58
                .build();
59
    }
60
}

4.10 Controller 层#

1
@RestController
2
@RequestMapping("/auth/qr-code")
3
@RequiredArgsConstructor
4
@Tag(name = "扫码登录")
5
public class QrCodeLoginController {
6

7
    private final QrCodeLoginService qrCodeLoginService;
8

9
    @Operation(summary = "生成二维码")
10
    @PostMapping("/generate")
11
    public R<QrCodeGenerateResponse> generate() {
12
        return R.ok(qrCodeLoginService.generate());
13
    }
14

15
    @Operation(summary = "查询二维码状态（长轮询降级）")
16
    @GetMapping("/status")
17
    public R<QrCodeStatusResponse> getStatus(
18
            @RequestParam String qrCodeId,
19
            @RequestParam(defaultValue = "25") long timeout) {
20
        return R.ok(qrCodeLoginService.getStatus(qrCodeId, timeout));
21
    }
22

23
    @Operation(summary = "手机扫码")
24
    @PostMapping("/scan")
25
    public R<QrCodeScanResponse> scan(
26
            @RequestParam String qrCodeId,
27
            @RequestHeader(SecurityConstants.AUTHORIZATION_HEADER) String authorization) {
28
        String accessToken = authorization.replace(SecurityConstants.TOKEN_PREFIX, "");
29
        return R.ok(qrCodeLoginService.scan(qrCodeId, accessToken));
30
    }
31

32
    @Operation(summary = "手机确认登录")
33
    @PostMapping("/confirm")
34
    public R<QrCodeConfirmResponse> confirm(
35
            @RequestParam String qrCodeId,
36
            @RequestHeader(SecurityConstants.AUTHORIZATION_HEADER) String authorization) {
37
        String accessToken = authorization.replace(SecurityConstants.TOKEN_PREFIX, "");
38
        return R.ok(qrCodeLoginService.confirm(qrCodeId, accessToken));
39
    }
40

41
    @Operation(summary = "手机取消登录")
42
    @PostMapping("/cancel")
43
    public R<Void> cancel(
44
            @RequestParam String qrCodeId,
45
            @RequestHeader(SecurityConstants.AUTHORIZATION_HEADER) String authorization) {
46
        String accessToken = authorization.replace(SecurityConstants.TOKEN_PREFIX, "");
47
        qrCodeLoginService.cancel(qrCodeId, accessToken);
48
        return R.ok();
49
    }
50
}

4.11 Gateway 白名单#

1
security:
2
  ignore:
3
    whites:
4
      - /api/auth/qr-code/generate
5
      - /api/auth/qr-code/status
6
      - /ws/qr-code/**

/scan、/confirm、/cancel 不在白名单中——手机端必须携带有效 Token 才能操作。

五、前端实现#

5.1 PC 端：二维码展示 + WebSocket#

1
import { ref, onMounted, onUnmounted } from 'vue'
2
import { useRouter } from 'vue-router'
3
import { useUserStore } from '@/stores/user'
4
import { qrCodeApi } from '@/api/auth'
5

6
type QrCodeStatus = 'PENDING' | 'SCANNED' | 'CONFIRMED' | 'CANCELED' | 'EXPIRED'
7

8
interface QrCodeStatusResponse {
9
  qrCodeId: string
10
  status: QrCodeStatus
11
  userId?: number
12
  nickname?: string
13
  avatar?: string
14
  pcAccessToken?: string
15
  pcRefreshToken?: string
16
}
17

18
export function useQrCodeLogin() {
19
  const router = useRouter()
20
  const userStore = useUserStore()
21

22
  const qrCodeId = ref('')
23
  const qrCodeUrl = ref('')
24
  const status = ref<QrCodeStatus>('PENDING')
25
  const scannedUser = ref<{ nickname: string; avatar: string } | null>(null)
26
  const countdown = ref(0)
27
  const loading = ref(false)
28
  const useFallback = ref(false)
29

30
  let ws: WebSocket | null = null
31
  let countdownTimer: ReturnType<typeof setInterval> | null = null
32
  let reconnectAttempts = 0
33
  const MAX_RECONNECT = 3
34
  let pollTimer: ReturnType<typeof setTimeout> | null = null
35

36
  async function generateQrCode() {
37
    loading.value = true
38
    try {
39
      const res = await qrCodeApi.generate()
40
      qrCodeId.value = res.data.qrCodeId
41
      qrCodeUrl.value = res.data.qrCodeUrl
42
      countdown.value = res.data.expireIn
43
      status.value = 'PENDING'
44
      scannedUser.value = null
45
      useFallback.value = false
46
      reconnectAttempts = 0
47
      startCountdown()
48
      connectWs()
49
    } finally {
50
      loading.value = false
51
    }
52
  }
53

54
  function connectWs() {
55
    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
56
    const wsUrl = `${protocol}//${window.location.host}/ws/qr-code?qrCodeId=${qrCodeId.value}`
57
    ws = new WebSocket(wsUrl)
58

59
    ws.onopen = () => {
60
      reconnectAttempts = 0
61
    }
62

63
    ws.onmessage = (event) => {
64
      const data: QrCodeStatusResponse = JSON.parse(event.data)
65
      handleStatusUpdate(data)
66
    }
67

68
    ws.onclose = () => {
69
      if (status.value === 'CONFIRMED' || status.value === 'CANCELED' || status.value === 'EXPIRED') {
70
        return
71
      }
72

73
      if (reconnectAttempts < MAX_RECONNECT) {
74
        reconnectAttempts++
75
        setTimeout(() => connectWs(), 2000 * reconnectAttempts)
76
      } else {
77
        fallbackToPolling()
78
      }
79
    }
80

81
    ws.onerror = () => {
82
      ws?.close()
83
    }
84
  }
85

86
  function fallbackToPolling() {
87
    useFallback.value = true
88
    startPolling()
89
  }
90

91
  async function startPolling() {
92
    if (status.value === 'CONFIRMED' || status.value === 'CANCELED' || status.value === 'EXPIRED') {
93
      return
94
    }
95

96
    try {
97
      const res = await qrCodeApi.getStatus(qrCodeId.value, 25)
98
      handleStatusUpdate(res.data)
99
    } catch {
100
    } finally {
101
      if (useFallback.value && status.value === 'PENDING') {
102
        pollTimer = setTimeout(() => startPolling(), 2000)
103
      }
104
    }
105
  }
106

107
  function handleStatusUpdate(data: QrCodeStatusResponse) {
108
    status.value = data.status
109

110
    switch (data.status) {
111
      case 'SCANNED':
112
        scannedUser.value = { nickname: data.nickname!, avatar: data.avatar! }
113
        break
114
      case 'CONFIRMED':
115
        handleLoginSuccess(data)
116
        break
117
      case 'CANCELED':
118
      case 'EXPIRED':
119
        break
120
    }
121
  }
122

123
  function handleLoginSuccess(data: QrCodeStatusResponse) {
124
    if (data.pcAccessToken) {
125
      document.cookie = `access_token=${data.pcAccessToken}; path=/; max-age=1800; SameSite=Lax; ${window.location.protocol === 'https:' ? 'Secure;' : ''}`
126
    }
127
    if (data.pcRefreshToken) {
128
      document.cookie = `refresh_token=${data.pcRefreshToken}; path=/; max-age=2592000; SameSite=Lax; ${window.location.protocol === 'https:' ? 'Secure;' : ''}`
129
    }
130
    userStore.setUserInfo({ accessToken: data.pcAccessToken! })
131
    router.push('/dashboard')
132
  }
133

134
  function startCountdown() {
135
    if (countdownTimer) clearInterval(countdownTimer)
136
    countdownTimer = setInterval(() => {
137
      countdown.value--
138
      if (countdown.value <= 0) {
139
        status.value = 'EXPIRED'
140
        cleanup()
141
      }
142
    }, 1000)
143
  }
144

145
  function cleanup() {
146
    if (ws) {
147
      ws.close()
148
      ws = null
149
    }
150
    if (pollTimer) {
151
      clearTimeout(pollTimer)
152
      pollTimer = null
153
    }
154
    if (countdownTimer) {
155
      clearInterval(countdownTimer)
156
      countdownTimer = null
157
    }
158
  }
159

160
  function refreshQrCode() {
161
    cleanup()
162
    generateQrCode()
163
  }
164

165
  onMounted(() => generateQrCode())
166
  onUnmounted(() => cleanup())
167

168
  return {
169
    qrCodeId, qrCodeUrl, status, scannedUser, countdown, loading,
170
    useFallback, refreshQrCode
171
  }
172
}

5.2 PC 端：Vue 组件#

1
<template>
2
  <div class="qr-login">
3
    <div v-if="status === 'PENDING'" class="qr-pending">
4
      <QrCodeCanvas :value="qrCodeUrl" :size="200" />
5
      <p>请使用手机 APP 扫描二维码登录</p>
6
      <span class="countdown">{{ countdown }}s 后过期</span>
7
      <span v-if="useFallback" class="fallback">当前使用降级连接</span>
8
    </div>
9

10
    <div v-else-if="status === 'SCANNED'" class="qr-scanned">
11
      <Avatar :src="scannedUser?.avatar" :size="48" />
12
      <p>{{ scannedUser?.nickname }} 已扫码</p>
13
      <p>请在手机上确认登录</p>
14
    </div>
15

16
    <div v-else-if="status === 'CONFIRMED'" class="qr-confirmed">
17
      <CheckCircleFilled style="font-size: 48px; color: #52c41a" />
18
      <p>登录成功，正在跳转...</p>
19
    </div>
20

21
    <div v-else-if="status === 'CANCELED'" class="qr-canceled">
22
      <CloseCircleFilled style="font-size: 48px; color: #ff4d4f" />
23
      <p>登录已取消</p>
24
      <Button type="primary" @click="refreshQrCode">重新扫码</Button>
25
    </div>
26

27
    <div v-else-if="status === 'EXPIRED'" class="qr-expired">
28
      <QrCodeCanvas :value="qrCodeUrl" :size="200" level="L" :fg-color="#d9d9d9" />
29
      <p>二维码已过期</p>
30
      <Button type="primary" @click="refreshQrCode">刷新二维码</Button>
31
    </div>
32
  </div>
33
</template>
34

35
<script setup lang="ts">
36
import { QrCodeCanvas } from 'qrcode.react'
37
import { useQrCodeLogin } from '@/composables/useQrCodeLogin'
38

39
const {
40
  qrCodeUrl, status, scannedUser, countdown, loading, useFallback, refreshQrCode
41
} = useQrCodeLogin()
42
</script>
43

44
<style scoped>
45
.fallback {
46
  font-size: 12px;
47
  color: #999;
48
  margin-top: 8px;
49
}
50
</style>

5.3 手机端：扫码 + 确认流程#

1
export function useScanLogin() {
2
  const router = useRouter()
3
  const confirmLoading = ref(false)
4
  const scanResult = ref<QrCodeScanResponse | null>(null)
5

6
  async function scanQrCode(qrCodeId: string) {
7
    try {
8
      const res = await qrCodeApi.scan(qrCodeId)
9
      scanResult.value = res.data
10
    } catch (error: any) {
11
      if (error.response?.data?.msg?.includes('已过期')) {
12
        showToast('二维码已过期，请在 PC 端刷新')
13
      } else if (error.response?.data?.msg?.includes('已被其他用户')) {
14
        showToast('该二维码已被其他用户扫描')
15
      } else {
16
        showToast('扫码失败，请重试')
17
      }
18
      router.back()
19
    }
20
  }
21

22
  async function confirmLogin(qrCodeId: string) {
23
    confirmLoading.value = true
24
    try {
25
      await qrCodeApi.confirm(qrCodeId)
26
      showToast('登录成功')
27
      router.back()
28
    } catch {
29
      showToast('确认失败，请重试')
30
    } finally {
31
      confirmLoading.value = false
32
    }
33
  }
34

35
  async function cancelLogin(qrCodeId: string) {
36
    try {
37
      await qrCodeApi.cancel(qrCodeId)
38
      router.back()
39
    } catch {
40
      router.back()
41
    }
42
  }
43

44
  return { scanResult, confirmLoading, scanQrCode, confirmLogin, cancelLogin }
45
}

5.4 手机端：确认页面组件#

1
<template>
2
  <div class="scan-confirm">
3
    <div class="user-info">
4
      <Avatar :src="scanResult?.avatar" :size="64" />
5
      <p class="nickname">{{ scanResult?.nickname }}</p>
6
    </div>
7

8
    <div class="confirm-text">
9
      <p>确认登录 Web 端？</p>
10
    </div>
11

12
    <div class="actions">
13
      <Button block @click="cancelLogin(qrCodeId)">取消</Button>
14
      <Button block type="primary" :loading="confirmLoading" @click="confirmLogin(qrCodeId)">
15
        确认登录
16
      </Button>
17
    </div>
18

19
    <p class="tip">确认后，PC 端将自动登录您的账号</p>
20
  </div>
21
</template>
22

23
<script setup lang="ts">
24
import { useRoute } from 'vue-router'
25
import { useScanLogin } from '@/composables/useScanLogin'
26

27
const route = useRoute()
28
const qrCodeId = route.query.qrCodeId as string
29

30
const { scanResult, confirmLoading, scanQrCode, confirmLogin, cancelLogin } = useScanLogin()
31

32
onMounted(() => scanQrCode(qrCodeId))
33
</script>

六、安全防御#

6.1 威胁模型#

攻击类型	攻击方式	影响
二维码劫持	攻击者生成自己的二维码，诱导用户扫描	用户登录到攻击者会话
二维码替换	攻击者替换页面上的二维码图片	同上
重放攻击	截获确认请求重放	重复登录
暴力扫码	脚本遍历 qrCodeId 尝试扫码	占用资源，可能撞到有效二维码
CSRF 扫码	跨站请求触发扫码/确认	非授权操作
中间人攻击	HTTP 明文截获 Token	Token 泄露
WebSocket 劫持	劫持 WebSocket 连接获取状态推送	非授权获取状态变更

6.2 防御措施#

1）二维码劫持防御

二维码 URL 中不包含任何敏感信息，仅包含 qrCodeId。攻击者即使生成自己的二维码，也无法获取受害者的 Token——因为 Token 是服务端根据扫码用户的身份签发的，与二维码本身无关。

1
攻击者生成 qrCodeId=attacker123 → 诱导用户扫描
2
→ 用户扫码后，服务端将 attacker123 的状态设为 SCANNED + userId=受害者
3
→ 攻击者 PC 端 WebSocket 连接 attacker123 → 获取到受害者的 Token
4

5
防御：Token 不直接写入 Redis Hash，而是在状态变更时
6
      临时生成并立即通过 WebSocket 推送，推送后立即删除
7
      同时校验 WebSocket 连接的同源性

关键防御：WebSocket 连接校验 Origin，确保只有同源页面能连接。

1
@Override
2
public void afterConnectionEstablished(WebSocketSession session) throws Exception {
3
    String origin = session.getHandshakeHeaders().getOrigin();
4
    if (!isValidOrigin(origin)) {
5
        session.close();
6
        return;
7
    }
8
    // ...
9
}

2）暴力扫码防御

qrCodeId 使用 UUID v4（128 位随机），暴力遍历的概率极低。额外限制：

1
@PostMapping("/scan")
2
@RateLimit(resource = "auth:qr-code:scan", key = "#accessToken", count = 10, timeUnit = TimeUnit.MINUTES)
3
public R<QrCodeScanResponse> scan(...) { }

3）分布式锁防并发扫码

同一个 qrCodeId 同时只能被一个用户扫码。使用 Redis SET NX 实现分布式锁：

1
String lockKey = QR_CODE_SCAN_LOCK_PREFIX + qrCodeId;
2
Boolean locked = redisService.setIfAbsent(lockKey, String.valueOf(userId), 5, TimeUnit.SECONDS);
3
if (Boolean.FALSE.equals(locked)) {
4
    throw new AuthException("二维码正在被其他设备处理");
5
}

4）Token 不经过手机端传输

确认登录时，服务端直接为 PC 端签发 Token，Token 通过 WebSocket 推送返回。手机端只接收”确认成功/失败”的结果，不接触 PC 端的 Token。

5）WSS 强制

生产环境 WebSocket 必须使用 wss://，所有接口必须走 HTTPS，防止中间人截获 Token。

6.3 安全措施汇总#

威胁	防御措施	防御效果
二维码劫持	Origin 校验 + Token 即时推送即时删除	✅ 攻击者无法获取他人 Token
二维码替换	二维码由服务端生成，前端不缓存	✅ 每次刷新都是新二维码
重放攻击	HTTPS + 请求签名 + qrCodeId 一次性	✅ 确认后二维码状态不可逆
暴力扫码	UUID v4 + RateLimit + 分布式锁	✅ 遍历空间 2^128，限流 10次/分钟
CSRF 扫码	手机端需 Authorization Header	✅ 跨站请求无法携带 Token
中间人攻击	WSS + HTTPS + Secure Cookie	✅ 传输加密
WebSocket 劫持	Origin 校验 + 连接 ID 绑定	✅ 非同源连接被拒绝

七、踩坑点 & 注意事项#

7.1 WebSocket 连接断开后状态丢失#

问题：用户网络抖动导致 WebSocket 断开，重连后无法获取之前的状态。

解决：WebSocket 连接建立后，立即从 Redis 读取当前状态并推送：

1
@Override
2
public void afterConnectionEstablished(WebSocketSession session) throws Exception {
3
    String qrCodeId = getQrCodeId(session);
4
    // ... 校验逻辑 ...
5

6
    sessions.put(qrCodeId, session);
7

8
    QrCodeStatus current = getQrCodeStatusFromRedis(qrCodeId);
9
    if (current != null) {
10
        sendStatus(session, current);
11
    }
12
}

7.2 二维码过期但手机端还在确认#

问题：用户在二维码即将过期时扫码，确认请求到达时二维码已过期。

解决：扫码时延长 TTL，给确认操作留出时间窗口：

1
@Override
2
public QrCodeScanResponse scan(String qrCodeId, String accessToken) {
3
    // ... 校验逻辑 ...
4

5
    // 扫码后延长 TTL 至 60 秒（给确认操作留时间）
6
    redisService.expire(QR_CODE_KEY_PREFIX + qrCodeId, 60, TimeUnit.SECONDS);
7

8
    // ...
9
}

7.3 用户扫码后不确认也不取消#

问题：用户扫码后关闭了手机 APP，二维码停留在 SCANNED 状态，PC 端一直等待。

解决：SCANNED 状态也设置超时（60 秒），超时后自动变为 EXPIRED：

1
// 扫码时设置 60 秒 TTL
2
redisService.expire(QR_CODE_KEY_PREFIX + qrCodeId, 60, TimeUnit.SECONDS);

Redis Key 过期时，通过 Keyspace Notification 触发状态推送：

1
@Component
2
public class QrCodeExpireListener {
3

4
    private final QrCodeWebSocketHandler webSocketHandler;
5

6
    public QrCodeExpireListener(QrCodeWebSocketHandler webSocketHandler) {
7
        this.webSocketHandler = webSocketHandler;
8
    }
9

10
    public void onQrCodeExpire(String qrCodeId) {
11
        QrCodeStatus expiredStatus = QrCodeStatus.builder()
12
                .qrCodeId(qrCodeId)
13
                .status(QrCodeStatusEnum.EXPIRED)
14
                .build();
15
        webSocketHandler.pushStatusUpdate(qrCodeId, expiredStatus);
16
    }
17
}

7.4 PC 端刷新页面后丢失二维码#

问题：用户刷新页面，qrCodeId 丢失，无法继续连接。

解决：将 qrCodeId 存入 sessionStorage：

1
function persistQrCodeId(id: string) {
2
  sessionStorage.setItem('pendingQrCodeId', id)
3
}
4

5
function restoreQrCodeId(): string | null {
6
  const id = sessionStorage.getItem('pendingQrCodeId')
7
  if (id) {
8
    sessionStorage.removeItem('pendingQrCodeId')
9
  }
10
  return id
11
}
12

13
function generateQrCode() {
14
  const savedId = restoreQrCodeId()
15
  if (savedId) {
16
    qrCodeId.value = savedId
17
    // 重新建立连接
18
  } else {
19
    // 生成新二维码
20
  }
21
}

页面加载时先检查 sessionStorage，如果有未完成的 qrCodeId，继续连接而非重新生成。

7.5 WebSocket 被防火墙/代理拦截#

问题：企业内网防火墙拦截 WebSocket 连接。

解决：长轮询降级机制，WebSocket 连接失败 3 次后自动降级为长轮询：

1
ws.onclose = () => {
2
  if (status.value === 'CONFIRMED' || status.value === 'CANCELED' || status.value === 'EXPIRED') {
3
    return
4
  }
5

6
  if (reconnectAttempts < MAX_RECONNECT) {
7
    reconnectAttempts++
8
    setTimeout(() => connectWs(), 2000 * reconnectAttempts)
9
  } else {
10
    fallbackToPolling()
11
  }
12
}

八、生产环境部署清单#

1
□ 后端
2
  □ Gateway 白名单添加 /api/auth/qr-code/generate、/api/auth/qr-code/status、/ws/qr-code/**
3
  □ /scan、/confirm、/cancel 不在白名单中（需 Token）
4
  □ WebSocket 配置 Origin 校验
5
  □ Redis Keyspace Notification 开启（notify-keyspace-events Eg$）
6
  □ RateLimit 配置：scan 接口 10 次/分钟/用户
7
  □ WSS + HTTPS 强制
8

9
□ 前端 PC 端
10
  □ 二维码使用 HTTPS URL
11
  □ WebSocket 使用 wss://
12
  □ 长轮询降级逻辑（WebSocket 失败 3 次后降级）
13
  □ sessionStorage 保存 qrCodeId 防刷新丢失
14
  □ 过期倒计时 UI 提示
15
  □ 降级状态显示（当前使用降级连接）
16

17
□ 前端手机端
18
  □ 扫码使用系统相机或 APP 内扫码组件
19
  □ 确认页面展示 PC 端信息（如"Windows Chrome"）
20
  □ 确认/取消操作需 Authorization Header
21

22
□ 安全
23
  □ 二维码 URL 不含敏感信息
24
  □ PC 端 Token 不经过手机端
25
  □ 分布式锁防并发扫码
26
  □ WebSocket Origin 校验
27
  □ Cookie Secure + SameSite=Lax
28

29
□ 监控
30
  □ 二维码生成量监控
31
  □ 扫码→确认转化率监控
32
  □ WebSocket 连接数监控
33
  □ 长轮询降级比例监控
34
  □ Redis Key 过期事件监控

九、方案对比总结#

维度	短轮询	长轮询	WebSocket
实时性	1-5s 延迟	近实时	实时
服务端压力	高（5,000 QPS/万用户）	低（~333 QPS/万用户）	最低（仅状态变更时）
实现复杂度	低	中	高
断线恢复	天然支持	客户端重发	需心跳+重连+即时状态推送
代理/防火墙	无问题	部分代理提前返回	可能被拦截
适用规模	< 1,000 并发	< 5,000 并发	任意规模
推荐场景	快速验证	降级方案	企业级首选

核心判断：WebSocket 实时性最好、资源占用最低，应作为首选方案。但需要配套长轮询降级机制，保证在 WebSocket 被拦截的场景下仍能正常使用。

参考资料#

如果这篇文章对你有帮助，欢迎点赞收藏。有问题欢迎评论区交流。

登录 | 扫码登录 | 对比文档