OTA 固件升级

OTA（Over-the-Air）固件升级模块，由 yudao-module-iot 后端模块的 ota 包实现。它支持对设备进行远程固件升级，包括固件版本管理、升级任务下发、设备升级进度追踪等功能。例如：

• 上传新版固件，批量升级产品下的所有设备
• 选择指定设备进行定向升级，实时查看每台设备的升级进度

OTA 固件升级主要由固件管理、升级任务、升级记录三部分组成。如下图所示：

1. 固件管理

固件管理，由 IotOtaFirmwareController 提供接口。每个固件关联一个产品，包含版本号和固件文件。

1.1 表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `iot_ota_firmware` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '固件编号',
  `name` varchar(128) NOT NULL COMMENT '固件名称',
  `description` varchar(512) DEFAULT '' COMMENT '固件描述',
    
  `version` varchar(64) NOT NULL COMMENT '版本号',
    
  `product_id` bigint NOT NULL COMMENT '产品编号',
    
  `file_url` varchar(1024) NOT NULL COMMENT '固件文件 URL',
  `file_size` bigint NOT NULL COMMENT '固件文件大小',
  `file_digest_algorithm` varchar(32) NOT NULL COMMENT '固件文件签名算法',
  `file_digest_value` varchar(256) NOT NULL COMMENT '固件文件签名结果',
    
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='IoT OTA 固件表';

① name、description：固件的基本信息，用于展示。

② version：固件版本号。同一产品下，版本号唯一，不允许重复。

③ product_id：关联的产品编号，表示该固件适用于哪个产品。创建后不可修改。

④ file_url：固件文件的下载地址。创建固件时上传文件，系统自动存储并生成 URL。file_size：固件文件大小（字节）。由系统在创建时自动计算。

file_digest_algorithm、file_digest_value：文件签名算法和签名值。目前使用 MD5 算法，创建时自动计算，用于设备端校验固件完整性。

1.2 管理后台（列表）

对应 [IoT 物联网 -> 运维管理 -> OTA 固件] 菜单，对应前端项目的 @/views/iot/ota/firmware 目录。

1.3 管理后台（创建/编辑）

① 点击【新增】按钮，弹出表单对话框。

② 编辑固件时，仅可修改固件名称和固件描述，版本号和固件文件为只读展示。

1.4 管理后台（详情）

在固件列表点击【详情】按钮，进入固件详情页。

2. 升级任务

升级任务，由 IotOtaTaskController 提供接口。每个任务关联一个固件，指定设备升级范围，并跟踪整体升级进度。

2.1 表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `iot_ota_task` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '任务编号',
  `name` varchar(255) NOT NULL COMMENT '任务名称',
  `description` varchar(1000) DEFAULT NULL COMMENT '任务描述',
    
  `firmware_id` bigint unsigned NOT NULL COMMENT '固件编号',
    
  `status` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '任务状态',
    
  `device_scope` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '设备升级范围',
    
  `device_total_count` int unsigned NOT NULL DEFAULT '0' COMMENT '设备总数',
  `device_success_count` int unsigned NOT NULL DEFAULT '0' COMMENT '设备成功数量',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='IoT OTA 升级任务表';

① name、description：任务的基本信息。同一固件下，任务名称不允许重复。

② firmware_id：关联的固件编号。

③ status：任务状态，参见 IotOtaTaskStatusEnum 枚举：

④ device_scope：设备升级范围，参见 IotOtaTaskDeviceScopeEnum 枚举：

⑤ device_total_count、device_success_count：设备总数和升级成功数量，用于展示升级进度。

2.2 管理后台（列表 & 创建）

① 升级任务列表嵌套在固件详情页中，对应前端项目的 @/views/iot/ota/task/OtaTaskList.vue 组件。

② 点击【新增任务】按钮，弹出创建表单：

2.3 管理后台（详情）

在任务列表点击【详情】按钮，弹出任务详情对话框。

3. 升级记录

升级记录，由 IotOtaTaskRecordController 提供接口。每条记录对应一台设备在某个任务中的升级状态。

3.1 表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `iot_ota_task_record` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '记录编号',
    
  `firmware_id` bigint unsigned NOT NULL COMMENT '固件编号',
  `task_id` bigint unsigned NOT NULL COMMENT '任务编号',
  `device_id` bigint unsigned NOT NULL COMMENT '设备编号',
  `from_firmware_id` bigint unsigned DEFAULT NULL COMMENT '来源固件编号',
    
  `status` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '升级状态',
    
  `progress` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '升级进度（0-100）',
  `description` varchar(500) DEFAULT NULL COMMENT '升级进度描述',
    
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='IoT OTA 升级任务记录表';

① firmware_id、task_id、device_id：关联的固件、任务和设备编号。from_firmware_id：设备升级前的固件版本编号，用于记录"从哪个版本升级"。

② status：升级状态，参见 IotOtaTaskRecordStatusEnum 枚举：

③ progress：升级进度百分比（0-100），由设备上报更新。description：升级进度描述，记录升级过程中的状态说明。取消时会记录取消原因。

3.2 状态流转

设备升级状态的流转路径如下：

待升级 → 已推送 → 升级中 → 升级成功
                      → 升级失败

待升级/已推送/升级中 → 已取消【管理员手动取消】

4. 设备消息

OTA 升级过程中，平台与设备之间通过消息进行通信。下面以 MQTT 协议为例，说明涉及的两个 Topic：

参见 IotDeviceMessageMethodEnum 枚举中的 OTA_UPGRADE 和 OTA_PROGRESS。Topic DTO 位于 yudao-module-iot-core 模块的 core/topic/ota 包下。

4.1 平台推送升级消息

平台通过 IotOtaUpgradeJob 定时扫描待升级记录，对在线设备推送升级消息。消息经由平台 → 网关 → MQTT Broker → 设备。

消息的 params 数据结构如下：

{
    "version": "1.0.2",
    "fileUrl": "https://example.com/firmware/v1.0.2.bin",
    "fileSize": 1048576,
    "fileDigestAlgorithm": "MD5",
    "fileDigestValue": "d41d8cd98f00b204e9800998ecf8427e"
}

4.2 设备上报升级进度

设备收到升级消息后，开始下载固件并安装。在升级过程中，设备通过 MQTT → 网关 → 平台上报升级进度。

消息的 params 数据结构如下：

{
    "version": "1.0.2",
    "status": 20,
    "progress": 75,
    "description": "downloading firmware..."
}

平台收到设备上报的进度消息后，由 IotDeviceMessageServiceImpl 路由到 IotOtaTaskRecordService 的 #updateOtaRecordProgress(...) 方法进行处理：更新升级记录的状态和进度，升级成功时自动更新设备固件版本号，并检查任务是否全部完成。