feat: 初步完成调度台适配
This commit is contained in:
DLmaster361
388
docs/Backend_Task_Scheduling_and_WebSocket_Messages.md
Normal file
388
docs/Backend_Task_Scheduling_and_WebSocket_Messages.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# AUTO-MAS 后端任务调度逻辑与WebSocket消息格式说明
|
||||
|
||||
## 1. 任务调度架构概览
|
||||
|
||||
AUTO-MAS 后端采用基于 AsyncIO 的异步任务调度系统，主要由以下核心组件构成：
|
||||
|
||||
### 1.1 核心组件
|
||||
|
||||
- **TaskManager**: 任务调度器，负责任务的创建、运行、停止和清理
|
||||
- **Broadcast**: 消息广播系统，负责在不同组件间传递消息
|
||||
- **WebSocket**: 与前端的实时通信通道
|
||||
- **Config**: 配置管理系统，包含脚本配置、队列配置等
|
||||
|
||||
### 1.2 任务类型
|
||||
|
||||
系统支持三种主要任务模式：
|
||||
|
||||
1. **设置脚本** - 直接执行单个脚本配置
|
||||
2. **自动代理** - 按队列顺序自动执行多个脚本
|
||||
3. **人工排查** - 手动排查和执行任务
|
||||
|
||||
## 2. 任务调度流程
|
||||
|
||||
### 2.1 任务创建流程
|
||||
|
||||
```
|
||||
前端请求 → API接口 → TaskManager.add_task() → 任务验证 → 创建异步任务 → 返回任务ID
|
||||
```
|
||||
|
||||
**具体步骤：**
|
||||
|
||||
1. **任务验证**: 根据模式和UID验证任务配置是否存在
|
||||
2. **重复检查**: 确保相同任务未在运行中
|
||||
3. **任务创建**: 使用`asyncio.create_task()`创建异步任务
|
||||
4. **回调设置**: 添加任务完成回调用于清理工作
|
||||
|
||||
### 2.2 任务执行流程
|
||||
|
||||
#### 设置脚本模式
|
||||
```
|
||||
获取脚本配置 → 确定脚本类型(MAA/General) → 创建对应Manager → 执行任务
|
||||
```
|
||||
|
||||
#### 自动代理模式
|
||||
```
|
||||
获取队列配置 → 构建任务列表 → 逐个执行脚本 → 更新状态 → 发送完成信号
|
||||
```
|
||||
|
||||
### 2.3 任务状态管理
|
||||
|
||||
- **等待**: 任务已加入队列但未开始执行
|
||||
- **运行**: 任务正在执行中
|
||||
- **跳过**: 任务因重复或其他原因被跳过
|
||||
- **完成**: 任务执行完毕
|
||||
|
||||
## 3. WebSocket 消息系统
|
||||
|
||||
### 3.1 消息基础结构
|
||||
|
||||
所有WebSocket消息都遵循统一的JSON格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "消息ID或任务ID",
|
||||
"type": "消息类型",
|
||||
"data": {
|
||||
"具体数据": "根据类型而定"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 消息类型详解
|
||||
|
||||
#### 3.2.1 Update 类型 - 数据更新
|
||||
|
||||
**用途**: 通知前端更新界面数据
|
||||
|
||||
**常见数据格式:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Update",
|
||||
"data": {
|
||||
"user_list": [
|
||||
{
|
||||
"name": "用户名",
|
||||
"status": "运行状态",
|
||||
"config": "配置信息"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Update",
|
||||
"data": {
|
||||
"task_list": [
|
||||
{
|
||||
"script_id": "脚本ID",
|
||||
"status": "等待/运行/完成/跳过",
|
||||
"name": "脚本名称"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Update",
|
||||
"data": {
|
||||
"log": "任务执行日志内容"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.2 Info 类型 - 信息显示
|
||||
|
||||
**用途**: 向前端发送需要显示的信息，包括普通信息、警告和错误
|
||||
|
||||
**数据格式:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Info",
|
||||
"data": {
|
||||
"Error": "错误信息内容"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Info",
|
||||
"data": {
|
||||
"Warning": "警告信息内容"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Info",
|
||||
"data": {
|
||||
"Info": "普通信息内容"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.3 Message 类型 - 对话框请求
|
||||
|
||||
**用途**: 请求前端弹出对话框显示重要信息
|
||||
|
||||
**数据格式:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Message",
|
||||
"data": {
|
||||
"title": "对话框标题",
|
||||
"content": "对话框内容",
|
||||
"type": "info/warning/error"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.4 Signal 类型 - 程序信号
|
||||
|
||||
**用途**: 发送程序控制信号和状态通知
|
||||
|
||||
**常见信号:**
|
||||
|
||||
**任务完成信号:**
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Signal",
|
||||
"data": {
|
||||
"Accomplish": "任务完成后调度台显示的日志内容"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**电源操作信号:**
|
||||
```json
|
||||
{
|
||||
"id": "task-uuid",
|
||||
"type": "Signal",
|
||||
"data": {
|
||||
"power": "NoAction/KillSelf/Sleep/Hibernate/Shutdown/ShutdownForce",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**心跳信号:**
|
||||
```json
|
||||
{
|
||||
"id": "Main",
|
||||
"type": "Signal",
|
||||
"data": {
|
||||
"Ping": "无描述"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "Main",
|
||||
"type": "Signal",
|
||||
"data": {
|
||||
"Pong": "无描述"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 任务管理器详细说明
|
||||
|
||||
### 4.1 TaskManager 核心方法
|
||||
|
||||
#### add_task(mode: str, uid: str)
|
||||
- **功能**: 添加新任务到调度队列
|
||||
- **参数**:
|
||||
- `mode`: 任务模式 ("设置脚本", "自动代理", "人工排查")
|
||||
- `uid`: 任务唯一标识符
|
||||
- **返回**: 任务UUID
|
||||
|
||||
#### stop_task(task_id: str)
|
||||
- **功能**: 停止指定任务
|
||||
- **参数**:
|
||||
- `task_id`: 任务ID，支持 "ALL" 停止所有任务
|
||||
|
||||
#### run_task(mode: str, task_id: UUID, actual_id: Optional[UUID])
|
||||
- **功能**: 执行具体任务逻辑
|
||||
- **流程**: 根据模式选择相应的执行策略
|
||||
|
||||
### 4.2 任务执行器
|
||||
|
||||
#### GeneralManager
|
||||
- **用途**: 处理通用脚本任务
|
||||
- **特点**: 支持自定义脚本路径和参数
|
||||
- **配置**: 基于 GeneralConfig 和 GeneralUserConfig
|
||||
|
||||
#### MaaManager
|
||||
- **用途**: 处理MAA (明日方舟助手) 专用任务
|
||||
- **特点**: 支持模拟器控制、ADB连接、游戏自动化
|
||||
- **配置**: 基于 MaaConfig 和 MaaUserConfig
|
||||
|
||||
## 5. 消息广播系统
|
||||
|
||||
### 5.1 Broadcast 机制
|
||||
|
||||
- **设计模式**: 发布-订阅模式
|
||||
- **功能**: 实现组件间解耦的消息传递
|
||||
- **特点**: 支持多个订阅者同时接收消息
|
||||
|
||||
### 5.2 消息流向
|
||||
|
||||
```
|
||||
任务执行器 → Broadcast → WebSocket → 前端界面
|
||||
↓
|
||||
其他订阅者
|
||||
```
|
||||
|
||||
## 6. 配置管理系统
|
||||
|
||||
### 6.1 配置类型
|
||||
|
||||
- **ScriptConfig**: 脚本配置，包含MAA和General两种类型
|
||||
- **QueueConfig**: 队列配置，定义自动代理任务的执行顺序
|
||||
- **GlobalConfig**: 全局系统配置
|
||||
|
||||
### 6.2 配置操作
|
||||
|
||||
- **锁机制**: 防止配置在使用时被修改
|
||||
- **实时更新**: 支持动态加载配置变更
|
||||
- **类型验证**: 确保配置数据的正确性
|
||||
|
||||
## 7. API 接口说明
|
||||
|
||||
### 7.1 任务控制接口
|
||||
|
||||
**创建任务**
|
||||
- **端点**: `POST /api/dispatch/start`
|
||||
- **请求体**:
|
||||
```json
|
||||
{
|
||||
"mode": "自动代理|人工排查|设置脚本",
|
||||
"taskId": "目标任务ID"
|
||||
}
|
||||
```
|
||||
- **响应**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"status": "success",
|
||||
"message": "操作成功",
|
||||
"websocketId": "新任务ID"
|
||||
}
|
||||
```
|
||||
|
||||
**停止任务**
|
||||
- **端点**: `POST /api/dispatch/stop`
|
||||
- **请求体**:
|
||||
```json
|
||||
{
|
||||
"taskId": "要停止的任务ID"
|
||||
}
|
||||
```
|
||||
|
||||
**电源操作**
|
||||
- **端点**: `POST /api/dispatch/power`
|
||||
- **请求体**:
|
||||
```json
|
||||
{
|
||||
"signal": "NoAction|Shutdown|ShutdownForce|Hibernate|Sleep|KillSelf"
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 WebSocket 连接
|
||||
|
||||
**端点**: `WS /api/core/ws`
|
||||
|
||||
**连接特性**:
|
||||
- 同时只允许一个WebSocket连接
|
||||
- 自动心跳检测 (15秒超时)
|
||||
- 连接断开时自动清理资源
|
||||
|
||||
## 8. 错误处理机制
|
||||
|
||||
### 8.1 异常类型
|
||||
|
||||
- **ValueError**: 配置验证失败
|
||||
- **RuntimeError**: 任务状态冲突
|
||||
- **TimeoutError**: 操作超时
|
||||
- **ConnectionError**: 连接相关错误
|
||||
|
||||
### 8.2 错误响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "相关任务ID",
|
||||
"type": "Info",
|
||||
"data": {
|
||||
"Error": "具体错误描述"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 9. 性能和监控
|
||||
|
||||
### 9.1 日志系统
|
||||
|
||||
- **分层日志**: 按模块划分日志记录器
|
||||
- **实时监控**: 支持日志实时推送到前端
|
||||
- **文件轮转**: 自动管理日志文件大小
|
||||
|
||||
### 9.2 资源管理
|
||||
|
||||
- **进程管理**: 自动清理子进程
|
||||
- **内存监控**: 防止内存泄漏
|
||||
- **连接池**: 复用数据库和网络连接
|
||||
|
||||
## 10. 安全考虑
|
||||
|
||||
### 10.1 输入验证
|
||||
|
||||
- **参数校验**: 使用 Pydantic 模型验证
|
||||
- **路径安全**: 防止路径遍历攻击
|
||||
- **命令注入**: 严格控制执行的命令参数
|
||||
|
||||
### 10.2 权限控制
|
||||
|
||||
- **单一连接**: 限制WebSocket连接数量
|
||||
- **操作限制**: 防止重复或冲突操作
|
||||
- **资源保护**: 防止资源滥用
|
||||
|
||||
---
|
||||
|
||||
*此文档基于 AUTO-MAS v5.0.0 版本编写，详细的API文档和配置说明请参考相关配置文件和源代码注释。*
|
||||
Reference in New Issue
Block a user