Python 3.6.1 WebSocket自定义Header长连接实战与排错

1. 需求拆解一个 WebSocket 客户端为什么还要折腾 header1.1 两个典型现象连不上和连上就被踢但凡在真实环境里写过 WebSocket 客户端大概率碰到过两类让人抓不住头绪的情况。第一种是压根连不上create_connection直接抛异常日志里只有一行干巴巴的Handshake status 403 Forbidden或者401 Unauthorized第二种更难受连接建立得干干净净日志打印“已连接”结果两三秒后服务端一声不吭把连接关了既不返回错误码也不给关闭原因本地看起来毫无破绽。这两类现象的根子都在握手阶段的那一份 HTTP header 上。WebSocket 的“长连接”不是凭空建立的它披着 HTTP/1.1 的外衣走了一遍升级流程服务端在这个升级请求里能看到的东西只有 URL、请求方法、header 和一点点 body 信息。业务侧的鉴权 token、客户端版本号、设备标识、来源域名校验几乎全部挂在这几行 header 上。Python 3.6.1 上写一个带自定义 header 的 WebSocket 模拟客户端脚本本质工作就是把这几个字段拼对、拼全、拼到服务端认可的位置然后在此基础上维持住这条长连接。1.2 header 在握手阶段到底承担了什么角色把 WebSocket 握手拆开看它是一次标准的 HTTP GET 请求请求行里写着GET /ws HTTP/1.1然后带上Upgrade: websocket、Connection: Upgrade、Sec-WebSocket-Key、Sec-WebSocket-Version: 13这几个协议必需的字段。服务端认了返回101 Switching Protocols从这一刻起这条 TCP 连接就不再走 HTTP 语义了改走 WebSocket 帧格式。关键在于101 返回之前的那段 HTTP 交互是唯一一次能携带任意自定义字段的机会。连接升级完成之后你想再传 token 就只能塞进业务消息体里自己解析很多服务端并不认这种玩法。所以“需要传 header 来建立长连接”这句话翻译成工程语言就是在 HTTP 升级请求里附加业务方要求的鉴权与识别字段让服务端放行。我把常见的 header 用途归了一下类实际对接时对着这张表逐项核对能省掉大量试错时间用途典型字段缺失后果身份鉴权Authorization、Cookie、自定义X-Token401 或直接断连来源校验Origin、Referer403 Forbidden客户端识别User-Agent、X-Client-Version、X-Device-Id被网关识别为非受信客户端协议协商Sec-WebSocket-Protocol、Sec-WebSocket-Extensions101 后立即关闭或消息压缩不可用路由与灰度自定义X-Route-Tag、X-Tenant连到错误的实例或租户1.3 Python 3.6.1 这个版本带来的真实约束版本写进标题不是没有原因的。3.6.1 属于 2017 年的产物语法层面够用f-string 有了async/await是正式关键字了类型注解也稳定了。真正的麻烦在依赖生态上很多现在主流的库早就把 3.6 从python_requires里摘掉了pip install一跑就报“Requires a newer version of Python”。实操上需要盯住三个版本上限websockets在 3.6 上基本只能停在 8.x/9.x 这一档10 之后的版本要求更高版本的解释器websocket-client建议锁在 1.3 以下再高的版本已经放弃对老解释器的支持certifi用来补 SSL 根证书老环境里自带的证书包经常过期用wss://时会莫名其妙报证书校验失败。这三条如果不提前锁死脚本在别的机器上能不能跑全看运气。还有一个容易被忽略的点3.6.1 的asyncio事件循环实现和后来版本差异不小asyncio.run()虽然可用但调试模式下对未关闭协程的告警行为不太一样写异步客户端时最好显式loop asyncio.get_event_loop()然后loop.run_until_complete()出问题的时候堆栈更容易读。提示在 3.6.1 这类老环境里务必用pip freeze requirements.txt把依赖版本原样冻结再配合--no-deps或者内网源做离线安装。直接pip install websocket-client拿到最新版大概率装完就报错。2. 三条技术路线选型对比2.1 websocket-client同步阻塞header 传法最接近裸握手这个库最大的优点是把 header 原样暴露给你create_connection()和run_forever()都接受一个header参数类型可以是[Key: Value, ...]形式的列表也可以是 dict底层直接把这些行拼进握手请求里中间几乎不做加工。你在抓包里看到什么代码里就写什么排查问题特别直观。它的工作模式是同步的连接对象自己开一个后台线程跑收包业务代码用回调函数接收消息on_message、on_open、on_error、on_close主线程要么run_forever()卡住要么recv()手动拉取。这种方式写一次性脚本、做接口验证、跑数据采集任务非常顺手缺点是并发数量上不去几十条连接还行几百条就得考虑换方案。2.2 websockets异步生态但要卡死版本号websockets是纯 asyncio 实现天生适合跑大量并发连接代码写出来也干净async with websockets.connect(...) as ws一个上下文就把生命周期管住了。它在 8.x/9.x 时代传自定义 header 用的是extra_headers参数接收一个 dict。这个参数名很关键这几个版本里叫extra_headers后面版本改成了additional_headers名字对不上就是TypeError: __init__() got an unexpected keyword argument在老环境上照着新文档抄代码第一步就卡住。它的另一个特点是遵循协议规范比较严格会自动处理 ping/pong 帧、会做消息分片重组、会在收到非法帧时抛ConnectionClosedError。这对生产环境是好事但如果你对接的服务端协议实现得比较随意反而需要多写一些异常兜底。2.3 手写握手只在特殊网关下才值得第三条路是自己用socket发 HTTP 升级请求自己解析 101 响应自己组帧。除非遇到非常特殊的情况比如网关要求极其罕见的 header 拼接顺序、需要在同一条 TCP 连接上先做 HTTP 鉴权再做升级或者要模拟某个特定客户端的字节级指纹否则真不建议手写。RFC 6455 里的掩码、分片、控制帧处理细节一堆写全了是几百行调试成本远超收益。三条路线的取舍我做成了对照表选型时对着看比较快维度websocket-clientwebsockets手写 socket编程模型同步 回调全异步全手动header 控制粒度高原样拼接中dict 传入完全自由3.6 可用版本1.3 及以下8.x / 9.x无依赖并发能力低线程模型高取决于实现调试难度低中高适合场景脚本验证、少量连接采集、推送、高并发特殊网关适配我个人的默认选择是先拿websocket-client把 header 打通、确认服务端认了这套字段再根据并发需求决定要不要迁移到websockets。先用简单工具确认协议层没问题再上复杂框架这个顺序能避免把“header 写错了”和“异步代码写错了”两类问题混在一起排查。3. 握手包拆解header 到底该怎么拼才不被拒3.1 请求行和必需字段的构成一次标准的升级请求大概长这样可以直接拿去和服务端同学对账GET /ws/stream?room1 HTTP/1.1 Host: 127.0.0.1:9000 Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ Sec-WebSocket-Version: 13 Origin: https://example.com User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) ... Authorization: Bearer eyJhbGciOi... X-Client-Version: 1.4.2Upgrade、Connection、Sec-WebSocket-Key、Sec-WebSocket-Version这四个是协议层必需的库通常会自动补不要自己在 header 列表里重复写。尤其Host重复出现会让部分严格的网关直接返回 400。Sec-WebSocket-Protocol如果服务端要求指定子协议就必须带上并且返回的 101 响应里子协议要对得上否则有些实现会主动断开。3.2 Sec-WebSocket-Key 与 Accept 的校验链条这个机制值得说清楚因为很多人排查“连上就断”时根本没意识到这一层。客户端随机生成 16 字节做 base64 编码作为Sec-WebSocket-Key服务端把这个 key 拼上一个固定字符串258EAFA5-E914-47DA-95CA-C5AB0DC85B11做 SHA-1 再 base64得到Sec-WebSocket-Accept返回。客户端校验这个值是否匹配不匹配就说明中间有代理改包或者根本不是 WebSocket 服务端。自己在本地验算一下能快速判断服务端实现是否规范import base64 import hashlib GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 key dGhlIHNhbXBsZSBub25jZQ accept base64.b64encode( hashlib.sha1((key GUID).encode(ascii)).digest() ).decode(ascii) print(accept) # s3pPLMBiTxaQ9kYGzzhZRbKxOowebsocket-client和websockets内部都会做这个校验校验失败会抛WebSocketBadStatusException或InvalidHandshake。看到这类报错先别怀疑自己的 header 写错八成是中间有一层反向代理没开 WebSocket 转发或者把Connection头给剥掉了。3.3 哪些 header 该由框架管哪些得自己填这条界限划不清楚就会陷入“我明明传了却报错”的死循环。原则是协议层字段交给库业务层字段自己拼。库自动维护的有Host、Upgrade、Connection、Sec-WebSocket-Key、Sec-WebSocket-Version某些库还会补Accept-Encoding。你需要自己填的是Authorization、Cookie、Origin、User-Agent、各种X-开头的自定义字段。Origin是一个典型的两面派浏览器的 WebSocket API 不允许改Origin但用 Python 脚本就没有这个限制所以很多服务端把Origin校验当作一道简易的客户端类型判别脚本里补一个合理的Origin往往能直接解决问题。Cookie在websocket-client里有个独立的cookie参数也可以直接塞进 header 列表两种都行。多值 cookie 建议拼成一条a1; b2再传别拆成多个Cookie行HTTP 规范上不允许部分实现会取第一个然后丢掉后面的。注意User-Agent千万不要用库默认的Python/3.6.1 websocket-client/0.57.0这类值。不少网关有 UA 白名单非浏览器 UA 直接 403。这是我自己踩过最冤枉的一次坑抓包看了半天 header 内容都对最后发现是被 UA 拦了。4. websocket-client 实战带 header 的长连接脚本4.1 环境准备与依赖锁定先把环境弄干净。老解释器配老库装的时候显式写版本号别让 pip 自作主张pip install websocket-client1.1.0 certifi2020.12.5如果机器上有多个解释器务必用python3.6 -m pip install的形式避免装到了别的版本下。装完写三行代码验证一下import sys import websocket print(sys.version) print(websocket.__version__)这里的第一行输出应该能看到3.6.1第二行应该和装的时候指定的版本一致。这一步看着多余实际能挡掉大量“为什么我改了代码却没生效”的困惑——很多时候是环境装串了。4.2 最小可跑通的脚本下面这份骨架我在多个场景里改巴改巴就用了核心是header用列表形式传顺序可控、重复字段也能保留# -*- coding: utf-8 -*- import json import ssl import time import websocket WS_URL ws://127.0.0.1:9000/ws/stream?room1 HEADER [ Authorization: Bearer 换成本次会话的真实 token, Origin: https://example.com, User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36, Accept-Language: zh-CN,zh;q0.9, X-Client-Version: 1.4.2, ] def on_open(ws): print([open] 连接建立发送订阅消息) ws.send(json.dumps({type: subscribe, topic: tick}, ensure_asciiFalse)) def on_message(ws, message): print([recv] %s % message[:200]) def on_error(ws, error): print([error] %r % (error,)) def on_close(ws, code, reason): print([close] code%s reason%s % (code, reason)) def main(): sslopt {cert_reqs: ssl.CERT_REQUIRED, check_hostname: True} ws websocket.WebSocketApp( WS_URL, headerHEADER, on_openon_open, on_messageon_message, on_erroron_error, on_closeon_close, ) ws.run_forever( ping_interval20, ping_timeout10, ssloptsslopt, ) if __name__ __main__: main()几个细节值得单独拎出来说。header传列表时每一行都要包含冒号加空格格式错一个字符服务端可能直接拒。run_forever的ping_interval和ping_timeout是保活关键前者表示每隔多少秒发一个 ping 帧后者表示等 pong 超时多久判定连接已死。默认值在某些版本里是 0也就是不发心跳那么在中间有负载均衡器的情况下连接空闲几十秒就会被静默掐断。4.3 心跳、重连与优雅退出长连接脚本跑起来之后真正折磨人的是稳定性。我的处理方式是把重连做成一层薄封装主循环里捕获异常后指数退避别写死一个固定间隔def run_with_retry(max_retry10): delay 1.0 for attempt in range(max_retry): try: main() delay 1.0 # 正常退出后重置 except KeyboardInterrupt: print(手动退出) break except Exception as exc: print(第 %d 次异常: %r % (attempt 1, exc)) time.sleep(delay) delay min(delay * 2, 60.0)退避的意义在于服务端如果是短暂重启你一秒一重连只会把它的启动流程再打挂一次而如果对端是限流拒绝固定高频重连会被直接拉黑。1 → 2 → 4 → 8 → 16 → 32 → 60这个序列是我在实践中最舒服的节奏恢复快又不会造成冲击。优雅退出这块WebSocketApp没有提供特别干净的中断方式run_forever会阻塞线程。常规做法是在on_message里检测到退出信号后调用ws.close()让run_forever自然返回。如果要支持外部中断可以维护一个全局标志位或者在主线程捕获KeyboardInterrupt后调用ws.close()注意要处理close()调用时连接已断的情况套一层 try 就行。提示ping_interval不能设得太短。有些服务端的连接数统计逻辑会把频繁 ping 的连接识别为异常客户端。20 到 30 秒是比较稳妥的区间比大多数负载均衡器默认的 60 秒空闲超时略短即可。5. websockets 实战异步写法与版本陷阱5.1 extra_headers 的正确传法在 Python 3.6 上锁定websockets9.1自定义 header 走extra_headers参数# -*- coding: utf-8 -*- import asyncio import json import websockets WS_URL ws://127.0.0.1:9000/ws/stream HEADERS { Authorization: Bearer token, Origin: https://example.com, User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36, X-Client-Version: 1.4.2, } async def worker(): async with websockets.connect( WS_URL, extra_headersHEADERS, ping_interval20, ping_timeout10, close_timeout5, max_size2 ** 22, ) as ws: await ws.send(json.dumps({type: subscribe, topic: tick})) while True: try: message await asyncio.wait_for(ws.recv(), timeout60) except asyncio.TimeoutError: continue print([recv] %s % message[:200]) def main(): loop asyncio.get_event_loop() try: loop.run_until_complete(worker()) except KeyboardInterrupt: print(手动退出) finally: loop.close() if __name__ __main__: main()extra_headers传 dict 的局限在于无法表达重复 key如果业务上真需要两个同名 header就得降级到websocket-client或者改用websockets内部的loop.create_connection手动走一遍。绝大多数场景一个 dict 够用不必纠结。5.2 长连接的保活与断线重连异步客户端的重连我习惯写在外层worker只负责一次完整会话异常往上抛async def supervisor(): delay 1.0 while True: try: await worker() delay 1.0 except asyncio.CancelledError: raise except Exception as exc: print([reconnect] %r % (exc,)) await asyncio.sleep(delay) delay min(delay * 2, 60.0)这里有个坑需要提醒websockets.connect在握手失败时抛的是InvalidStatusCode这个异常里带着status_code和headers抓出来打印能把服务端拒绝的真实原因看明白。很多人只打印str(exc)拿到的信息非常有限白白浪费排查时间。from websockets.exceptions import InvalidStatusCode try: ... except InvalidStatusCode as exc: print(状态码: %s % exc.status_code) print(响应头: %s % dict(exc.headers))InvalidStatusCode的headers里经常能看到服务端自带的X-Reject-Reason之类字段比盲猜强太多。6. 踩坑记录与排查速查表6.1 握手阶段报错怎么定位握手失败的排查顺序我认为是固定的先看状态码再看响应头最后才是 body。401 基本就是 token 问题检查有没有带Bearer前缀、token 是不是过期了、是不是被 URL 编码过403 多半是Origin或 UA 被拦把浏览器的请求头扒下来逐条对比400 一般是 header 格式不合法比如某一行少了冒号或者重复了Host。websocket-client抛出的WebSocketBadStatusException除了状态码还带resp_body有些服务端在拒绝时会在 body 里写一段 JSON 说明原因可惜大部分人没注意到。我一般在异常处理里顺手打一下前 500 个字符往往能省掉整个下午。还有一个隐蔽的情况服务端返回的是200 OK而不是101。这通常意味着 URL 打到了普通的 HTTP 路由上或者 nginx 那层没配proxy_set_header Upgrade $http_upgrade请求根本没被转发到 WebSocket 服务。6.2 连上之后的问题断连、分片与日志噪音101之后立刻断开第一嫌疑是Sec-WebSocket-Protocol协商不一致第二嫌疑是服务端在等客户端发第一条业务消息超时没等到就踢人。我的习惯是on_open里立刻发一条心跳或认证消息别让连接“空转”。消息收不全的问题也很常见尤其是传输大 JSON 时。websockets默认max_size是 1MiB超了会直接关闭连接并抛PayloadTooLarge代码里显式调大这个值就行。websocket-client那边没有大小限制但要注意on_message回调里做重活会阻塞收包线程解析大 JSON 建议丢到队列里交给别的线程处理。日志方面强烈建议在on_message里截断打印前 200 个字符。我见过有人直接print(message)一条消息几十 KB日志文件半天涨到几个 G磁盘满了才发现问题不在连接而在日志。6.3 高频问题速查表现象大概率原因处理动作401 Unauthorizedtoken 缺失、过期、前缀写错检查Authorization完整性403 ForbiddenOrigin/ UA 被拦补齐浏览器风格 header400 Bad Requestheader 格式错、重复Host打印原始 header 行逐条核对200 而非 101网关未转发 Upgrade检查反向代理配置101 后秒断子协议未协商、未发首条消息补Sec-WebSocket-Protocolopen 后立即发消息空闲约 60 秒断开中间设备空闲超时开启ping_interval设 20 到 30 秒InvalidStatusCode无细节只打了str(exc)打印exc.status_code与exc.headersPayloadTooLarge单帧超过max_size调大max_sizeModuleNotFoundError解释器装串了用python3.6 -m pip重装6.4 几条不太写在文档里的经验第一条先把 header 调通再考虑并发。我见过太多人一上手就写异步池结果跑不通不知道是 header 错还是协程调度错最后把两件事一起推翻重来。用同步脚本验证协议层花的时间远小于在异步代码里猜。第二条抓包工具的优先级高于一切猜测。把真实客户端的握手请求抓下来和自己的脚本生成的请求并排放着对比差异一目了然。很多库支持打开调试日志websocket-client可以用websocket.enableTrace(True)输出里能完整看到发出去的 header 行比自己拼字符串验证可靠得多。第三条token 别硬编码在脚本里。老环境里跑的一次性脚本很容易被随手丢进代码仓库Authorization写死在源码里是常见事故。用环境变量读取或者从命令行参数传入多花两行代码的事。第四条如果服务端返回的close帧带了状态码一定要打出来。1008表示策略违规1009表示消息过大1011表示服务端内部错误这几个码能直接把排查方向锁定比看任意一行业务日志都管用。一个能长期跑着的模拟客户端脚本代码量其实不大难点全在那些不会写在接口文档里的约束上谁校验 UA、谁校验 Origin、心跳该多快、重连该多慢。这些参数只能靠一轮轮试出来试出来之后一定要写进注释隔两个月再回来看你会感谢当时留下的那几行说明。