Cheshire Cat AI核心项目WebSocket连接异常问题分析与解决方案

问题背景

在Cheshire Cat AI核心项目中，当用户通过WebSocket与系统交互时，如果用户在系统处理过程中突然断开连接，会导致WebSocket连接状态不一致的问题。具体表现为：当用户重新连接时，系统会尝试使用之前已建立的会话，但由于底层连接状态异常，会抛出"Unexpected ASGI message 'websocket.close'"运行时错误，导致用户无法继续正常交互，必须重启服务才能恢复。

问题复现与诊断

通过编写专门的复现脚本，我们可以系统性地重现这个问题：

1. 建立WebSocket连接并发送初始消息
2. 在系统处理响应过程中（特别是处理时间小于1秒时）强制断开连接
3. 尝试重新建立连接时出现异常

问题根源在于WebSocket连接状态管理的不一致性。当用户强制断开连接时，系统高层（Starlette框架）的WebSocket对象仍标记为"已连接"状态，而底层Python WebSocket实际上已断开。这种状态不一致导致后续操作失败。

解决方案

方案一：基础异常处理

在StrayCat类的__send_ws_json方法中添加针对ConnectionClosedOK异常的处理逻辑：

from websockets.exceptions import ConnectionClosedOK

def __send_ws_json(self, data: Any):
    try:
        asyncio.run_coroutine_threadsafe(
            self.__ws.send_json(data), loop=self.__main_loop
        ).result()
    except ConnectionClosedOK as ex:
        if ex.code == 1000:
            log.warning(ex)
            if self.__ws:
                del self.__ws
                self.__ws = None

这种处理方式能够捕获正常的连接关闭异常(代码1000)，并清理无效的WebSocket对象，防止状态不一致。

方案二：全面状态管理

为了更全面地处理各种异常情况，我们在连接管理层面增加了更通用的异常处理：

1. 在StrayCat类中添加专用方法：

async def close_connection(self):
    if self.__ws:
        try:
            await self.__ws.close()
        except RuntimeError as ex:
            log.warning(ex)
            if self.__ws:
                del self.__ws
                self.__ws = None

2. 在连接管理逻辑中使用该方法：

if user.id in strays.keys():
    stray = strays[user.id]
    await stray.close_connection()

这种方案不仅处理了正常关闭情况，还能应对各种运行时异常，确保WebSocket对象状态的一致性。

技术要点解析

1. WebSocket状态管理：WebSocket协议本身是无状态的，但应用层需要维护连接状态。当物理连接异常断开时，应用层状态可能不同步。

2. 异常处理策略：针对不同的异常类型(ConnectionClosedOK和RuntimeError)采用不同的处理方式，但核心逻辑都是清理无效状态。

3. 资源清理：显式地将WebSocket引用设为None，确保垃圾回收器可以正确回收资源。

4. 线程安全：使用asyncio.run_coroutine_threadsafe确保跨线程操作的安全性。

实施效果

经过上述修复后：

1. 用户强制断开连接时，系统能够优雅地处理异常并记录警告信息
2. 不会出现运行时错误阻塞后续连接
3. 用户可以重新建立连接并继续正常交互
4. 系统资源得到正确释放，避免内存泄漏

最佳实践建议

1. 对于实时通信系统，应始终实现完善的连接状态监测和异常处理机制
2. 考虑实现心跳机制来检测不活跃连接
3. 对于关键业务操作，应实现事务性保证，确保操作要么完整执行，要么完全回滚
4. 日志记录应包含足够的上下文信息，便于问题诊断

这种类型的连接管理问题在实时系统中很常见，本文提供的解决方案不仅适用于Cheshire Cat AI项目，也可为其他基于WebSocket的实时系统提供参考。