17370845950

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、ws npm 包）都内置自动 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 间隔、Ngi

nx proxy_read_timeout、客户端保活逻辑三者必须严格对齐，差 5 秒都可能导致静默掉线。