lucky-cat/docs/knowledge vault/bugfix-websocket-fresh-auth-reconnect.zh-CN.md

WebSocket 断线后使用新鉴权上下文重连：问题原因与修复方案

1. 对应提交

273550b fix(multimodal): reconnect websocket with fresh auth

本文说明多模态 WebSocket 在运行过程中断开后，设备可能持续重连失败、无法继续唤醒对话，而重启设备后又可以恢复的问题。

2. 用户可见现象

典型表现如下：

1. 设备启动后能够正常连接并完成若干轮对话；
2. 运行过程中 WebSocket 出现 error 或 disconnected；
3. 后续日志反复出现连接失败，设备无法重新进入可用的语音会话；
4. Wi-Fi 本身可能仍显示已连接；
5. 重启设备后，连接通常能够立即恢复。

“重启后恢复”说明问题不一定来自远端服务长期不可用。如果远端服务或公网一直不可达，重启设备一般也不会立刻解决。这个现象更符合设备内部旧 WebSocket、旧鉴权 Header 或重连状态没有被完整清理。

3. 原有设计的问题

3.1 WebSocket 重连存在两个控制者

修复前，底层 WebSocket 客户端配置为：

.disable_auto_reconnect = false,
.enable_close_reconnect = true,

这意味着底层库可以自行重连。同时，项目的 control-plane 也负责鉴权、创建连接、处理断线和调度下一次启动。

因此一次断线后可能同时存在两条恢复路径：

底层 WebSocket 库
    └─ 使用原客户端和原 Header 自动重连

control-plane
    └─ 将会话标记为不可用，准备重新鉴权和创建连接

两套状态机并不共享完整状态，容易产生以下不一致：

• control-plane 已认为连接不可用，但底层仍在自动重连；
• control-plane 已清空当前会话鉴权信息，但旧客户端仍持有创建时的 Header；
• 新一轮启动与旧客户端的关闭、回调或重连交错；
• 上层看到“未连接”，底层却可能仍处于 connecting、closing 或 reconnecting；
• 旧连接的异步回调可能影响新一轮连接。

3.2 WebSocket error/disconnected 没有强制回收旧 transport

修复前，control_plane_multimodal_mark_transport_unavailable() 会清理上层状态，但只有部分原因会触发底层 transport stop：

• 协议错误；
• 文本发送失败；
• listening 超时；
• no-response 超时。

以下两个最直接代表 WebSocket 已失效的原因却没有进入强制关闭条件：

CONTROL_PLANE_TRANSPORT_LOSS_WS_ERROR
CONTROL_PLANE_TRANSPORT_LOSS_WS_DISCONNECTED

结果是上层状态已经退休，底层旧客户端却可能继续存在并自行重连。

3.3 断线事件没有稳定地调度新一轮连接

修复前，收到 transport error/disconnected 后主要执行：

• 清理待处理的云端业务状态；
• 停止音频上行。

但没有在这两个事件中明确调度一次新的 WebSocket 启动。因此恢复可能依赖底层自动重连，或者依赖后续其他状态变化碰巧触发连接。

3.4 一次启动失败后，重试请求可能被消费掉

Wi-Fi 状态任务会消费 ws_start_requested。修复前，如果本次 control_plane_try_start_multimodal_from_state_machine() 返回失败，请求已经被消费，但没有立即重新挂起。

这样会出现：

收到重连请求
    ↓
本次启动失败
    ↓
请求被消费
    ↓
没有新的触发条件
    ↓
设备长期停留在未连接状态

4. 根本原因

根本原因不是单次网络错误，而是 WebSocket 恢复流程的所有权不唯一：

底层库自动重连旧客户端
        ＋
control-plane 清理并重建会话
        ＋
WS 错误时旧 transport 未被强制回收
        ＋
启动失败后重试请求可能丢失
        ↓
旧连接、旧 Header 和新会话状态互相干扰
        ↓
运行中持续连接失败，重启后因全部状态重建而恢复

5. 修复方案

5.1 禁止底层 WebSocket 自动重连

配置改为：

.disable_auto_reconnect = true,
.enable_close_reconnect = false,

底层 transport 只负责一条连接的建立、收发和关闭，不再私自决定重连。

重连所有权统一交给 control-plane：

WebSocket 异常
    ↓
通知 control-plane
    ↓
退休旧 transport
    ↓
重新进入多模态启动流程
    ↓
重新取得当前有效鉴权信息并生成连接 Header
    ↓
创建新的 WebSocket 客户端

5.2 WS error/disconnected 必须关闭旧 transport

以下原因被加入 close_transport 判断：

