WebSocket鉴权这事说简单也简单说难也难。简单在于本质就是一次HTTP Upgrade请求可以在握手阶段塞token难在于很多团队把HTTP那套思维生搬硬套过来结果线上各种意外断连、token泄漏、权限绕过排查起来一头雾水。我前后做过几个带实时推送的业务系统从早期的“裸奔”模式到后面逐渐沉淀出一套相对完整的鉴权方案踩了不少坑这里把思路和实现一起梳理一下。1. WebSocket鉴权为什么不能照搬HTTP方案先弄清楚一个核心区别HTTP请求是“一次性”的每次请求都能带上完整的鉴权信息服务端每次都能校验无状态、好排查。WebSocket不一样它一旦建立连接后续通信就是一条长连接上的全双工数据流不会再自动附带任何cookie或header。鉴权如果只在连接建立时做一次那这条连接在之后数小时甚至数天的生命周期里只要不断开服务端就默认它一直是合法的。这里面有一个很典型的误解有人觉得“连接建立时校验过token了后面就安全了”实际上这是把鉴权当成了“入场券”忽略了WebSocket连接天然具备的“状态延续”风险。比如用户的token有效期是30分钟连接却挂了2个小时期间用户权限变了、账号被禁用了、token被重置了这条旧连接依然能收发消息。更危险的是如果同一token被多个客户端共享服务端根本区分不了谁是谁。另外一个问题出在“鉴权信息放哪”。HTTP可以放在Authorization头、cookie、请求体里选择很多WebSocket的浏览器端API却有限制。浏览器里new WebSocket(url)没办法自定义header虽然理论上可以走protocols参数但那设计初衷是协商子协议不是为了塞token。这个问题直接决定了前端怎么把token传到后端也是很多团队第一次实现时卡住的地方。还有个容易忽略的点鉴权不等于加密。很多方案只校验证书和token消息内容明文传输token即使校验通过了敏感数据被抓包一样能看。所以设计鉴权方案的同时要想清楚是否需要wss是否需要消息体加密这跟鉴权是两个维度的事。想清楚这些就会发现WebSocket鉴权应该分三个层面去做而不是简简单单验一个token就完事。2. 鉴权方案设计握手的入口与消息的关卡我的落地方案是三层结构连接握手鉴权、消息级鉴权、生命周期管理。缺一层都有隐患合在一起才算闭环。2.1 握手阶段HTTP Upgrade请求是唯一一次能借助标准头部的机会浏览器发起WebSocket连接时会先发一个HTTP Upgrade请求服务端返回101后连接才建立。这个Upgrade请求里可以带header可以带cookie也可以带query参数这是整个连接生命周期里唯一一次可以用标准HTTP语义传鉴权信息的机会。我在服务端用的是Go语言标准的http.Request就能读到这些信息。推荐的方式是靠token而不是session因为WebSocket场景下session的分布式共享本身就是一个大坑而token可以放在query、header、cookie里后端无状态校验即可。这里有一个很重要的取舍走query参数最简单但token会出现在访问日志里如果nginx/apache默认打了access logtoken就直接裸奔了。走Header稍微安全点但浏览器原生API设不了header需要服务端配合一次HTTP请求去换取一个带鉴权信息的WebSocket地址或者用子协议的方式带token。这个我会在讲到实现的时候展开对比。2.2 消息级鉴权面向多页面与分布式后端的兜底防线只做握手鉴权等于信任了整条长连接。我自己的项目刚开始就是这么干的后来出现了一个问题某个用户在前端页面上通过越权调用发了一种消息类型后端没校验就直接处理了因为后端觉得“连接都鉴权过了这个消息肯定是他的”。这个想法在WebSocket场景下很危险。消息级鉴权不是说每条消息都重新校验一次token那是性能灾难。正确姿势是连接建立时校验token同时从token里解析出用户身份userID把身份绑定到这条连接上。每条消息进来时先根据消息类型判断“这个用户有没有权限执行这个操作、操作的数据范围是哪个”。比如普通用户只能发消息给同一项目组的人管理员才能发全局广播这种判断必须在每一条消息上做因为WebSocket是一个无约束的全双工通道前端想发什么就发什么。只有握手鉴权没有消息级鉴权等于把服务端接口裸奔在用户面前用户拿网页控制台就能调你能收的所有消息类型。2.3 生命周期鉴权把token过期、刷新、踢人、断线重连纳入设计这一层最容易被忽略但实际运行中大量问题出在这里。一个典型的场景用户登录后进了WebSockettoken有效期设置的是24小时他明天下次打开页面时token还能用这时候连接重新握手的鉴权是没问题的。麻烦的是中间态比如token已经过期但WebSocket连接还活着服务端要不要主动断开我的设计是在业务层级加一个“心跳鉴权”的概念不仅心跳包要回复pong服务端还会定期比如每5分钟检查一遍用户的token是否还在有效期内、用户是否仍被允许访问这个项目。如果在服务端的内存表里做了连接与用户身份的绑定这个检查只需要遍历在线表就行开销很小但能解决“人已经被踢下线连接还飘着”的尴尬局面。还有一个必须想清楚的场景是断线重连。移动端网络切换、后端发布重启连接必然断开客户端一般有重连逻辑。如果重连时用的是旧token后端需要能识别“这是前一天同一台设备上的同一个用户”而不是把旧token一刀切。这里我建议每次重连都刷新token而不是沿用旧token重试因为旧token可能在断线期间已经被吊销了。3. 核心实现三种握手携带方式的取舍与代码落地从前端把token传到后端实际操作里有三条路query参数、Header、子协议。各有利弊我一次性讲清楚。3.1 三种方式的详细对比携带方式前端实现服务端读取方式优点缺点适用场景query参数new WebSocket(wss://x?tokenxxx)从r.URL.Query()里取实现最简单不依赖额外协议token会进访问日志URL长度受限制token会出现在浏览器历史记录中内网或私有项目对日志管控有把握Header需配合HTTP接口先请求后端拿一个临时URL或ticket从r.Header.Get(Authorization)里取不暴露在URL和日志里可以加短期票据逻辑符合HTTP语义需要额外一次HTTP请求实现复杂大部分中大型项目推荐优先考虑子协议Sec-WebSocket-Protocolnew WebSocket(url, [ticket, token])从r.Header.Get(Sec-WebSocket-Protocol)里取能传数据不算标准鉴权方式语义不清晰有些代理会对该header做改写token长度受限部分特殊场景有人会说webSocket支持自定义Header——这里我多啰嗦一句浏览器原生API不行但很多第三方库比如某些实现WebSocket的客户端SDK可以自定义header。如果是你在写非浏览器的客户端比如桌面端、移动端、后端做客户端走WebSocket直接自定义Header是最干净的方案因为不受浏览器限制。3.2 服务端落地Go语言版握手鉴权先做一个校验token的函数func authenticate(r *http.Request) (*UserIdentity, error) { // 按优先级从不同位置获取token token : r.Header.Get(Authorization) if strings.HasPrefix(token, Bearer ) { token token[7:] } if token { // 兼容无法设置Header的场景 token r.URL.Query().Get(token) } if token { // 再尝试子协议 protocols : r.Header.Get(Sec-WebSocket-Protocol) if protocols ! { parts : strings.Split(protocols, ,) for _, p : range parts { p strings.TrimSpace(p) if strings.HasPrefix(p, token_) { token strings.TrimPrefix(p, token_) break } } } } if token { return nil, errors.New(missing token) } // 解析并校验token这里以JWT为例 parsed, err : jwt.Parse(token, func(t *jwt.Token) (interface{}, error) { return []byte(your_secret_key), nil }) if err ! nil || !parsed.Valid { return nil, errors.New(invalid token) } claims : parsed.Claims.(jwt.MapClaims) uid, _ : claims[uid].(float64) if uid 0 { return nil, errors.New(invalid user id) } return UserIdentity{ UserID: int64(uid), Role: claims[role].(string), }, nil }然后在升级之前做鉴权var upgrader websocket.Upgrader{ CheckOrigin: func(r *http.Request) bool { // 生产环境要严格校验Origin防止跨站WebSocket劫持 origin : r.Header.Get(Origin) if origin { return true } return isAllowedOrigin(origin) }, } func wsHandler(w http.ResponseWriter, r *http.Request) { identity, err : authenticate(r) if err ! nil { http.Error(w, unauthorized, http.StatusUnauthorized) return } conn, err : upgrader.Upgrade(w, r, nil) if err ! nil { log.Printf(upgrade error: %v, err) return } // 绑定连接与用户身份 connMgr.Add(identity.UserID, conn) defer connMgr.Remove(identity.UserID, conn) // 进入消息循环 serveWS(conn, identity) }这里有一个很容易踩的坑CheckOrigin不要全部返回true有些人图省事直接不看来源就放行了这会直接暴露跨站WebSocket劫持风险。攻击者可以在自己的站里写脚本让受害者浏览器去连受害网站的WebSocket端口如果CheckOrigin全放过攻击脚本就能借用受害者的身份建立连接。生产环境一定维护一个白名单或者至少比对Origin和Host的域名部分。3.3 前端配合如何处理Header受限浏览器端不能自定义Header我用的方案是“先换URL再连接”前端在WebSocket连接前先向后端发起一次HTTP请求后端返回一个一次性票据ticket一般带5秒过期时间前端再用wss://xxx?ticketxxx去建立WebSocket连接。服务端收到后用ticket换取真实的用户身份并且把ticket标记为已使用防止重放。这个ticket设计在最里面解决token暴露的问题因为ticket是一次性且短期的即使出现在日志里也无法被用来冒充用户。关键代码// 生成ticket的接口 func getTicketHandler(w http.ResponseWriter, r *http.Request) { // 这是普通的HTTP接口正常走你的登录态校验 uid : getCurrentUserID(r) ticket : generateRandomTicket() ticketStore.Set(ticket, uid, 5*time.Second) json.NewEncoder(w).Encode(map[string]string{ url: wss://yourdomain.com/ws?ticket ticket, }) } // WebSocket握手时通过ticket换取身份 func authenticateByTicket(r *http.Request) (*UserIdentity, error) { ticket : r.URL.Query().Get(ticket) if ticket { return nil, errors.New(missing ticket) } uid, ok : ticketStore.GetAndDelete(ticket) if !ok { return nil, errors.New(invalid or expired ticket) } return UserIdentity{UserID: uid}, nil }4. 连接与状态管理心跳、重连、在线表与踢人逻辑鉴权只是第一步连上了之后连接状态的维护其实和鉴权耦合得很深。很多系统上线后出现“用户明明下线了状态还显示在线”或者“踢人踢不掉重新登录又顶不掉旧连接”这些都是因为没有把连接管理设计好。我的做法是把连接管理做成独立的组件和鉴权模块配合起来。4.1 在线连接表与并发控制服务端维护一张全局的在线表存储userID - 连接集合。注意是集合不是单条连接因为同一个用户很可能同时在浏览器、手机、桌面端登录三个设备就是三条连接。type ConnManager struct { mu sync.RWMutex conns map[int64]map[*websocket.Conn]struct{} } func (m *ConnManager) Add(uid int64, conn *websocket.Conn) { m.mu.Lock() defer m.mu.Unlock() if m.conns[uid] nil { m.conns[uid] make(map[*websocket.Conn]struct{}) } m.conns[uid][conn] struct{}{} } func (m *ConnManager) Remove(uid int64, conn *websocket.Conn) { m.mu.Lock() defer m.mu.Unlock() if set, ok : m.conns[uid]; ok { delete(set, conn) if len(set) 0 { delete(m.conns, uid) } } }为什么用集合而不是单个连接因为一个userID下存在多条连接非常正常单连接结构会在第二个设备登录时把第一个设备顶下线这个产品上需要明确需求才能这么干。4.2 心跳机制和死连接清理心跳是整个长连接系统最基础的保障之一。不设心跳就会出现大量半开连接网络断开时TCP不会立刻通知到应用层服务端以为连接还在其实客户端早就掉线了。长此以往在线表里会堆积一堆僵尸连接推送消息时还会触发一堆写超时错误。我用的心跳间隔是30秒服务端启动一个定时器每隔30秒对所有连接发送一次ping消息WebSocket协议层自带的心跳帧客户端收到后返回pong。服务端将最后一次pong时间记录下来超过90秒没有pong就强制关闭这个连接。这两个数值不是拍脑袋定的需要考虑移动端省电和弱网环境。间隔太短会让移动端频繁唤醒电量掉得厉害间隔太长又会让僵尸连接存活久占用资源。30秒/90秒是比较通用的配置如果你服务的场景是PC网页端可以更快比如10秒/30秒。4.3 踢人与权限变更后的强制下线“踢人”这个操作在产品里有很多变体管理员封禁用户、用户修改密码后旧设备失效、同名账号互踢。核心问题都一样如何让服务端主动断开指定连接。再进一步断开之后如果客户端自动重连那踢人就没意义了因为旧token如果还是有效的重连就会直接成功。所以踢人的正确姿势是两步走服务端吊销旧的token或记录一个黑名单状态服务端主动关闭该用户的所有连接。顺序很重要先吊销再断开。否则中间有个时间窗口客户端自动重连并成功。实现上踢人逻辑就是遍历该用户的连接集合写入关闭帧然后关闭连接func (m *ConnManager) KickUser(uid int64, reason string) { m.mu.RLock() conns : m.conns[uid] m.mu.RUnlock() for conn : range conns { // 使用控制消息通知客户端被踢原因 conn.WriteControl(websocket.CloseMessage, websocket.FormatCloseMessage(4001, reason), time.Now().Add(5*time.Second)) m.Remove(uid, conn) conn.Close() } }我这里定义了一个自定义错误码4001业务上专门表示“被强制下线”。客户端收到这个错误码后应该停止自动重连逻辑否则会陷入“被踢-重连-再被踢”的死循环。4.4 断线重连与重新鉴权重连逻辑里最大的坑是“沿用旧token直接重试”。假设用户的token有效期为2小时他1小时前登录中间网络断了客户端立即用旧token重连——这表面上没问题。但如果断网发生在token过期前10分钟等到网络恢复时旧token已经失效重连失败。在弱网环境地下车库、电梯里这种情况很频繁。我的方案是客户端在重连前先调用刷新token接口用refreshToken换一个新的accessToken再用新token发起WebSocket连接。如果refreshToken也过期了客户端才认为需要重新登录。5. 安全加固与常见绕过路径鉴权方案做完了不代表就安全了。我在安全测试阶段总结了几条绕过路径不防住等于白做。5.1 重放攻击与票据一次性用票据方案换URL时一定要确保ticket只能使用一次并且要设置极短的有效期。我之前遇到过测试环境里把ticket有效期设置成10分钟结果安全测试的人拿到别人分享的URL后10分钟之内都能直接用那个ticket连上。改成5秒有效且消费一次后立即失效就堵住了。5.2 权限提升与消息类型校验一个常见攻击用户用websocket客户端比如在线调试工具连接服务端手动构造一个“管理员广播”的消息类型如果服务端只在握手时校验了身份没有在消息处理时校验角色这个用户就能实现权限提升。解决方式很简单但也最容易偷懒每种消息类型的处理函数里都必须做一次“当前用户是否有权执行该操作”的校验。这不是重复劳动是WebSocket这种无约束通道下必须做的事。5.3 消息伪造与来源校验WebSocket连接建立后服务端默认信任这条连接的所有输入。但实际上如果身份信息只是在URL里放了一次之后就没有任何参照物服务端接收到的每条消息其实是“无法区分来自谁”的——它只能通过连接上绑定的身份来判断。问题来了一旦连接被劫持或者客户端代码被注入恶意脚本比如XSS攻击者就可以借用这个合法连接为所欲为。配合的方案是在消息体里带一个短暂时效的消息签名或者至少带一个单调递增的序号服务端校验序号连续性。这种方案在金融类、对账类的实时系统里很有必要一般的聊天应用可以放宽。我自己实践下来轻量的做法是消息体里加一个客户端生成的随机数nonce服务端缓存最近收到的nonce重复出现的直接丢弃能防一部分重放。5.4 WSS与代理层注意事项生产环境一定要用wss而不是ws除非你明确知道上层的负载均衡已经终结了TLS。另外很多云厂商的负载均衡对WebSocket协议的支持细节不一致比如对socket.io这类框架长连接的闲置超时时间由负载均衡的“连接空闲超时”控制如果LB设置为60秒而你的心跳是30秒就没事心跳如果是90秒LB就会先把没有数据传输的连接切断。这个在压测和上线前必须查清楚否则会出现“连接稳定运行几分钟后全部断开”的诡异问题。排查方法很简单看负载均衡的访问日志有没有出现大量的101升级后紧接着4xx或5xx的日志以及后端连接数是否周期性清空。之前有同事排查类似问题最后发现是LB层的连接超时设置导致而服务端日志看起来一切都正常。6. 常见问题与排查实录误连、断连、鉴权失效、并发踢下线最后整理一下我自己及团队在实际运维中踩过的问题做成速查表再展开讲讲排查思路。现象可能原因排查方法握手一直401token过期 / 签名算法不匹配 / 时钟偏差检查服务端时间和客户端时间JWT的iat和exp做宽容处理连接偶尔断开负载均衡闲置超时 / 心跳间隔大于LB超时时间调短心跳间隔或调整LB配置客户端显示在线服务端推送失败僵尸连接没清理检查心跳pong时间有没有在更新增加僵尸连接自动清理任务用户被踢后立即自动重连成功踢人时没有先吊销token调整顺序先吊销token再断开连接一个用户多次重复登录导致在线列表爆炸每次连接都新增记录没有踢掉旧连接根据产品需求决定是否启用“单设备登录”策略如果需要做“同类型设备互踢”所有连接在固定时间点集体断开多半是负载均衡周期性回收或者服务端定时任务误关闭看服务端日志里有没有输出主动关闭的日志检查定时任务是否触碰了连接池6.1 握手阶段鉴权成功但消息收发失败这个现象很有迷惑性。握手鉴权已经是200了连接也建立了但客户端发送消息后服务端没有任何响应客户端的状态看起来还是OPEN发出去的消息石沉大海。我遇到的一次消息处理函数里做了用户角色判断但角色信息从JWT的role字段里取的时候类型断言写错了解析出来一直是空字符串导致所有消息都被判定为“无权限”。处理函数里只是静默丢弃返回了一个错误码客户端没有处理错误码就当作成功了。这个问题的核心教训是鉴权失败和消息处理失败都应该有明确的错误协议不能静默丢弃。我后来规定业务消息必须返回一个对应的Ack哪怕是一条默认的“已收到”也行至少让客户端知道链路是通的。6.2 token过期和连接存活的矛盾这属于设计层面的纠偏。早期版本我确实只做握手鉴权当时想的是“token过期了再重连不就行了”。但真实用户行为里有太多长时间挂机的情况token过期了连接还挂着后端要基于用户身份推送系统通知的时候发现这个用户被判定为“频繁掉线”。后来我在心跳循环里叠加了一层“Token有效性检查”每5分钟检查一次在线表里所有连接的用户的token过期时间如果已经过期或者接近过期比如剩余时间小于2分钟服务端主动给客户端下发一个token_expiring事件客户端收到这个事件后后台调用刷新接口换取新token再把新token通过一条普通消息发给服务端更新。这种做法的好处是用户无感知连接也不断。6.3 并发连接数与推拉消息稳定性做实时服务的人都绕不开一个问题连接数一多推送性能就下降。我自己遇到过一次线上事故连接数从几千涨到上万后某些连接开始反复断开重连服务端CPU和内存看着都正常但推送延迟越来越高。后来定位到是写超时设置得不合理。推送消息时用的写超时时间是100毫秒正常情况下够了。但有一次推送的是一个超大消息体一整个对象包含了大量字段序列化之后很大写入TCP缓冲区时超过100毫秒直接超时断开。大量连接同时推这种大消息就造成了“批量抖动”。解决办法也很粗暴但有效拆分消息体把一次性推送的大JSON拆成几类小消息分别推送同时把写超时调整为500毫秒并给每个连接设置一个独立的发送队列避免一个连接慢导致整个goroutine阻塞。现在推送大消息也没再出现过抖动了。6.4 多实例部署时的鉴权状态一致性服务端一旦上了多个实例在线连接表就不能只存在单机内存里了否则用户连接在实例A消息推送到实例B就找不到这条连接。鉴权这里也同理踢人操作需要让所有实例都知道用户已被踢。我采用的方式是引入一个轻量级的消息中间件或者用Redis的Pub/Sub也可以实例A发起踢人动作时广播一条“用户12345已被封禁”的消息其他实例收到后各自关闭本机上的对应连接。这比把所有连接状态都存Redis再同步要简单得多也够用。连接和鉴权状态保持一致的关键是状态变更必须走广播而不是走后端直接操作DB后再让各个实例自己去查。6.5 调试WebSocket的实用技巧最后唠一点排查工具的使用心得。浏览器开发者工具的Network面板可以看到WebSocket的帧记录但只能看到一个方向的帧对于调试双向消息交互我更喜欢直接用命令行工具来做连接测试。很多人在排查问题时只会用现成的在线调试网站但那类网站通常只能建立裸连接不支持自定义协议和鉴权头实际情况是高仿不出来。写一个简单的Go或Node测试脚本模拟一个客户端携带token和自定义Header去连接服务端问题基本能复现十有八九。脚本里可以把收发消息、心跳、错误码都打出来比在浏览器里翻帧方便得多。这个脚本我建议直接放在代码仓库的scripts/目录下当作项目的调试工具长期维护团队成员排查问题都用得上。WebSocket鉴权这件事本质上就是在HTTP无状态模型和长连接有状态模型之间做一个折中。握手阶段借用HTTP的语义完成身份认证连接建立后在业务层自己做会话管理、心跳检测、权限校验和生命周期控制。很多人觉得WebSocket鉴权难难不在技术本身而在于对长连接的“状态延续”没有足够敬畏。如果能把身份绑定、权限校验、连接生命周期这三点想清楚任何项目都能设计出一套够用且不容易出问题的方案。