audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新wiki

Browse Source
This commit is contained in:
eafonyang
2026-07-01 11:26:23 +08:00
parent 864040f45b
commit cacee5f294
15 changed files with 579 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.qoder/repowiki/zh/content/核心功能模块/OTA固件管理.md
+404 -26
View File
@@ -3,34 +3,59 @@
<cite>
**本文档引用的文件**
- [backend/src/models/Ota.js](file://backend/src/models/Ota.js)
- [backend/src/models/BlackList.js](file://backend/src/models/BlackList.js)
- [backend/src/models/OtaTargetDevice.js](file://backend/src/models/OtaTargetDevice.js)
- [backend/src/routes/ota.js](file://backend/src/routes/ota.js)
- [backend/src/routes/blacklist.js](file://backend/src/routes/blacklist.js)
- [backend/src/routes/otaTargetDevice.js](file://backend/src/routes/otaTargetDevice.js)
- [backend/src/services/otaStorage.js](file://backend/src/services/otaStorage.js)
- [backend/src/validators/ota.js](file://backend/src/validators/ota.js)
- [backend/src/validators/blacklist.js](file://backend/src/validators/blacklist.js)
- [backend/src/validators/otaTargetDevice.js](file://backend/src/validators/otaTargetDevice.js)
- [backend/src/utils/response.js](file://backend/src/utils/response.js)
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [frontend/src/views/ota/index.vue](file://frontend/src/views/ota/index.vue)
- [frontend/src/views/blacklist/index.vue](file://frontend/src/views/blacklist/index.vue)
- [frontend/src/views/ota-target-device/index.vue](file://frontend/src/views/ota-target-device/index.vue)
- [frontend/src/api/ota.js](file://frontend/src/api/ota.js)
- [frontend/src/api/blacklist.js](file://frontend/src/api/blacklist.js)
- [frontend/src/api/otaTargetDevice.js](file://frontend/src/api/otaTargetDevice.js)
</cite>
## 更新摘要
**所做更改**
- 新增黑名单管理功能模块，支持设备黑名单维护
- 新增目标设备升级功能，支持定向升级控制
- 扩展OTA版本检查流程，增加黑名单和定向设备过滤逻辑
- 更新前端管理界面，新增黑名单和定向升级管理页面
- 增强OTA版本管理的完整性和安全性
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
6. [黑名单管理功能](#黑名单管理功能)
7. [目标设备升级功能](#目标设备升级功能)
8. [依赖关系分析](#依赖关系分析)
9. [性能考虑](#性能考虑)
10. [故障排除指南](#故障排除指南)
11. [结论](#结论)
12. [附录](#附录)
## 简介
本项目提供完整的OTA固件管理能力，涵盖固件版本管理、文件上传下载、强制更新配置以及设备端版本检查。系统支持两种设备型号：Luxsin-X8与Luxsin-X9，采用不同的存储策略：
- Luxsin-X8：通过S3对象存储进行分发
- Luxsin-X9：保存到本地文件系统
系统还提供了完善的前端管理界面，支持版本列表查询、新增/编辑/删除、文件上传、强制更新策略配置等功能。
**新增功能**：
- 黑名单管理：支持将特定设备MAC地址加入黑名单，阻止其接收OTA更新
- 目标设备升级：支持定向升级功能，仅允许指定设备接收特定OTA版本
- 增强的版本检查：在设备端版本检查时集成黑名单和定向设备过滤逻辑
系统还提供了完善的前端管理界面，支持版本列表查询、新增/编辑/删除、文件上传、强制更新策略配置、黑名单管理和定向升级管理等功能。
## 项目结构
后端采用Express + Sequelize架构，前端基于Vue3 + Element Plus构建。整体结构清晰，职责分离明确。
@@ -38,36 +63,66 @@
```mermaid
graph TB
subgraph "前端"
FE_View["OTA视图<br/>frontend/src/views/ota/index.vue"]
FE_API["OTA API封装<br/>frontend/src/api/ota.js"]
FE_OtaView["OTA视图<br/>frontend/src/views/ota/index.vue"]
FE_BlackListView["黑名单视图<br/>frontend/src/views/blacklist/index.vue"]
FE_TargetDeviceView["目标设备视图<br/>frontend/src/views/ota-target-device/index.vue"]
FE_OtaAPI["OTA API封装<br/>frontend/src/api/ota.js"]
FE_BlackListAPI["黑名单API封装<br/>frontend/src/api/blacklist.js"]
FE_TargetDeviceAPI["目标设备API封装<br/>frontend/src/api/otaTargetDevice.js"]
end
subgraph "后端"
BE_Router["OTA路由<br/>backend/src/routes/ota.js"]
BE_BlackListRouter["黑名单路由<br/>backend/src/routes/blacklist.js"]
BE_TargetDeviceRouter["目标设备路由<br/>backend/src/routes/otaTargetDevice.js"]
BE_Model["OTA模型<br/>backend/src/models/Ota.js"]
BE_BlackListModel["黑名单模型<br/>backend/src/models/BlackList.js"]
BE_TargetDeviceModel["目标设备模型<br/>backend/src/models/OtaTargetDevice.js"]
BE_Validator["OTA校验器<br/>backend/src/validators/ota.js"]
BE_BlackListValidator["黑名单校验器<br/>backend/src/validators/blacklist.js"]
BE_TargetDeviceValidator["目标设备校验器<br/>backend/src/validators/otaTargetDevice.js"]
BE_Storage["OTA存储服务<br/>backend/src/services/otaStorage.js"]
BE_Utils["响应工具<br/>backend/src/utils/response.js"]
BE_DB["数据库配置<br/>backend/src/config/database.js"]
BE_ENV["环境配置<br/>backend/src/config/env.js"]
end
FE_View --> FE_API
FE_API --> BE_Router
FE_OtaView --> FE_OtaAPI
FE_BlackListView --> FE_BlackListAPI
FE_TargetDeviceView --> FE_TargetDeviceAPI
FE_OtaAPI --> BE_Router
FE_BlackListAPI --> BE_BlackListRouter
FE_TargetDeviceAPI --> BE_TargetDeviceRouter
BE_Router --> BE_Model
BE_BlackListRouter --> BE_BlackListModel
BE_TargetDeviceRouter --> BE_TargetDeviceModel
BE_Router --> BE_Validator
BE_BlackListRouter --> BE_BlackListValidator
BE_TargetDeviceRouter --> BE_TargetDeviceValidator
BE_Router --> BE_Storage
BE_Router --> BE_Utils
BE_Model --> BE_DB
BE_BlackListModel --> BE_DB
BE_TargetDeviceModel --> BE_DB
BE_Storage --> BE_ENV
```
**图表来源**
- [backend/src/routes/ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
- [backend/src/routes/blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
- [backend/src/routes/otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)
- [backend/src/models/Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [backend/src/models/BlackList.js:1-37](file://backend/src/models/BlackList.js#L1-L37)
- [backend/src/models/OtaTargetDevice.js:1-38](file://backend/src/models/OtaTargetDevice.js#L1-L38)
- [frontend/src/views/ota/index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
- [frontend/src/views/blacklist/index.vue:1-381](file://frontend/src/views/blacklist/index.vue#L1-L381)
- [frontend/src/views/ota-target-device/index.vue:1-386](file://frontend/src/views/ota-target-device/index.vue#L1-L386)
**章节来源**
- [backend/src/routes/ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
- [backend/src/routes/blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
- [backend/src/routes/otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)
- [frontend/src/views/ota/index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
- [frontend/src/views/blacklist/index.vue:1-381](file://frontend/src/views/blacklist/index.vue#L1-L381)
- [frontend/src/views/ota-target-device/index.vue:1-386](file://frontend/src/views/ota-target-device/index.vue#L1-L386)
## 核心组件
系统的核心组件包括：
@@ -75,16 +130,24 @@ BE_Storage --> BE_ENV
- **OTA路由**：提供RESTful API接口
- **OTA存储服务**：处理不同设备型号的文件存储策略
- **OTA校验器**：使用Zod进行数据验证
- **黑名单模型**：管理设备黑名单
- **目标设备模型**：管理定向升级设备
- **黑名单路由**：管理黑名单相关操作
- **目标设备路由**：管理定向升级相关操作
- **前端管理界面**：提供可视化操作界面
**章节来源**
- [backend/src/models/Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [backend/src/models/BlackList.js:1-37](file://backend/src/models/BlackList.js#L1-L37)
- [backend/src/models/OtaTargetDevice.js:1-38](file://backend/src/models/OtaTargetDevice.js#L1-L38)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/validators/ota.js:1-36](file://backend/src/validators/ota.js#L1-L36)
- [backend/src/validators/blacklist.js:1-14](file://backend/src/validators/blacklist.js#L1-L14)
- [backend/src/validators/otaTargetDevice.js:1-14](file://backend/src/validators/otaTargetDevice.js#L1-L14)
- [frontend/src/views/ota/index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
## 架构总览
系统采用分层架构设计，前后端分离，职责清晰：
系统采用分层架构设计，前后端分离，职责清晰。新增的黑名单和目标设备功能通过独立的路由和模型实现，与现有OTA功能无缝集成。
```mermaid
sequenceDiagram
@@ -106,10 +169,17 @@ Frontend->>Backend : 创建/更新OTA版本
Backend->>DB : 持久化数据
DB-->>Backend : 确认写入
Backend-->>Frontend : 响应操作结果
Frontend->>Backend : 设备端版本检查
Backend->>DB : 查询黑名单和定向设备
DB-->>Backend : 返回过滤条件
Backend->>DB : 查询可用版本
DB-->>Backend : 返回匹配记录
Backend-->>Frontend : 响应最终版本信息
```
**图表来源**
- [backend/src/routes/ota.js:24-66](file://backend/src/routes/ota.js#L24-L66)
- [backend/src/routes/ota.js:68-102](file://backend/src/routes/ota.js#L68-L102)
- [backend/src/services/otaStorage.js:46-103](file://backend/src/services/otaStorage.js#L46-L103)
- [frontend/src/views/ota/index.vue:384-412](file://frontend/src/views/ota/index.vue#L384-L412)
@@ -147,12 +217,27 @@ varchar source
varchar eq_key
datetime create_at
}
BLACKLIST {
int id PK
int ota_id FK
varchar mac
datetime create_at
}
OTATARGETDEVICE {
int id PK
int ota_id FK
varchar mac_addr
datetime create_at
}
OTA ||--|| MODEL : "对应型号"
OTA ||--o{ BLACKLIST : "黑名单关联"
OTA ||--o{ OTATARGETDEVICE : "目标设备关联"
```
**图表来源**
- [backend/src/models/Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
- [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
- [backend/src/models/BlackList.js:5-32](file://backend/src/models/BlackList.js#L5-L32)
- [backend/src/models/OtaTargetDevice.js:5-33](file://backend/src/models/OtaTargetDevice.js#L5-L33)
**字段说明**：
- `verCode`：版本号（整数），用于排序和比较
@@ -165,9 +250,13 @@ OTA ||--|| MODEL : "对应型号"
- `target`：是否定向发布（0-全量，1-定向）
- `beta`：是否灰度发布（0-否，1-是）
- `status`：状态（0-停用，1-可用）
- `mac`：黑名单设备MAC地址
- `mac_addr`：目标设备MAC地址
**章节来源**
- [backend/src/models/Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [backend/src/models/BlackList.js:1-37](file://backend/src/models/BlackList.js#L1-L37)
- [backend/src/models/OtaTargetDevice.js:1-38](file://backend/src/models/OtaTargetDevice.js#L1-L38)
### 文件上传与存储策略
系统针对不同设备型号采用差异化的存储策略：
@@ -214,17 +303,22 @@ Error --> End([结束])
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
### OTA版本检查流程
设备端通过`/api/ota/latest/check`接口获取最新可用版本：
设备端通过`/api/ota/latest/check`接口获取最新可用版本，现已集成黑名单和定向设备过滤逻辑：
```mermaid
sequenceDiagram
participant Device as "设备端"
participant API as "OTA检查接口"
participant DB as "数据库"
Device->>API : GET /api/ota/latest/check?currentVerCode&model&hw
Device->>API : GET /api/ota/latest/check?currentVerCode&model&hw&mac
API->>API : 解析查询参数
API->>DB : 检查黑名单(mac)
DB-->>API : 返回黑名单状态
API->>DB : 查询定向设备(仅当target=1)
DB-->>API : 返回定向设备状态
API->>DB : 查询verCode > currentVerCode且status=1
DB-->>API : 返回匹配记录
API->>API : 过滤黑名单和定向设备
API->>API : 按verCode降序排序
API->>Device : 返回最高版本信息
Note over Device,API : 未找到可用版本时返回空数据
@@ -236,6 +330,8 @@ Note over Device,API : 未找到可用版本时返回空数据
**查询逻辑**：
- 必须满足：`status=1`（可用）、`verCode > 当前版本号`
- 支持按`model`和`hw`（硬件版本）过滤
- **新增**：黑名单过滤（mac存在于黑名单表）
- **新增**：定向设备过滤（当target=1时，mac必须存在于目标设备表）
- 返回最高版本的完整信息
**章节来源**
@@ -276,6 +372,22 @@ class OtaUpdateSchema {
+endTime : string?
+status : number?
}
class BlackListCreateSchema {
+ota_id : number
+mac : string
}
class BlackListUpdateSchema {
+ota_id : number?
+mac : string?
}
class OtaTargetDeviceCreateSchema {
+ota_id : number
+mac_addr : string
}
class OtaTargetDeviceUpdateSchema {
+ota_id : number?
+mac_addr : string?
}
class ApiResponse {
+success(data, msg)
+error(msg, code)
@@ -283,26 +395,31 @@ class ApiResponse {
}
OtaCreateSchema --> ApiResponse : "验证失败时返回错误"
OtaUpdateSchema --> ApiResponse : "验证失败时返回错误"
BlackListCreateSchema --> ApiResponse : "验证失败时返回错误"
OtaTargetDeviceCreateSchema --> ApiResponse : "验证失败时返回错误"
```
**图表来源**
- [backend/src/validators/ota.js:3-35](file://backend/src/validators/ota.js#L3-L35)
- [backend/src/validators/blacklist.js:3-11](file://backend/src/validators/blacklist.js#L3-L11)
- [backend/src/validators/otaTargetDevice.js:3-11](file://backend/src/validators/otaTargetDevice.js#L3-L11)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
**验证规则**：
- 版本号必须为整数
- 版本名称长度1-20字符
- URL最长255字符
- MD5必须为32位十六进制
- 数值字段范围0-1（布尔型）
- 可选字段支持null值
- **OTA版本验证**：版本号必须为整数，版本名称长度1-20字符，URL最长255字符，MD5必须为32位十六进制，数值字段范围0-1（布尔型）
- **黑名单验证**：ota_id必须为整数，MAC地址不能为空且最多100字符
- **目标设备验证**：ota_id必须为整数，MAC地址不能为空且最多17字符
- **可选字段支持**：所有更新操作支持null值
- **唯一性约束**：目标设备MAC地址在同一OTA版本下必须唯一
**章节来源**
- [backend/src/validators/ota.js:1-36](file://backend/src/validators/ota.js#L1-L36)
- [backend/src/validators/blacklist.js:1-14](file://backend/src/validators/blacklist.js#L1-L14)
- [backend/src/validators/otaTargetDevice.js:1-14](file://backend/src/validators/otaTargetDevice.js#L1-L14)
- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
### 前端管理界面
前端提供完整的OTA管理界面，支持多种操作：
前端提供完整的OTA管理界面，支持多种操作，现已集成黑名单和目标设备管理功能：
```mermaid
flowchart TD
@@ -321,10 +438,17 @@ UploadFile --> SaveInfo[自动填充URL和MD5]
SaveBtn[保存按钮] --> ValidateForm[表单验证]
ValidateForm --> SubmitAPI[提交到后端]
SubmitAPI --> RefreshList[刷新列表]
MoreActions[更多操作] --> BlackListAction[黑名单管理]
MoreActions --> TargetDeviceAction[定向升级管理]
BlackListAction --> OpenBlackListDialog[打开黑名单对话框]
TargetDeviceAction --> OpenTargetDeviceDialog[打开目标设备对话框]
OpenBlackListDialog --> LoadBlackList[加载黑名单列表]
OpenTargetDeviceDialog --> LoadTargetDeviceList[加载目标设备列表]
```
**图表来源**
- [frontend/src/views/ota/index.vue:420-579](file://frontend/src/views/ota/index.vue#L420-L579)
- [frontend/src/views/ota/index.vue:645-683](file://frontend/src/views/ota/index.vue#L645-L683)
**主要功能**：
- 版本列表查询（支持按版本名、型号、状态、版本号筛选）
@@ -333,10 +457,195 @@ SubmitAPI --> RefreshList[刷新列表]
- 文件上传（支持Luxsin-X8/X9）
- 强制更新策略配置（强制更新、定向发布、灰度发布）
- 状态管理（可用/停用）
- **新增**：黑名单管理（支持按OTA版本、设备型号、MAC地址筛选）
- **新增**：定向升级管理（支持按OTA版本、设备型号、MAC地址筛选）
**章节来源**
- [frontend/src/views/ota/index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
- [frontend/src/views/blacklist/index.vue:1-381](file://frontend/src/views/blacklist/index.vue#L1-L381)
- [frontend/src/views/ota-target-device/index.vue:1-386](file://frontend/src/views/ota-target-device/index.vue#L1-L386)
- [frontend/src/api/ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)
- [frontend/src/api/blacklist.js:1-57](file://frontend/src/api/blacklist.js#L1-L57)
- [frontend/src/api/otaTargetDevice.js:1-57](file://frontend/src/api/otaTargetDevice.js#L1-L57)
## 黑名单管理功能
### 黑名单模型设计
黑名单功能通过独立的BlackList模型实现，与OTA版本建立一对多关联关系。
```mermaid
erDiagram
BLACKLIST {
int id PK
int ota_id FK
varchar mac
datetime create_at
}
OTA {
int id PK
int verCode
varchar verName
varchar url
char md5
smallint force
varchar desc
varchar model
int hw
smallint target
smallint beta
datetime startTime
datetime endTime
smallint status
datetime create_at
}
BLACKLIST }|--|| OTA : "关联OTA版本"
```
**图表来源**
- [backend/src/models/BlackList.js:5-32](file://backend/src/models/BlackList.js#L5-L32)
- [backend/src/models/Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
**字段说明**：
- `id`：黑名单记录ID
- `ota_id`：关联的OTA版本ID
- `mac`：设备MAC地址，最多100字符
- `create_at`：创建时间，默认当前时间
**章节来源**
- [backend/src/models/BlackList.js:1-37](file://backend/src/models/BlackList.js#L1-L37)
### 黑名单管理流程
黑名单管理提供完整的CRUD操作，支持按OTA版本、设备型号、MAC地址进行筛选查询。
```mermaid
sequenceDiagram
participant Admin as "管理员"
participant Frontend as "黑名单管理界面"
participant API as "黑名单API"
participant DB as "数据库"
Admin->>Frontend : 访问黑名单管理页面
Frontend->>API : 查询黑名单列表
API->>DB : 按条件查询(ota_id/model/mac)
DB-->>API : 返回黑名单记录
API-->>Frontend : 响应JSON数据
Frontend->>API : 新增黑名单
API->>DB : 校验OTA存在性
DB-->>API : 返回OTA信息
API->>DB : 插入黑名单记录
DB-->>API : 返回插入结果
API-->>Frontend : 响应操作结果
Frontend->>API : 编辑/删除黑名单
API->>DB : 更新/删除记录
DB-->>API : 确认操作
API-->>Frontend : 响应操作结果
```
**图表来源**
- [backend/src/routes/blacklist.js:16-71](file://backend/src/routes/blacklist.js#L16-L71)
- [backend/src/routes/blacklist.js:96-131](file://backend/src/routes/blacklist.js#L96-L131)
- [frontend/src/views/blacklist/index.vue:144-346](file://frontend/src/views/blacklist/index.vue#L144-L346)
**功能特性**：
- **查询筛选**：支持按OTA版本、设备型号、MAC地址模糊查询
- **分页加载**：支持skip/limit参数，最大每页1000条记录
- **关联查询**：支持按设备型号筛选时自动转换为OTA ID列表
- **数据验证**：MAC地址格式验证，OTA存在性校验
- **权限控制**：所有接口均需登录认证
**章节来源**
- [backend/src/routes/blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
- [frontend/src/views/blacklist/index.vue:1-381](file://frontend/src/views/blacklist/index.vue#L1-L381)
## 目标设备升级功能
### 目标设备模型设计
目标设备功能通过独立的OtaTargetDevice模型实现，与OTA版本建立一对多关联关系。
```mermaid
erDiagram
OTATARGETDEVICE {
int id PK
int ota_id FK
varchar mac_addr
datetime create_at
}
OTA {
int id PK
int verCode
varchar verName
varchar url
char md5
smallint force
varchar desc
varchar model
int hw
smallint target
smallint beta
datetime startTime
datetime endTime
smallint status
datetime create_at
}
OTATARGETDEVICE }|--|| OTA : "关联OTA版本"
```
**图表来源**
- [backend/src/models/OtaTargetDevice.js:5-33](file://backend/src/models/OtaTargetDevice.js#L5-L33)
- [backend/src/models/Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
**字段说明**：
- `id`：目标设备记录ID
- `ota_id`：关联的OTA版本ID
- `mac_addr`：设备MAC地址，最多17字符
- `create_at`：创建时间，默认当前时间
**章节来源**
- [backend/src/models/OtaTargetDevice.js:1-38](file://backend/src/models/OtaTargetDevice.js#L1-L38)
### 目标设备管理流程
目标设备管理提供完整的CRUD操作，支持按OTA版本、设备型号、MAC地址进行筛选查询，并确保MAC地址在同一OTA版本下的唯一性。
```mermaid
sequenceDiagram
participant Admin as "管理员"
participant Frontend as "目标设备管理界面"
participant API as "目标设备API"
participant DB as "数据库"
Admin->>Frontend : 访问目标设备管理页面
Frontend->>API : 查询目标设备列表
API->>DB : 按条件查询(ota_id/model/mac_addr)
DB-->>API : 返回目标设备记录
API-->>Frontend : 响应JSON数据
Frontend->>API : 新增目标设备
API->>DB : 校验OTA存在性
DB-->>API : 返回OTA信息
API->>DB : 唯一性校验(mac_addr在ota_id下唯一)
DB-->>API : 返回校验结果
API->>DB : 插入目标设备记录
DB-->>API : 返回插入结果
API-->>Frontend : 响应操作结果
Frontend->>API : 编辑/删除目标设备
API->>DB : 更新/删除记录
DB-->>API : 确认操作
API-->>Frontend : 响应操作结果
```
**图表来源**
- [backend/src/routes/otaTargetDevice.js:16-71](file://backend/src/routes/otaTargetDevice.js#L16-L71)
- [backend/src/routes/otaTargetDevice.js:96-139](file://backend/src/routes/otaTargetDevice.js#L96-L139)
- [frontend/src/views/ota-target-device/index.vue:144-351](file://frontend/src/views/ota-target-device/index.vue#L144-L351)
**功能特性**：
- **查询筛选**：支持按OTA版本、设备型号、MAC地址模糊查询
- **分页加载**：支持skip/limit参数，最大每页1000条记录
- **关联查询**：支持按设备型号筛选时自动转换为OTA ID列表
- **唯一性约束**：同一OTA版本下MAC地址必须唯一
- **数据验证**：MAC地址格式验证，OTA存在性校验
- **权限控制**：所有接口均需登录认证
**章节来源**
- [backend/src/routes/otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)
- [frontend/src/views/ota-target-device/index.vue:1-386](file://frontend/src/views/ota-target-device/index.vue#L1-L386)
## 依赖关系分析
@@ -351,28 +660,50 @@ Multer["Multer文件上传"]
end
subgraph "内部模块"
OtaRoute["OTA路由"]
BlackListRoute["黑名单路由"]
TargetDeviceRoute["目标设备路由"]
OtaModel["OTA模型"]
BlackListModel["黑名单模型"]
TargetDeviceModel["目标设备模型"]
OtaValidator["OTA校验器"]
BlackListValidator["黑名单校验器"]
TargetDeviceValidator["目标设备校验器"]
OtaStorage["OTA存储服务"]
ResponseUtil["响应工具"]
EnvConfig["环境配置"]
DBConfig["数据库配置"]
end
Express --> OtaRoute
Express --> BlackListRoute
Express --> TargetDeviceRoute
Sequelize --> OtaModel
Sequelize --> BlackListModel
Sequelize --> TargetDeviceModel
Zod --> OtaValidator
Zod --> BlackListValidator
Zod --> TargetDeviceValidator
S3 --> OtaStorage
Multer --> OtaRoute
OtaRoute --> OtaModel
OtaRoute --> OtaValidator
OtaRoute --> OtaStorage
OtaRoute --> ResponseUtil
BlackListRoute --> BlackListModel
BlackListRoute --> BlackListValidator
BlackListRoute --> ResponseUtil
TargetDeviceRoute --> TargetDeviceModel
TargetDeviceRoute --> TargetDeviceValidator
TargetDeviceRoute --> ResponseUtil
OtaStorage --> EnvConfig
OtaModel --> DBConfig
BlackListModel --> DBConfig
TargetDeviceModel --> DBConfig
```
**图表来源**
- [backend/src/routes/ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
- [backend/src/routes/blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
- [backend/src/routes/otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/package.json:11-24](file://backend/package.json#L11-L24)
@@ -381,18 +712,20 @@ OtaModel --> DBConfig
- **可扩展**：模块化设计便于功能扩展
- **环境适配**：支持开发/生产环境差异化配置
- **安全性**：内置输入验证和错误处理
- **新增**：黑名单和目标设备功能独立部署，不影响核心OTA功能
**章节来源**
- [backend/package.json:1-29](file://backend/package.json#L1-L29)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
## 性能考虑
系统在设计时充分考虑了性能优化：
系统在设计时充分考虑了性能优化，新增功能同样遵循这些原则：
### 数据库优化
- 使用索引字段：`verCode`、`model`、`status`
- 使用索引字段：`verCode`、`model`、`status`、`mac`、`mac_addr`
- 分页查询限制：最大每页1000条记录
- 条件查询优化：支持多字段组合查询
- **新增**：黑名单和目标设备表建立适当的索引以支持频繁的MAC地址查询
### 存储优化
- **S3存储**：利用CDN加速，支持断点续传
@@ -403,6 +736,7 @@ OtaModel --> DBConfig
- **缓存友好**：查询参数明确，便于缓存
- **批量操作**：支持分页批量获取
- **错误快速返回**：验证失败立即返回
- **新增**：黑名单和目标设备查询支持按OTA版本批量筛选
## 故障排除指南
@@ -428,19 +762,38 @@ OtaModel --> DBConfig
- 确认跨域配置正确
- 验证API接口可达性
**5. 黑名单添加失败**
- 检查MAC地址格式是否正确（AA:BB:CC:DD:EE:FF）
- 确认关联的OTA版本是否存在
- 验证黑名单中MAC地址是否重复
**6. 目标设备添加失败**
- 检查MAC地址格式是否正确（AA:BB:CC:DD:EE:FF）
- 确认关联的OTA版本是否存在
- 验证同一OTA版本下MAC地址是否唯一
**7. 设备无法接收OTA更新**
- 检查设备MAC地址是否在黑名单中
- 确认设备是否在目标设备列表中（当target=1时）
- 验证设备硬件版本与OTA版本兼容性
**章节来源**
- [backend/src/routes/ota.js:174-181](file://backend/src/routes/ota.js#L174-L181)
- [backend/src/services/otaStorage.js:95-98](file://backend/src/services/otaStorage.js#L95-L98)
- [backend/src/routes/blacklist.js:108-112](file://backend/src/routes/blacklist.js#L108-L112)
- [backend/src/routes/otaTargetDevice.js:108-112](file://backend/src/routes/otaTargetDevice.js#L108-L112)
## 结论
本OTA固件管理系统具有以下优势：
本OTA固件管理系统经过功能增强后具有以下优势：
- **架构清晰**：前后端分离，职责明确
- **功能完整**：覆盖从版本管理到文件分发的全流程
- **扩展性强**：模块化设计便于功能扩展
- **安全可靠**：完善的输入验证和错误处理机制
- **性能优化**：合理的存储策略和查询优化
- **新增功能完善**：黑名单管理和目标设备升级功能完整集成
- **管理便捷**：提供完整的前端管理界面，支持多种操作
系统特别适合需要管理多型号设备固件更新的企业应用场景，为设备厂商提供了完整的OTA解决方案。
系统特别适合需要管理多型号设备固件更新的企业应用场景，为设备厂商提供了完整的OTA解决方案，现在包括更精细的设备控制能力。
## 附录
@@ -453,6 +806,7 @@ OtaModel --> DBConfig
- `currentVerCode`：当前版本号（必填）
- `model`：设备型号（必填）
- `hw`：硬件版本（可选）
- `mac`：设备MAC地址（可选，用于黑名单过滤）
**版本管理接口**
- 列表查询：GET `/api/ota/`
@@ -466,6 +820,20 @@ OtaModel --> DBConfig
- 支持格式：`.pkg`、`.bin`、`.zip`
- 超时时间：5分钟
**黑名单管理接口**
- 列表查询：GET `/api/blacklist/`
- 获取详情：GET `/api/blacklist/:id`
- 创建黑名单：POST `/api/blacklist/`
- 更新黑名单：PUT `/api/blacklist/:id`
- 删除黑名单：DELETE `/api/blacklist/:id`
**目标设备管理接口**
- 列表查询：GET `/api/ota-target-device/`
- 获取详情：GET `/api/ota-target-device/:id`
- 创建目标设备：POST `/api/ota-target-device/`
- 更新目标设备：PUT `/api/ota-target-device/:id`
- 删除目标设备：DELETE `/api/ota-target-device/:id`
### 环境配置
- 数据库：MySQL（UTF8MB4字符集）
- 存储：S3或本地文件系统
@@ -473,4 +841,14 @@ OtaModel --> DBConfig
- `DATABASE_*`：数据库连接配置
- `AWS_*`：S3存储配置
- `OTA_*`：OTA存储路径和URL配置
- `APP_ENV`：应用环境（development/production）
- `APP_ENV`：应用环境（development/production）
### 数据库表结构
- **ota**：OTA版本主表
- **black_list**：黑名单表
- **ota_target_device**：目标设备表
### 前端路由
- `/ota`：OTA版本管理
- `/blacklist`：黑名单管理
- `/ota-target-device`：目标设备管理