CONTROL_PLANE_TRANSPORT_LOSS_WS_ERROR
CONTROL_PLANE_TRANSPORT_LOSS_WS_DISCONNECTED

这保证上层判定 WebSocket 不可用时，底层旧客户端也会被停止，而不是留在后台继续使用旧状态重连。

5.3 断线和错误事件主动调度重连

处理以下事件时，明确调用 control_plane_schedule_websocket_wait_task()：

CONTROL_PLANE_MULTIMODAL_EVENT_TRANSPORT_DISCONNECTED
CONTROL_PLANE_MULTIMODAL_EVENT_TRANSPORT_ERROR

因此恢复不再依赖底层自动重连或其他偶发事件。

5.4 启动失败后重新挂起重试请求

Wi-Fi 状态任务尝试启动 WebSocket 后会检查结果：

if (!ws_started) {
    (void)control_plane_schedule_websocket_wait_task();
}

本次失败不会永久吃掉重试机会。后续仍由既有状态机和退避节奏继续尝试。

5.5 增加架构守卫

架构检查脚本增加规则，防止后续修改重新引入以下行为：

• 再次开启底层 WebSocket 自动重连；
• WS error/disconnected 不再回收旧 transport；
• transport error/disconnected 不再调度 control-plane 重连；
• 启动失败后不重新安排重试。

这条守卫的目的不是运行时恢复，而是在构建或代码检查阶段阻止同类设计回退。

6. “fresh auth”的准确含义

这里的 fresh auth 更准确地说是：

不复用旧 WebSocket 客户端内部固化的鉴权 Header，而是销毁旧 transport，重新通过 control-plane 的鉴权与建连流程构造连接。

它不必然表示每次断线都强制向服务端申请一个全新的 JWT。设备鉴权模块仍可能复用尚未过期、权限范围正确的有效 JWT。

两者的区别是：

概念	含义
重新走鉴权建连流程	重新检查当前鉴权状态，并为新客户端生成当前有效的连接参数和 Header。此次修复保证做到这一点。
强制刷新 JWT	无论现有 JWT 是否有效，都向鉴权服务申请新 JWT。此次提交并没有要求每次都这样做。

7. 修复后的影响

正面影响

• WebSocket 重连只有一个控制者；
• 每轮重连前会回收旧客户端；
• 避免旧连接回调污染新会话；
• 重连会重新经过项目自己的鉴权和状态检查；
• 单次启动失败后仍能继续重试；
• 运行中断线后的行为更接近重启设备后的干净启动流程。

代价

• 每次 WebSocket error/disconnected 都需要销毁并新建 transport；
• 相比底层直接原地自动重连，会多经过一次清理和 control-plane 调度；
• 如果需要刷新鉴权，还会增加鉴权请求时间；
• 但换来的是状态一致性和可恢复性，避免设备陷入长期不可用状态。

该提交只重建多模态 WebSocket，不会主动让 Wi-Fi STA 断开并重新关联路由器。Wi-Fi 重关联属于另一层恢复策略。

8. 关键日志

修复后重点关注：

Schedule fresh-auth reconnect after transport disconnect
Schedule fresh-auth reconnect after transport error
Retire unavailable transport: reason=...; next start requires fresh auth

预期顺序大致为：

transport error/disconnected
    ↓
Retire unavailable transport
    ↓
Schedule fresh-auth reconnect
    ↓
旧 transport 完成清理
    ↓
鉴权准备
    ↓
新 WebSocket 建立成功

如果只看到反复的 schedule，但没有旧 transport 清理完成或新鉴权开始，应继续检查 transport stop 是否卡住。如果鉴权成功但新 WebSocket 仍连接失败，应继续区分 DNS、TCP/TLS 和远端拒绝问题。

9. 建议验证方法

1. 正常完成多轮语音对话，确认基础流程不受影响；
2. 对话空闲时短暂关闭路由器或屏蔽网络，制造 WebSocket disconnect；
3. 恢复网络，确认设备会退休旧 transport，并自动创建新连接；
4. 在 TTS 播放或音频上行期间制造断网，确认上行停止且不会留下假连接；
5. 连续重复断网、恢复至少 10 次，确认不需要重启设备；
6. 检查每次新连接前是否都有明确的旧 transport 清理过程；
7. 检查没有出现底层 WebSocket 自行无限重连的日志循环。

10. 涉及文件

components/control_plane/src/multimodal/control_plane_multimodal_runtime.c
components/control_plane/src/multimodal/control_plane_multimodal_session_service.c
components/control_plane/src/runtime/control_plane_runtime_workers.c
components/platform/src/multimodal/transport_ws/transport_ws_workers_impl.c
tools/check_architecture_guards.sh