WebSocket握手认证：Sa-Token解决方案与实践

1. WebSocket 握手认证的痛点与解决方案选型WebSocket作为全双工通信协议在实时消息推送、在线协作等场景应用广泛。但很多开发者都会遇到一个典型问题如何在握手阶段进行可靠的身份认证传统方案如Cookie或Session ID在跨域场景下存在局限性而JWT又面临Token过期难以主动通知的困境。我在实际项目中测试过三种主流方案URL参数传递Token存在安全风险且易被拦截HTTP Header认证部分浏览器不支持自定义HeaderSa-Token的鉴权方案最终选择的解决方案Sa-Token的优势在于内置WebSocket鉴权模块支持Token自动续期提供完整的会话管理API与HTTP认证体系无缝集成2. Sa-Token的WebSocket鉴权原理2.1 握手阶段的认证流程当客户端发起WebSocket连接时客户端携带Token连接ws://example.com/ws?tokenxxxx服务端通过Sa-Token的StpUtil.checkLogin()验证认证通过后建立持久连接后续通信使用SessionID维持状态关键代码示例ServerEndpoint(/ws) public class WebSocketEndpoint { OnOpen public void onOpen(Session session, PathParam(token) String token) { // 身份验证 StpUtil.checkLogin(token); // 绑定Session与用户ID SaSession saSession StpUtil.getSessionByLoginId(StpUtil.getLoginIdByToken(token)); saSession.set(websocket_session, session); } }2.2 会话保持机制Sa-Token通过双重映射维持状态UserID → SaSession → WebSocket SessionWebSocket SessionID → UserID这种设计带来两个重要特性服务端可主动推送消息到指定用户连接断开时自动清理会话数据3. 完整实现方案3.1 环境准备Maven依赖配置dependency groupIdcn.dev33/groupId artifactIdsa-token-core/artifactId version1.34.0/version /dependency dependency groupIdjavax.websocket/groupId artifactIdjavax.websocket-api/artifactId version1.1/version /dependency3.2 核心实现步骤登录接口签发TokenPostMapping(/login) public String login(String username, String password) { // 验证账号密码... return StpUtil.createLoginSession(userId); }WebSocket端点配置ServerEndpoint(/ws/{token}) public class WsEndpoint { private static final ConcurrentHashMapString, Session sessions new ConcurrentHashMap(); OnOpen public void onOpen(Session session, PathParam(token) String token) { StpUtil.checkLogin(token); String userId StpUtil.getLoginIdByToken(token); sessions.put(userId, session); } OnMessage public void onMessage(String message, Session session) { // 消息处理逻辑... } }服务端主动推送示例public void pushMessage(String userId, String content) { Session session sessions.get(userId); if(session ! null session.isOpen()) { session.getAsyncRemote().sendText(content); } }4. 生产环境注意事项4.1 安全性强化必须使用wss协议Token设置合理有效期建议2-4小时实现IP绑定防止Token劫持StpUtil.getSessionByLoginId(userId).set(ip, currentIp);4.2 性能优化连接数监控// 获取当前在线用户数 StpUtil.getSessionCount();心跳检测配置# sa-token配置 sa-token.timeout3600 sa-token.activity-timeout3004.3 常见问题排查连接失败403检查Token是否过期验证服务端时钟是否同步消息推送延迟检查Netty worker线程配置确认未阻塞IO操作内存泄漏确保实现OnClose清理逻辑定期检查Session映射表5. 扩展应用场景5.1 多端消息同步通过Sa-Token的Pub-Sub模块实现// 订阅频道 StpUtil.getSessionByLoginId(userId).subscribeChannel(order_update); // 发布消息 SaSessionCustomUtil.publishChannel(order_update, 新订单通知);5.2 分布式部署方案集成Redissa-token.jwtSecretyour-secret-key sa-token.is-sharetrue sa-token.token-styleuuid使用Gateway统一鉴权// 全局过滤器 public class WsAuthFilter implements GlobalFilter { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String token exchange.getRequest().getQueryParams().getFirst(token); StpUtil.checkLogin(token); return chain.filter(exchange); } }在实际项目中这套方案成功支撑了日均10万的WebSocket连接关键点在于保持轻量级会话数据实现连接异常自动恢复做好背压控制Backpressure建立完善的监控指标连接数、消息延迟等