Python websockets ping_interval 和 ping_timeout 怎么配合保活

Python 的 websockets 里，这两个参数不是同一个“超时时间”：ping_interval 决定多久主动发一次 Ping，ping_timeout 决定发出 Ping 后等多久还没收到 Pong 就判定连接不可用。一般先保留默认的 20 秒和 20 秒；只有确认代理空闲时限、网络延迟或服务端处理能力后，再调整其中一个。

官方地址：https://websockets.readthedocs.io/en/stable/topics/keepalive.html

先看 ping_interval 和 ping_timeout 各管什么

当前稳定版文档中的 connect() 和 serve() 都支持这两个参数。默认配置会周期性发送 WebSocket Ping，并等待匹配的 Pong。前者解决“长时间没有业务消息”的空闲问题，后者解决“对端已经慢到不可用”的判断问题。

所以“把两个值都调成 5 秒”并不等于保活更可靠：它会增加 Ping 流量，也会让短暂抖动更快触发关闭。参数应围绕链路中的空闲时限和可接受故障发现时间来定。

从旧配置迁移到可解释的心跳组合

如果旧代码只写了 websockets.connect(url)，升级时不需要为了迁移强行增加业务心跳。先把参数显式写出来，方便审查和按环境调整：

import asyncio
from websockets.asyncio.client import connect
from websockets.exceptions import ConnectionClosed

async def consume(uri: str) -> None:
    # 20 秒发一次 Ping，20 秒内等不到 Pong 才关闭连接。
    async with connect(uri, ping_interval=20, ping_timeout=20) as ws:
        try:
            async for message in ws:
                # 业务消息仍由接收循环处理，不能把 Ping 当作业务心跳。
                print(message)
        except ConnectionClosed as exc:
            # 关闭原因交给上层重连策略，当前函数只负责记录并退出。
            print(f"WebSocket closed: code={exc.code} reason={exc.reason}")

asyncio.run(consume("wss://example.invalid/socket"))

三种组合可以先这样理解：

• 默认组合：适合大多数稳定公网连接，既保持流量又能发现失联。
• ping_timeout=None：适合允许偶发长延迟、但仍要避免代理把连接视为空闲的场景；代价是不会靠 Pong 超时主动清理。
• ping_interval=None：只适合由应用层或基础设施明确负责保活的场景，不能再期待 websockets 自动发现断线。

这里不建议把业务层“每 10 秒发一条 JSON heartbeat”和协议 Ping 混成一件事。协议 Ping 由库自动处理，应用层心跳只有在服务端定义了业务状态、租约或客户端可见确认时才有必要。

用异常和延迟指标判断是否真的断开

看到 ConnectionClosedError: sent 1011 ... keepalive ping timeout，首先说明的是 Pong 没有在当前 ping_timeout 窗口内回来，不一定说明服务端进程已经停止。官方 FAQ 把常见原因归为网络质量变差、接收方处理不过来，或者代理没有正确支持长连接。

排查时按下面顺序做，避免直接把超时值无限调大：

1. 记录关闭码、原因和发生时间，区分正常关闭与异常关闭。
2. 检查代理或负载均衡的空闲连接时限，确认它大于 ping_interval，并留出网络抖动余量。
3. 在可控诊断窗口调用一次 await ws.ping() 并等待返回的延迟值，观察是偶发尖峰还是持续升高。
4. 如果确认只是延迟尖峰，再增大 ping_timeout；如果是对端无响应，继续调大只会延迟故障发现。

async def sample_latency(ws) -> float:
    # ping() 返回等待对应 Pong 的 awaitable，结果是近似往返延迟秒数。
    pong_waiter = await ws.ping()
    latency = await pong_waiter
    return latency

上线前回归检查与边界清单

迁移完成后，至少覆盖四个状态：空闲连接能跨过代理的清理窗口；正常消息流不会被误当成协议 Ping；临时高延迟不会频繁误断；真正断网时上层能收到 ConnectionClosed 并执行自己的重连或告警策略。

• 客户端和服务端是否都明确写了参数，避免一侧默认值变化时无人知晓。
• ping_interval 是否小于链路中最短的空闲清理时间，并考虑抖动。
• ping_timeout 是否大于正常高峰期的往返延迟，而不是只按本地局域网延迟设置。
• 是否把协议级保活和业务级心跳、鉴权租约、重连退避分开记录。

常见问题

只把 ping_timeout 设为 None 会不会不再保活？

不会。Ping 仍按 ping_interval 发送，只是不再因为 Pong 超时自动关闭连接。需要自行监控异常连接，避免失联连接无限占用资源。

为什么 ping_interval 调小后断线反而变多？

更短的间隔会提高检测频率，也会增加流量和对短暂延迟的敏感度。先确认代理空闲时限，再按可接受的故障发现时间调整，不要只追求更小数字。

websockets 会自动处理对端发来的 Ping 吗？

会，协议层 Ping/Pong 由库处理。只有服务端另行定义了业务层心跳格式时，才需要在应用代码里实现对应消息。