NapCatQQ项目中WebSocket服务关闭连接未断开问题分析

问题背景

在NapCatQQ项目（一个基于QQNT的机器人框架）的3.1.10版本中，发现当通过WebUI关闭正向WebSocket服务时，已建立的WebSocket连接未能正常断开。同时，客户端也未收到预期的生命周期元事件通知（lifecycle类型的meta_event）。这导致服务重启后客户端仍无法正常接收消息上报，影响了系统的可靠性和可维护性。

问题现象

1. 连接保持异常：服务端关闭WebSocket服务后，客户端连接仍保持活跃状态，未触发连接断开异常
2. 生命周期事件缺失：未按OneBot协议规范发送sub_type为disable的lifecycle元事件
3. 服务恢复异常：重新开启服务后，原有连接无法恢复消息接收功能

技术分析

WebSocket服务管理机制

NapCatQQ采用动态配置热重载机制管理WebSocket服务。从日志可见，配置变更时会触发服务重启：

[OneBot11] 热重载
WebSocket服务 已启动/未启动

然而，服务关闭时仅停止了新连接监听，未主动断开现有连接，这违反了WebSocket服务管理的常规实践。

OneBot协议实现缺陷

根据OneBot v11协议规范，生命周期事件应包含：

• enable：连接建立时触发
• disable：连接断开时触发

当前实现缺少disable事件通知，导致客户端无法感知服务端状态变化。

连接保持机制

客户端通过定期PING/PONG维持连接，即使服务端已"关闭"，TCP连接仍保持活跃：

发送keepalive ping
接收keepalive pong

这种设计使得客户端无法通过常规心跳机制检测服务端不可用状态。

解决方案建议

1. 完善连接终止逻辑

   • 服务关闭时主动断开所有活跃连接
   • 发送标准WebSocket关闭帧(Close Frame)
   • 记录连接终止日志

2. 实现完整生命周期事件

   • 补充disable类型元事件发送
   • 确保事件格式符合OneBot规范

3. 增强重连机制

   • 客户端应实现指数退避重连策略
   • 服务端重启后应清除无效连接状态

影响评估

该问题主要影响以下场景：

• 服务端配置热更新时
• 系统维护性重启过程中
• 客户端需要精确感知服务状态的自动化流程

及时修复将提升系统在动态环境下的可靠性，确保状态变更的及时通知和连接管理的正确性。