audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
003b44e2bd764c8bada8b211bd8da01a2f31b843
dashboard/.qoder/repowiki/zh/content/数据库设计/OTA固件模型.md
T
eafonyang 08da279275 新增项目文档
2026-06-30 14:46:52 +08:00

13 KiB
Raw Blame History

OTA固件模型

**本文档引用的文件** - [backend/src/models/Ota.js](file://backend/src/models/Ota.js) - [backend/src/routes/ota.js](file://backend/src/routes/ota.js) - [backend/src/services/otaStorage.js](file://backend/src/services/otaStorage.js) - [backend/src/validators/ota.js](file://backend/src/validators/ota.js) - [frontend/src/views/ota/index.vue](file://frontend/src/views/ota/index.vue) - [frontend/src/api/ota.js](file://frontend/src/api/ota.js) - [backend/src/config/env.js](file://backend/src/config/env.js) - [backend/src/utils/response.js](file://backend/src/utils/response.js) - [DEPLOY.md](file://DEPLOY.md)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介

本文档详细介绍了OTA固件模型的设计与实现，包括固件版本管理、存储机制、发布策略以及升级流程。系统支持两种设备型号（Luxsin-X8和Luxsin-X9），提供强制更新和可选更新两种升级类型，并具备灰度发布和定向发布的功能。

项目结构

OTA系统采用前后端分离架构，主要由以下组件构成：

graph TB
subgraph "前端层"
FE[Vue.js 前端界面]
API[API封装层]
end
subgraph "后端层"
ROUTES[路由层]
VALIDATORS[验证器]
MODELS[数据模型]
STORAGE[存储服务]
end
subgraph "基础设施"
DB[(数据库)]
S3[S3存储]
FS[文件系统]
end
FE --> API
API --> ROUTES
ROUTES --> VALIDATORS
ROUTES --> MODELS
MODELS --> DB
ROUTES --> STORAGE
STORAGE --> S3
STORAGE --> FS

图表来源

章节来源

核心组件

数据模型设计

OTA固件模型定义了完整的固件版本管理结构，包含以下关键字段：

字段名 类型 描述 默认值
id INTEGER 主键ID 自增
verCode INTEGER 版本号（整数） 必填
verName STRING(20) 版本名称 必填
url STRING(255) 升级包URL 必填
md5 STRING(32) 升级包MD5校验码 必填
force SMALLINT 是否强制更新 0（否）
desc STRING(255) 描述信息 NULL
model STRING(100) 对应设备型号 NULL
hw INTEGER 硬件版本号 0
target SMALLINT 是否定向发布 0（否）
beta SMALLINT 是否灰度发布 0（否）
startTime DATE 升级开始时间 NULL
endTime DATE 升级结束时间 NULL
status SMALLINT 发布状态 1（可用）
create_at DATE 创建时间 当前时间

章节来源

存储策略

系统针对不同设备型号采用差异化的存储策略：

flowchart TD
Start([上传请求]) --> CheckModel{检查设备型号}
CheckModel --> |Luxsin-X8| UploadS3[上传到S3存储]
CheckModel --> |Luxsin-X9| SaveLocal[保存到本地文件系统]
UploadS3 --> GenKey[生成S3 Key]
GenKey --> PutObject[写入S3对象]
PutObject --> BuildURL[构建公共URL]
SaveLocal --> CreateDir[创建目录结构]
CreateDir --> WriteFile[写入文件]
WriteFile --> BuildLocalURL[构建本地URL]
BuildURL --> Return[返回结果]
BuildLocalURL --> Return

图表来源

章节来源

架构概览

OTA系统采用RESTful API设计，提供完整的CRUD操作和专门的升级包上传功能：

sequenceDiagram
participant Client as 客户端
participant Frontend as 前端界面
participant Backend as 后端服务
participant Storage as 存储服务
participant Database as 数据库
Client->>Frontend : 访问OTA管理界面
Frontend->>Backend : 获取OTA列表
Backend->>Database : 查询OTA记录
Database-->>Backend : 返回OTA数据
Backend-->>Frontend : 返回JSON响应
Frontend->>Backend : 上传升级包
Backend->>Storage : 处理文件上传
Storage->>Storage : 计算MD5哈希
Storage->>Storage : 保存文件
Storage-->>Backend : 返回文件信息
Backend-->>Frontend : 返回上传结果
Frontend->>Backend : 创建OTA记录
Backend->>Database : 插入新记录
Database-->>Backend : 返回新ID
Backend-->>Frontend : 返回创建结果

图表来源

详细组件分析

前端管理界面

前端采用Element Plus组件库构建，提供直观的OTA管理界面：

classDiagram
class OtaManagement {
+searchForm : Object
+pagination : Object
+tableData : Array
+dialogVisible : Boolean
+formData : Object
+loadData() void
+handleSearch() void
+handleAdd() void
+handleEdit(row) void
+handleSubmit() void
+handleDelete(row) void
}
class FormValidation {
+verCode : Number
+verName : String
+model : String
+url : String
+md5 : String
+force : Number
+status : Number
+target : Number
+beta : Number
+hw : Number
}
class PackageUpload {
+packageFileList : Array
+packageUploading : Boolean
+handlePackageChange(file) Promise
+handlePackageRemove() void
}
OtaManagement --> FormValidation : "使用"
OtaManagement --> PackageUpload : "集成"

图表来源

前端界面特性：

  • 支持按版本名称、设备型号、状态进行筛选
  • 提供分页功能，支持10-100条记录每页
  • 内置表单验证，确保数据完整性
  • 支持升级包自动上传和MD5校验
  • 提供复制现有版本的功能

章节来源

后端API服务

后端提供完整的OTA管理API：

核心API接口

接口 方法 功能 权限要求
/api/ota/upload-package POST 上传升级包 登录用户
/api/ota/latest/check GET 检查最新版本 无需登录
/api/ota/ GET 获取OTA列表 登录用户
/api/ota/:ota_id GET 获取指定OTA 登录用户
/api/ota/ POST 创建OTA记录 登录用户
/api/ota/:ota_id PUT 更新OTA记录 登录用户
/api/ota/:ota_id DELETE 删除OTA记录 登录用户

版本检查逻辑

设备端通过/api/ota/latest/check接口获取最新可用版本：

flowchart TD
Request[设备请求] --> ParseParams[解析参数]
ParseParams --> CheckStatus{检查状态}
CheckStatus --> |不可用| NoData[返回空数据]
CheckStatus --> |可用| QueryDB[查询数据库]
QueryDB --> FilterByVersion{过滤更高版本}
FilterByVersion --> FilterByModel{按设备型号过滤}
FilterByModel --> FilterByHW{按硬件版本过滤}
FilterByHW --> OrderByVersion[按版本号降序排列]
OrderByVersion --> ReturnResult[返回最新版本]
NoData --> End([结束])
ReturnResult --> End

图表来源

章节来源

存储服务实现

存储服务根据设备型号采用不同的存储策略：

Luxsin-X8存储策略

  • 使用Amazon S3作为存储后端
  • 文件命名为LUXSIN_X8.PKG
  • 生成S3 Key格式：ota/{YYYYMM}/x8/{md5前5位}/LUXSIN_X8.PKG
  • 支持IAM角色认证和显式凭证两种模式

Luxsin-X9存储策略

  • 使用本地文件系统存储
  • 文件命名为LUXSIN.PKG
  • 目录结构：{OTA_UPLOAD_DIR}/ota/{YYYYMM}/x9/{md5前5位}/LUXSIN.PKG
  • 支持开发和生产环境的不同存储路径

章节来源

数据验证机制

系统采用Zod库实现严格的数据验证：

flowchart TD
Input[用户输入] --> Schema[验证模式]
Schema --> Validate{验证通过?}
Validate --> |是| Process[处理数据]
Validate --> |否| Error[返回错误信息]
Process --> CreateRecord[创建数据库记录]
CreateRecord --> Success[返回成功响应]
Error --> End([结束])
Success --> End

图表来源

章节来源

依赖关系分析

graph LR
subgraph "外部依赖"
ZOD[Zod验证库]
SEQUELIZE[Sequelize ORM]
MULTER[Multer文件上传]
S3_SDK[AWS S3 SDK]
end
subgraph "内部模块"
OtaModel[Ota模型]
OtaRoutes[OTA路由]
OtaStorage[存储服务]
OtaValidator[验证器]
ApiResponse[响应封装]
end
ZOD --> OtaValidator
SEQUELIZE --> OtaModel
MULTER --> OtaRoutes
S3_SDK --> OtaStorage
OtaRoutes --> OtaModel
OtaRoutes --> OtaStorage
OtaRoutes --> OtaValidator
OtaRoutes --> ApiResponse

图表来源

章节来源

性能考虑

存储优化

  • S3存储：利用CDN加速全球访问，支持断点续传
  • 本地存储：使用递归目录结构，避免单目录文件过多
  • MD5校验：上传即计算，确保文件完整性

数据库优化

  • 索引策略：对verCode、model、status建立复合索引
  • 查询优化：使用LIMIT限制返回数量，避免全表扫描
  • 缓存策略：结合Redis实现热点数据缓存

前端性能

  • 懒加载：表格数据按需加载
  • 分页机制：支持大数据量场景下的分页显示
  • 防抖处理：搜索框输入防抖，减少请求频率

故障排除指南

常见问题及解决方案

1. S3上传失败

症状：升级包上传到Luxsin-X8失败 原因：

  • AWS凭证配置错误
  • S3权限不足
  • 网络连接问题

解决方案：

  • 检查AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY配置
  • 验证S3桶权限设置
  • 确认网络连通性

2. 本地存储权限问题

症状：升级包无法保存到Luxsin-X9 原因：

  • 目录权限不足
  • 磁盘空间不足
  • 路径不存在

解决方案：

  • 确保/data/projects/source目录可写
  • 检查磁盘空间
  • 创建必要的目录结构

3. 版本冲突

症状：创建OTA记录时报版本已存在 原因：

  • 相同设备型号的版本号重复
  • 数据库约束冲突

解决方案：

  • 修改版本号确保唯一性
  • 检查现有版本记录

4. 前端上传异常

症状：升级包上传界面无响应 原因：

  • 文件大小超限
  • 网络超时
  • 前端验证失败

解决方案：

  • 检查文件大小限制（50MB）
  • 确认网络连接稳定
  • 重新选择符合要求的文件

章节来源

结论

OTA固件模型提供了完整的固件版本管理解决方案，具有以下特点：

技术优势

  • 双存储策略：针对不同设备型号采用最优存储方案
  • 严格验证：前后端双重数据验证确保数据完整性
  • 灵活发布：支持强制更新、可选更新、灰度发布等多种发布策略
  • 安全可靠：MD5校验、权限控制、错误处理机制完善

扩展性

  • 模块化设计：各组件职责清晰，易于维护和扩展
  • 环境适配：支持开发、测试、生产多环境部署
  • API标准化：RESTful接口设计便于第三方集成

最佳实践建议

  1. 版本管理：建立严格的版本号命名规范
  2. 测试流程：在灰度环境中充分测试后再全量发布
  3. 监控告警：建立OTA升级监控和异常告警机制
  4. 回滚策略：制定完善的版本回滚预案

该系统为固件版本管理提供了可靠的基础设施，能够满足现代IoT设备的OTA升级需求。

Reference in New Issue View Git Blame Copy Permalink