FastAPI WebSocket 默认不自动处理 ping/pong，需手动调用 websocket.ping() 并配合定时任务每20–30秒发送一次；同时须配置 Nginx proxy_read_timeout 与心跳间隔对齐，并确保 WebSocket 升级头正确设置。
FastAPI 的 WebSocket 默认不自动处理 ping/pong
FastAPI 基于 Starlette 实现 WebSocket，底层使用 websockets 库，但 WebSocketEndpoint 或 websocket_route 并不会自动响应 ping 帧（opcode 9）或发送 pong（opcode 10）。浏览器或客户端发来的 ping 不会被自动回 pong，长时间无数据交互时连接容易被中间代理（如 Nginx、Cloudflare）或防火墙断开。
必须手动调用 websocket.ping() 触发心跳
Starlette 的 WebSocket 对象提供了 ping() 方法，但它是**单向触发发送 pong 帧**的工具，不是周期性心跳开关。它不接收参数，也不自动重试，且仅在连接活跃时有效。常见错误是误以为调用一次就能“开启心跳”——实际必须配合定时任务反复调用。
实操建议：
- 使用
asyncio.create_task()启动一个后台心跳协程，每 20–30 秒调用一次websocket.ping() - 务必在
try/except中包裹ping()调用，捕获ConnectionClosed或RuntimeError（例如连接已关闭时调用会抛异常） - 避免在
websocket.receive_text()等阻塞等待前才发 ping —— 心跳应独立运行，不能依赖业务消息驱动
客户端 ping 和服务端 pong 的分工要明确
WebSocket 协议中，ping/pong 是对称机制：任意一端可发 ping，另一端需回应 pong。但实践中更可靠的做法是「服务端主动 ping，客户端自动 pong」，因为：
- 现代浏览器和主流 WebSocket 客户端（如 JS
WebSocket、wsnpm 包）都内置自动 pong 响应逻辑，无需额外代码 - 服务端可控性强；而依赖客户端定时 ping 容易因前端页面失焦、JS 被节流等原因失效
- Nginx 等反向代理通常只检查服务端是否活跃，对客户端 ping 不敏感
示例心跳协程片段：
async def _send_ping(websocket: WebSocket):
while True:
try:
await websocket.ping()
except (ConnectionClosed, RuntimeError):
break
await asyncio.sleep(25)
在 connect 后立即启动：asyncio.create_task(_send_ping(websocket))
注意 Nginx 和超时配置的协同
即使 FastAPI 正确发送了 ping，若 Nginx 的 proxy_read_timeout 小于 ping 间隔，连接仍会被断开。典型错误配置：
- Nginx 默认
proxy_read_timeout 60，但服务端 ping 间隔设为 45 秒 → 中间空窗期可能超时 - 未设置
proxy_set_header Upgrade $http_upgrade和proxy_set_header Connection "upgrade"，导致 WebSocket 升级失败，ping/pong 根本不走 WebSocket 通道 - Cloudflare 免费版强制 100 秒闲置断连，此时 ping 间隔必须 ≤ 85 秒，且需开启 “WebSockets” 开关
关键点：服务端 ping 间隔、Nginx proxy_read_timeout、客户端保活逻辑三者必须严格对齐，差 5 秒都可能导致静默掉线。
