WebSocket 实时通信系统

概述

mower-ng 服务端在 /ws 端点上使用 WebSocket 向前端主动推送数据。客户端可以通过 WebSocket 连接向后端发送订阅配置，让后端选择性推送指定类型的数据。

WebSocket 连接无需鉴权，这样用户配置 mower-ng helper 时更方便（虽然现在 helper 还没有接入 WebSocket）。

后端推送数据格式

所有类型的 WebSocket 消息都采用统一的 JSON 格式。不同类型通过 type 字段区分，其它字段中包括具体数据。

{
  "type": "消息类型标识",
  "其它字段": "具体数据"
}

客户端配置方法

客户端通过发送 JSON 配置对象来控制接收的数据类型。例如网页前端在 ui/src/components/WebSocket.vue 中设置开启以下五类数据的推送：

{
  "log": true,
  "sc": true,
  "conf": true,
  "screenshot": true,
  "thread_status": true
}

每个布尔值字段控制对应类型数据的接收与否。

在 ui/src/pages/Log.vue 中，当用户调整选项开启或关闭截图显示时，也会向后端发送截图的订阅配置。

默认配置说明：

后端在 WebSocket 连接建立时会设置默认配置 push_config。目前只有日志推送是默认开启的，其他数据类型都需要客户端显式配置后才能接收。

后端初始连接发送数据

当 WebSocket 连接建立时，后端会自动发送以下初始数据：

1. 日志数据：发送最近的历史日志记录
2. 线程状态：发送当前程序的运行状态
3. 性能通知：如果存在性能指标通知（截图性能数据），也会一并发送

这些初始数据会在客户端发送任何配置之前发送，无视客户端发送的配置选项。

数据类型

1. 实时日志监控（mower/utils/log.py 的 whlr 对象）

• 功能描述：实时推送程序运行日志到前端界面
• 默认开启：是
• 初始连接发送：是（发送最近的历史日志）
• 数据格式：

{
  "type": "log",
  "data": "具体的日志文本内容"
}

2. 运行截图预览（mower/utils/log.py 的 save_screenshot 函数）

• 功能描述：将截图实时推送到前端显示
• 默认开启：否
• 初始连接发送：否
• 数据格式：

{
  "type": "sc",
  "data": "data:image/jpeg;base64,...（base64编码的图片数据）"
}

3. 线程状态监控（mower/utils/config/__init__.py 的 update_thread_status 函数）

• 功能描述：实时监控程序线程的运行状态
• 默认开启：否
• 初始连接发送：是（发送当前线程状态）
• 数据格式：

{
  "type": "thread_status",
  "data": "RUNNING" // 可能的值：RUNNING, STOPPED, STOPPING, IDLE
}

4. 配置同步更新（mower/utils/config/__init__.py 的 save_conf 函数）

• 功能描述：通知前端配置文件已更新，需要重新加载
• 默认开启：否
• 初始连接发送：否
• 数据格式：

{
  "type": "conf",
  "time": 1640995200000 // 配置更新时间戳
}

注意：因为 WebSocket 连接无需鉴权，因此只发送时间戳，更新后的配置内容需要客户端从需要鉴权的 HTTP 端点获取。

5. 性能指标展示（mower/solvers/credit.py 的 upload_data 函数）

• 功能描述：推送截图性能数据用于前端展示
• 默认开启：否
• 初始连接发送：是（如果存在性能通知）
• 数据格式：

{
  "type": "screenshot",
  "msg": "性能描述信息",
  "color": "颜色标识"
}

6. 任务列表更新（暂未启用，mower/utils/config/__init__.py）

• 功能描述：推送基建任务列表的更新信息
• 默认开启：否
• 初始连接发送：否
• 数据格式：

{
  "type": "task_list",
  "data": ["任务对象数组"]
}