更新wiki

2026-07-01 11:26:23 +08:00
parent 864040f45b
commit cacee5f294
15 changed files with 579 additions and 104 deletions
@@ -7,6 +7,12 @@
 - [otaStorage.js](file://backend/src/services/otaStorage.js)
 - [index.vue](file://frontend/src/views/ota/index.vue)
 - [ota.js](file://frontend/src/api/ota.js)
+- [blacklist.js](file://frontend/src/api/blacklist.js)
+- [otaTargetDevice.js](file://frontend/src/api/otaTargetDevice.js)
+- [BlackList.js](file://backend/src/models/BlackList.js)
+- [OtaTargetDevice.js](file://backend/src/models/OtaTargetDevice.js)
+- [blacklist.js](file://backend/src/routes/blacklist.js)
+- [otaTargetDevice.js](file://backend/src/routes/otaTargetDevice.js)
 - [response.js](file://backend/src/utils/response.js)
 - [env.js](file://backend/src/config/env.js)
 - [request.js](file://frontend/src/utils/request.js)
@@ -14,6 +20,14 @@
 - [DEPLOY.md](file://DEPLOY.md)
 </cite>

+## 更新摘要
+**变更内容**
+- 集成黑名单管理功能，支持按MAC地址阻止设备接收OTA更新
+- 集成定向升级功能，支持指定设备进行定向升级
+- 在OTA管理页面中新增黑名单和定向升级的操作入口
+- 新增黑名单和定向升级的独立管理页面
+- 完善OTA版本管理的完整生命周期管理体验
+
 ## 目录
 1. [简介](#简介)
 2. [项目结构](#项目结构)
@@ -26,10 +40,10 @@
 9. [结论](#结论)

 ## 简介
-本文件面向OTA固件管理页面的使用者与维护者，系统性阐述固件版本管理功能，涵盖固件上传、版本控制、强制更新配置、发布状态管理、兼容性检查、更新策略配置、用户通知机制、下载统计、版本历史与回滚功能，以及进度监控、错误处理与用户体验优化方案。文档以仓库现有代码为依据，结合前后端交互流程，提供可操作的实践指导。
+本文件面向OTA固件管理页面的使用者与维护者，系统性阐述固件版本管理功能，涵盖固件上传、版本控制、强制更新配置、发布状态管理、兼容性检查、更新策略配置、用户通知机制、下载统计、版本历史与回滚功能，以及进度监控、错误处理与用户体验优化方案。**本次更新集成了黑名单管理和定向升级功能，提供更完整的OTA管理体验**。

 ## 项目结构
-系统采用前后端分离架构，前端使用Vue 3 + Element Plus，后端使用Node.js + Express + Sequelize，数据库为MySQL。OTA模块位于独立的路由与模型中，存储策略针对不同设备型号采用差异化方案（X8上传至S3，X9本地存储）。
+系统采用前后端分离架构，前端使用Vue 3 + Element Plus，后端使用Node.js + Express + Sequelize，数据库为MySQL。OTA模块位于独立的路由与模型中，存储策略针对不同设备型号采用差异化方案（X8上传至S3，X9本地存储）。**新增了黑名单和定向升级的独立管理模块**。

 ```mermaid
 graph TB
@@ -40,45 +54,38 @@ ROUTER --> BE["后端服务<br/>routes/ota.js"]
 BE --> MODEL["数据模型<br/>models/Ota.js"]
 BE --> STORAGE["存储服务<br/>services/otaStorage.js"]
 STORAGE --> ENV["环境配置<br/>config/env.js"]
+FE --> BLACKLIST_API["黑名单API<br/>api/blacklist.js"]
+BLACKLIST_API --> BLACKLIST_BE["黑名单路由<br/>routes/blacklist.js"]
+BLACKLIST_BE --> BLACKLIST_MODEL["黑名单模型<br/>models/BlackList.js"]
+FE --> TARGET_API["定向升级API<br/>api/otaTargetDevice.js"]
+TARGET_API --> TARGET_BE["定向升级路由<br/>routes/otaTargetDevice.js"]
+TARGET_BE --> TARGET_MODEL["定向升级模型<br/>models/OtaTargetDevice.js"]
 ```

-图表来源
- [index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
+**图表来源**
+- [index.vue:1-1003](file://frontend/src/views/ota/index.vue#L1-L1003)
 - [ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)
- [request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
- [router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [env.js:1-13](file://backend/src/config/env.js#L1-L13)
-
-章节来源
- [index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
- [ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)
- [request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
- [router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [env.js:1-13](file://backend/src/config/env.js#L1-L13)
+- [blacklist.js:1-57](file://frontend/src/api/blacklist.js#L1-L57)
+- [otaTargetDevice.js:1-57](file://frontend/src/api/otaTargetDevice.js#L1-L57)
+- [blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
+- [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)

 ## 核心组件
- 前端视图组件：负责搜索、分页、表单校验、上传与CRUD操作，提供友好的用户交互体验。
+- 前端视图组件：负责搜索、分页、表单校验、上传与CRUD操作，提供友好的用户交互体验。**新增了黑名单和定向升级的弹窗管理功能**。
 - API封装：统一封装GET/POST/PUT/DELETE请求，处理超时与认证头注入。
- 后端路由：提供OTA版本列表、详情、创建、更新、删除与升级包上传接口。
- 数据模型：定义OTA版本的数据结构与约束，确保版本号唯一性与字段完整性。
+- 后端路由：提供OTA版本列表、详情、创建、更新、删除与升级包上传接口。**新增黑名单和定向升级的CRUD接口**。
+- 数据模型：定义OTA版本的数据结构与约束，确保版本号唯一性与字段完整性。**新增黑名单和定向升级的数据模型**。
 - 存储服务：根据设备型号选择不同的存储策略（S3/X9本地），并生成公开访问链接。
 - 响应封装：统一返回格式，便于前端处理与展示。
 - 环境配置：区分开发/生产环境，影响存储目录与S3凭据策略。

-章节来源
- [index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
+**章节来源**
+- [index.vue:1-1003](file://frontend/src/views/ota/index.vue#L1-L1003)
 - [ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)
- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [response.js:1-25](file://backend/src/utils/response.js#L1-L25)
- [env.js:1-13](file://backend/src/config/env.js#L1-L13)
+- [blacklist.js:1-57](file://frontend/src/api/blacklist.js#L1-L57)
+- [otaTargetDevice.js:1-57](file://frontend/src/api/otaTargetDevice.js#L1-L57)
+- [blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
+- [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)

 ## 架构总览
 OTA固件管理页面的端到端流程如下：
@@ -87,6 +94,7 @@ OTA固件管理页面的端到端流程如下：
 - 后端路由接收请求，进行鉴权与参数校验；
 - 数据模型层保证数据一致性；
 - 存储服务根据设备型号执行差异化存储；
+- **黑名单和定向升级功能通过独立的路由和模型处理**；
 - 统一响应格式返回给前端，前端渲染结果。

 ```mermaid
@@ -108,15 +116,21 @@ ST-->>RT : 返回存储结果URL/MD5/S3Key
 RT-->>AX : 统一响应格式
 AX-->>API : 返回数据
 API-->>FE : 渲染结果
+Note over FE,RT : 新增黑名单和定向升级流程
+FE->>API : 调用黑名单/定向升级接口
+API->>AX : 发起HTTP请求
+AX->>RT : 路由处理鉴权/参数校验
+RT->>MD : 查询/写入黑名单/定向升级数据
+RT-->>AX : 统一响应格式
+AX-->>API : 返回数据
+API-->>FE : 渲染结果
 ```

-图表来源
- [index.vue:420-579](file://frontend/src/views/ota/index.vue#L420-L579)
+**图表来源**
+- [index.vue:420-831](file://frontend/src/views/ota/index.vue#L420-L831)
 - [ota.js:13-67](file://frontend/src/api/ota.js#L13-L67)
- [request.js:11-69](file://frontend/src/utils/request.js#L11-L69)
- [ota.js:24-268](file://backend/src/routes/ota.js#L24-L268)
- [Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
- [otaStorage.js:46-103](file://backend/src/services/otaStorage.js#L46-L103)
+- [blacklist.js:12-56](file://frontend/src/api/blacklist.js#L12-L56)
+- [otaTargetDevice.js:12-55](file://frontend/src/api/otaTargetDevice.js#L12-L55)

 ## 详细组件分析

@@ -127,6 +141,7 @@ API-->>FE : 渲染结果
 - 上传流程：仅当设备型号为X8/X9时显示上传按钮，自动计算MD5并生成公开下载地址。
 - CRUD操作：支持新增、编辑、复制（基于现有行）、删除，均通过API封装调用后端接口。
 - 分页与加载：支持每页数量切换与页码切换，加载状态通过Element Plus的loading指示。
+- **新增功能**：在更多操作菜单中集成了黑名单管理和定向升级功能，支持对单个OTA版本进行设备级别的管控。

 ```mermaid
 flowchart TD
@@ -140,21 +155,27 @@ Action --> |新增| OpenAdd["打开新增对话框"]
 Action --> |编辑| OpenEdit["打开编辑对话框"]
 Action --> |复制| CopyRow["复制行数据到表单"]
 Action --> |删除| ConfirmDel["确认删除"]
+Action --> |黑名单| OpenBlack["打开黑名单弹窗"]
+Action --> |定向升级| OpenTarget["打开定向升级弹窗"]
 OpenAdd --> Submit["提交表单"]
 OpenEdit --> Submit
 CopyRow --> Submit
 ConfirmDel --> Delete["调用删除接口"]
+OpenBlack --> ManageBlack["管理黑名单"]
+OpenTarget --> ManageTarget["管理定向升级"]
 Submit --> Reload["刷新列表"]
 Delete --> Reload
+ManageBlack --> Reload
+ManageTarget --> Reload
 Reload --> Render
 ```

-图表来源
- [index.vue:420-579](file://frontend/src/views/ota/index.vue#L420-L579)
+**图表来源**
+- [index.vue:420-831](file://frontend/src/views/ota/index.vue#L420-L831)
 - [ota.js:13-49](file://frontend/src/api/ota.js#L13-L49)

-章节来源
- [index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
+**章节来源**
+- [index.vue:1-1003](file://frontend/src/views/ota/index.vue#L1-L1003)
 - [ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)

 ### 后端路由与控制器
@@ -166,6 +187,8 @@ Reload --> Render
  - 创建：POST /api/ota/（需登录），校验版本号唯一性与字段合法性。
  - 更新：PUT /api/ota/:ota_id（需登录），支持部分字段更新与版本号冲突检测。
  - 删除：DELETE /api/ota/:ota_id（需登录）。
+  - **新增黑名单接口**：GET/POST/PUT/DELETE /api/blacklist/（需登录），支持黑名单的CRUD操作。
+  - **新增定向升级接口**：GET/POST/PUT/DELETE /api/ota-target-device/（需登录），支持定向升级设备的CRUD操作。
 - 参数校验：使用Zod Schema进行严格的字段类型与长度校验。
 - 错误处理：统一使用ApiResponse封装，区分成功、错误与无数据三类返回码。

@@ -173,8 +196,12 @@ Reload --> Render
 sequenceDiagram
 participant FE as "前端"
 participant RT as "后端路由<br/>routes/ota.js"
+participant BL_RT as "黑名单路由<br/>routes/blacklist.js"
+participant TD_RT as "定向升级路由<br/>routes/otaTargetDevice.js"
 participant VL as "校验器<br/>validators/ota.js"
 participant MD as "模型<br/>models/Ota.js"
+participant BL_MD as "黑名单模型<br/>models/BlackList.js"
+participant TD_MD as "定向升级模型<br/>models/OtaTargetDevice.js"
 participant ST as "存储服务<br/>services/otaStorage.js"
 FE->>RT : POST /api/ota/upload-package
 RT->>VL : 校验请求体
@@ -186,25 +213,31 @@ RT->>ST : 上传S3并生成URL
 end
 ST-->>RT : 返回存储结果
 RT-->>FE : ApiResponse.success()
-FE->>RT : POST /api/ota/
-RT->>VL : 校验创建Schema
-RT->>MD : 检查版本号唯一性
-RT->>MD : 写入数据库
-MD-->>RT : 返回新记录
-RT-->>FE : ApiResponse.success()
+Note over FE,BL_RT : 黑名单操作
+FE->>BL_RT : POST /api/blacklist/
+BL_RT->>VL : 校验黑名单Schema
+BL_RT->>BL_MD : 检查OTA存在性
+BL_RT->>BL_MD : 写入黑名单数据库
+BL_MD-->>BL_RT : 返回新记录
+BL_RT-->>FE : ApiResponse.success()
+Note over FE,TD_RT : 定向升级操作
+FE->>TD_RT : POST /api/ota-target-device/
+TD_RT->>VL : 校验定向升级Schema
+TD_RT->>TD_MD : 检查OTA存在性和唯一性
+TD_RT->>TD_MD : 写入定向升级数据库
+TD_MD-->>TD_RT : 返回新记录
+TD_RT-->>FE : ApiResponse.success()
 ```

-图表来源
+**图表来源**
 - [ota.js:24-268](file://backend/src/routes/ota.js#L24-L268)
- [ota.js:3-33](file://backend/src/validators/ota.js#L3-L33)
- [Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
- [otaStorage.js:46-103](file://backend/src/services/otaStorage.js#L46-L103)
+- [blacklist.js:96-139](file://backend/src/routes/blacklist.js#L96-L139)
+- [otaTargetDevice.js:96-139](file://backend/src/routes/otaTargetDevice.js#L96-L139)

-章节来源
+**章节来源**
 - [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
- [ota.js:1-36](file://backend/src/validators/ota.js#L1-L36)
- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+- [blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
+- [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)

 ### 数据模型与约束
 - 关键字段：
@@ -219,6 +252,8 @@ RT-->>FE : ApiResponse.success()
  - startTime/endTime：发布时间窗口。
 - 唯一性约束：verCode+model组合唯一，防止重复版本。
 - 默认值：force、target、beta、status等字段提供合理默认值。
+- **新增黑名单模型**：包含ota_id（关联OTA版本）、mac（MAC地址）字段，支持按OTA版本和MAC地址进行设备级管控。
+- **新增定向升级模型**：包含ota_id（关联OTA版本）、mac_addr（MAC地址）字段，支持指定设备进行定向升级。

 ```mermaid
 erDiagram
@@ -239,13 +274,31 @@ datetime endTime
 smallint status
 datetime create_at
 }
+BLACK_LIST {
+int id PK
+int ota_id FK
+string mac
+datetime create_at
+}
+OTA_TARGET_DEVICE {
+int id PK
+int ota_id FK
+string mac_addr
+datetime create_at
+}
+OTA ||--o{ BLACK_LIST : "包含"
+OTA ||--o{ OTA_TARGET_DEVICE : "包含"
 ```

-图表来源
+**图表来源**
 - [Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
+- [BlackList.js:5-36](file://backend/src/models/BlackList.js#L5-L36)
+- [OtaTargetDevice.js:5-37](file://backend/src/models/OtaTargetDevice.js#L5-L37)

-章节来源
+**章节来源**
 - [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [BlackList.js:1-36](file://backend/src/models/BlackList.js#L1-L36)
+- [OtaTargetDevice.js:1-37](file://backend/src/models/OtaTargetDevice.js#L1-L37)

 ### 存储策略与安全
 - 设备型号差异化：
@@ -270,11 +323,11 @@ BuildX8 --> Return["返回MD5/URL/S3Key"]
 BuildX9 --> Return
 ```

-图表来源
+**图表来源**
 - [otaStorage.js:46-103](file://backend/src/services/otaStorage.js#L46-L103)
 - [env.js:1-13](file://backend/src/config/env.js#L1-L13)

-章节来源
+**章节来源**
 - [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
 - [env.js:1-13](file://backend/src/config/env.js#L1-L13)

@@ -289,8 +342,11 @@ BuildX9 --> Return
  - 灰度发布：beta=1时，按比例或规则逐步放量。
 - 时间窗口：
  - startTime/endTime限定发布时间范围，超出范围的版本不应被推送。
+- **黑名单与定向升级集成**：
+  - 设备端在检查更新时，需要先检查设备是否在黑名单中，如果在黑名单中则不应接收更新。
+  - 设备端在检查更新时，需要检查设备是否在定向升级列表中，只有定向设备才能接收更新。

-章节来源
+**章节来源**
 - [ota.js:68-102](file://backend/src/routes/ota.js#L68-L102)

 ### 用户体验与错误处理
@@ -300,16 +356,48 @@ BuildX9 --> Return
  - 上传反馈：上传成功后自动填充MD5与URL，失败时给出具体错误信息。
  - 删除确认：二次确认对话框，防止误删。
  - 分页与重置：支持页码与每页数量调整，重置搜索条件。
+  - **新增弹窗管理**：黑名单和定向升级分别通过独立弹窗进行管理，支持MAC地址的批量添加和删除。
+  - **MAC地址格式校验**：支持AA:BB:CC:DD:EE:FF格式的MAC地址输入和验证。
 - 后端：
  - 统一响应格式：code=1成功、code=0错误、code=2无数据。
-  - 错误分类：参数错误、业务冲突（版本已存在）、存储异常（S3上传失败）等。
+  - 错误分类：参数错误、业务冲突（版本已存在）、存储异常（S3上传失败）、权限错误等。
  - 日志记录：关键操作与异常均有日志输出，便于排查。

-章节来源
+**章节来源**
 - [index.vue:305-338](file://frontend/src/views/ota/index.vue#L305-L338)
 - [response.js:1-25](file://backend/src/utils/response.js#L1-L25)
 - [ota.js:25-66](file://backend/src/routes/ota.js#L25-L66)

+### 黑名单管理功能
+- 功能概述：支持将特定设备的MAC地址加入黑名单，阻止这些设备接收OTA更新。
+- 界面集成：在OTA版本的"更多操作"菜单中新增"黑名单"选项，点击后弹出黑名单管理弹窗。
+- 操作流程：
+  - 打开黑名单弹窗后，输入设备MAC地址并点击"添加"按钮。
+  - 支持批量MAC地址添加，每个MAC地址一行。
+  - 可以查看当前OTA版本的所有黑名单设备列表。
+  - 支持删除不需要的黑名单设备。
+- 数据验证：MAC地址格式必须符合AA:BB:CC:DD:EE:FF格式，且每个MAC地址都必须唯一。
+
+**章节来源**
+- [index.vue:645-734](file://frontend/src/views/ota/index.vue#L645-L734)
+- [blacklist.js:12-56](file://frontend/src/api/blacklist.js#L12-L56)
+- [blacklist.js:96-204](file://backend/src/routes/blacklist.js#L96-L204)
+
+### 定向升级功能
+- 功能概述：支持指定特定设备的MAC地址进行定向升级，只有这些设备能够接收到OTA更新。
+- 界面集成：在OTA版本的"更多操作"菜单中新增"定向升级"选项，点击后弹出定向升级管理弹窗。
+- 操作流程：
+  - 打开定向升级弹窗后，输入目标设备的MAC地址并点击"添加"按钮。
+  - 支持批量MAC地址添加，每个MAC地址一行。
+  - 可以查看当前OTA版本的所有定向升级设备列表。
+  - 支持删除不需要的定向升级设备。
+- 数据验证：MAC地址格式必须符合AA:BB:CC:DD:EE:FF格式，且每个MAC地址在同一个OTA版本内必须唯一。
+
+**章节来源**
+- [index.vue:736-817](file://frontend/src/views/ota/index.vue#L736-L817)
+- [otaTargetDevice.js:12-55](file://frontend/src/api/otaTargetDevice.js#L12-L55)
+- [otaTargetDevice.js:96-208](file://backend/src/routes/otaTargetDevice.js#L96-L208)
+
 ## 依赖关系分析
 - 前端依赖：
  - Element Plus：UI组件库，提供表格、表单、对话框、分页等。
@@ -336,21 +424,21 @@ BE --> ML["Multer"]
 BE --> AW["AWS SDK"]
 ```

-图表来源
+**图表来源**
 - [request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
 - [router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
 - [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
 - [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [ota.js:1-36](file://backend/src/validators/ota.js#L1-L36)
- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+- [blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
+- [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)

-章节来源
+**章节来源**
 - [request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
 - [router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
 - [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
 - [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
- [ota.js:1-36](file://backend/src/validators/ota.js#L1-L36)
- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+- [blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
+- [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)

 ## 性能考虑
 - 文件上传：
@@ -364,6 +452,9 @@ BE --> AW["AWS SDK"]
  - 目录按年月与MD5前缀组织，有利于快速定位与清理。
 - 响应格式：
  - 统一的响应结构便于前端缓存与错误处理，减少重复解析成本。
+- **黑名单和定向升级查询优化**：
+  - 黑名单和定向升级列表查询支持按OTA版本过滤，减少不必要的数据传输。
+  - 支持MAC地址模糊查询，提升用户体验。

 ## 故障排除指南
 - 上传失败：
@@ -371,18 +462,24 @@ BE --> AW["AWS SDK"]
  - 确认S3配置（区域、桶名、凭据）或本地存储目录权限。
  - 查看后端日志中的错误信息（如S3上传失败）。
 - 版本冲突：
-  - 创建/更新时提示“该版本已存在”，请修改版本号或设备型号组合。
+  - 创建/更新时提示"该版本已存在"，请修改版本号或设备型号组合。
 - 权限问题：
  - 未登录或Token过期时会被重定向到登录页；超级管理员权限不足时会被拒绝访问。
 - 网络异常：
  - 前端请求拦截器会捕获401/403错误并提示，同时清除本地认证信息。
 - 页面空白或API失败：
  - 检查Nginx代理是否指向后端服务，确认容器健康状态与日志输出。
+- **黑名单和定向升级问题**：
+  - MAC地址格式错误：确保输入AA:BB:CC:DD:EE:FF格式。
+  - OTA版本不存在：确认选择的OTA版本ID有效。
+  - 重复的MAC地址：黑名单和定向升级中的MAC地址在同一OTA版本内必须唯一。

-章节来源
+**章节来源**
 - [ota.js:25-66](file://backend/src/routes/ota.js#L25-L66)
 - [request.js:44-69](file://frontend/src/utils/request.js#L44-L69)
+- [blacklist.js:159-183](file://backend/src/routes/blacklist.js#L159-L183)
+- [otaTargetDevice.js:142-208](file://backend/src/routes/otaTargetDevice.js#L142-L208)
 - [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)

 ## 结论
-OTA固件管理页面通过清晰的前后端职责划分与统一的响应格式，实现了从版本上传、存储、查询到发布的完整闭环。X8/X9差异化存储策略兼顾了可扩展性与易用性，配合严格的参数校验与完善的错误处理，为设备端的兼容性检查与更新策略提供了可靠支撑。建议在后续迭代中进一步完善下载统计、版本历史与回滚功能，并持续优化上传体验与性能表现。
+OTA固件管理页面通过清晰的前后端职责划分与统一的响应格式，实现了从版本上传、存储、查询到发布的完整闭环。**本次更新集成了黑名单管理和定向升级功能，显著提升了OTA管理的精细化程度和安全性**。X8/X9差异化存储策略兼顾了可扩展性与易用性，配合严格的参数校验与完善的错误处理，为设备端的兼容性检查与更新策略提供了可靠支撑。**新增的黑名单和定向升级功能使得OTA管理更加灵活，能够满足不同场景下的设备管控需求**。建议在后续迭代中进一步完善下载统计、版本历史与回滚功能，并持续优化上传体验与性能表现。