---
title: 设备 OTA 升级机制
summary: 介绍涂鸦面板设备 OTA 固件升级机制，包括触发源、升级类型及管理员与分享设备等场景说明。
questions:
  - OTA 升级检测在哪些触发源下会启动（初始化、推送、设备重新上线）？
  - 提醒升级、强制升级和检测升级三种类型有什么区别？
  - 强制升级时用户点击取消后面板小程序会怎样？
  - OTA 升级检查的防抖机制是如何工作的？
  - 分享设备或普通家庭成员为什么不会触发 OTA 逻辑？
  - 固件状态为"正在升级"时框架会做什么处理？
  - OTA 升级的生命周期标记如何防止在同一次运行中反复提醒？
  - 管理员进入面板发现新固件时的升级交互流程是怎样的？
  - 面板运行中收到升级通知推送后框架如何引导用户？
  - OTA 升级机制为什么不向开发者开放自定义实现的接口？
---

# 设备 OTA 升级机制

## 1. 概述
OTA（Over-the-Air）升级检测机制用于在用户进入面板小程序或在面板运行过程中，实时检测设备固件更新情况，并根据固件优先级（强制/提醒）引导用户进行升级，确保设备运行在最佳版本。

> **提示**：该能力已高度集成至 [面板环境初始化](./) 文档中。在面板小程序初始化时调用该接口，即可自动触发下述 OTA 升级流程，无需开发者自行实现。

---

## 2. 逻辑流程图

```mermaid
graph TD
    Start([触发升级检查]) --> Trigger{触发源}
    Trigger -- "初始化/进入面板" --> AdminCheck
    Trigger -- "收到升级通知推送" --> AdminCheck
    Trigger -- "设备重新上线" --> AdminCheck

    AdminCheck{是否管理员?} -- 否 --> End([结束])
    AdminCheck -- 是 --> DevFilter{支持 OTA 且非分享的设备}

    DevFilter -- 否 --> End
    DevFilter -- 是 --> API[请求云端升级信息接口]

    API --> DataCheck{存在有效更新?}
    DataCheck -- 否 --> End
    DataCheck -- 是 --> Priority[锁定目标项: 强制升级 > 正在升级 > 普通更新]

    Priority --> StatusNode{固件状态}

    %% 状态: 排队中
    StatusNode -- "排队中" --> S13_Force{是否强制升级?}
    S13_Force -- 否 --> End
    S13_Force -- 是 --> Action_Check

    %% 状态: 正在升级
    StatusNode -- "正在升级" --> S25_Check{强制升级 或 升级期间不可控?}
    S25_Check -- 否 --> End
    S25_Check -- 是 --> Action_Check

    %% 状态: 有新版本
    StatusNode -- "有新版本" --> S1_Online{设备在线 且 非检测类型升级?}
    S1_Online -- 否 --> End
    S1_Online -- 是 --> Dialog_Confirm[弹出升级确认弹窗]

    Dialog_Confirm -- 点击确定 --> Action_Check
    Dialog_Confirm -- 点击取消 --> S1_Cancel{是否强制升级?}
    S1_Cancel -- 是 --> Exit[退出小程序]
    S1_Cancel -- 否 --> End

    %% 执行动作
    Action_Check{本次生命周期是否已检查过?}
    Action_Check -- 是 --> End
    Action_Check -- 否 --> OpenOTA[标记已检查 <br/> 跳转至 OTA 升级原生页]
```

---

## 3. 升级类型

*   **提醒升级**：用户进入设备面板主动提醒 App 用户，用户可以选择是否升级。
*   **强制升级**：升级提醒主动推送给 App 用户，用户无选择权利，必须升级。
*   **检测升级**：升级提醒不会主动推送给 App 用户，需要用户主动发起版本检测，才能看到升级提醒。

---

## 4. 场景说明

### 场景 A：管理员进入面板发现新固件
*   **表现**：用户进入面板后，屏幕弹出升级提示框，显示更新日志。
*   **逻辑**：
    1. 接口返回固件状态为“有新版本”。
    2. 检查设备当前处于“在线”状态。
    3. 弹出升级交互弹窗。
    4. 用户点击“立即升级”后跳转，点击“取消”则关闭弹窗（非强制情况下）。

<Image src="/images/panel/panel-ota-tip.jpg" style={{ width: '256px' }} />

### 场景 B：固件强制升级
*   **表现**：用户进入面板，不会出现提醒弹窗，设备面板会自动直接跳转到设备升级页面。
*   **逻辑**：
    1. 识别到该固件属于“强制升级”类型。
    2. 直接跳转至 OTA 升级原生页。

<Image src="/images/panel/panel-ota-detail.jpg" style={{ width: '256px' }} />

### 场景 C：面板运行中设备开始升级（推送触发）
*   **表现**：用户正在操作设备时，突然收到“设备正在升级”的提示。
*   **逻辑**：
    1. 框架接收到云端下发的升级通知推送。
    2. 触发升级检查流程。
    3. 若判断固件正在升级且不可控，将弹出升级通知弹窗，引导用户查看进度，防止在升级期间进行冲突操作。

<Image src="/images/panel/panel-ota-tip.jpg" style={{ width: '256px' }} />

### 场景 D：分享设备或普通家庭成员
*   **表现**：完全不触发任何 OTA 相关的弹窗或逻辑。
*   **逻辑**：
    1. 框架校验当前用户权限，若非“管理员”则终止流程。
    2. 校验设备属性，若是“被分享设备”则终止流程。

---

## 5. 注意事项
1.  **防抖机制**：升级检查函数设有一定的防抖时间，确保在短时间内多次触发（如同时初始化并收到推送）时，只执行一次一次有效请求。
2.  **生命周期标记**：内部维护了“已检查”状态，确保在小程序的一次运行生命周期内，不会因为多次检测到强制更新而反复干扰用户。
3.  **退出逻辑**：处理强制升级时，框架会严格执行退出机制。开发者在微调逻辑时需确保不破坏该闭环，以避免固件版本不一致导致的业务异常。
4.  **功能标准化与封闭性**：该 OTA 机制属于基础库内置的统一标准能力，旨在确保所有面板应用在设备固件安全与用户升级体验上保持高度一致。为了保障核心链路的严谨性，目前**不向开发者开放自定义实现的接口或配置项**，请基于框架提供的标准化行为进行业务评估。