从开发到现场：RK3588 边缘设备的冷部署与 OTA 升级实战

上一篇我们分享了越微自研事件融合引擎与证据链，把 AI 视觉误报率从 75% 降到了 10-15%。但系统做得再好，部署不上去、升级出问题，一切都是白搭。边缘设备分散在各个客户现场，网络不稳定，运维人员技术水平不一，怎么把系统可靠地部署上去？怎么在不中断业务的情况下安全升级？本文分享我们的冷部署与 OTA 升级方案，以及踩过的那些坑。

---

一、背景：边缘设备的部署运维挑战

做边缘计算产品，部署和运维是绕不开的难题。和云端服务不同，边缘设备有几个特殊的挑战：

挑战一：设备分散，现场环境复杂

边缘设备不是集中在数据中心，而是分散在各个客户现场——工厂车间、园区角落、仓库、楼道、电线杆上。设备可能接的是不稳定的 WiFi，可能经常断电，可能温度很高（夏天车间 40 度以上），可能灰尘很大。

在这种环境下，部署和升级不能假设「网络稳定、电源稳定、环境可控」，必须考虑各种异常情况。

挑战二：运维人员技术水平不一

云端服务的部署运维由专业的运维工程师操作，但边缘设备的现场操作可能是客户的保安、电工、行政人员——他们可能不懂 Linux，不会敲命令，甚至不会用 SSH。

部署和升级流程必须足够简单，最好是「下一步、下一步、完成」的图形化操作，或者一键脚本，不能要求运维人员懂技术细节。

挑战三：升级不能中断业务

边缘设备通常在 7×24 小时运行，升级的时候不能长时间中断业务——客户的安防系统不能因为升级就停半小时，工厂的质检系统不能因为升级就停一条线。

升级必须快速、可靠、可回滚——升级出了问题能立即回滚到旧版本，不能让设备变砖。

挑战四：配置和数据不能丢

升级的时候，设备上的配置（摄像头地址、任务参数、ROI 设置）、历史数据（告警记录、证据图）、日志都不能丢。如果升级把配置搞丢了，客户要重新配置一遍，体验非常差。

我们早期的版本就踩过这个坑——升级脚本直接覆盖了整个目录，把客户的配置和数据都覆盖了，客户非常生气。后来我们才把「生产数据」和「编译制品」严格分开。

---

二、我们的部署架构：热插拔扁平布局 [Yuewell Inside]

针对这些挑战，我们设计了一套「热插拔扁平布局」的部署架构。核心思想是：目录结构简单清晰，生产数据和编译制品严格分离，升级只替换编译制品，不碰生产数据。

目录结构

```

部署根目录/

├── run.sh # 总控脚本：start | stop | restart | install-systemd

├── VERSION # 版本号文件

├── systemd/ # systemd 服务配置

│ ├── install_systemd.sh # 安装 systemd 服务

│ └── yw-avis.service # systemd unit 文件

├── backend/ # 后端服务（边缘核心服务 + 推理引擎）

│ ├── bin/ # 可执行文件（编译制品，升级时替换）

│ ├── lib/ # 依赖库（编译制品，升级时替换）

│ ├── models/ # AI 模型文件（编译制品，升级时替换）

│ ├── scripts/ # 运维脚本（编译制品，升级时替换）

│ ├── configs/ # 配置文件（生产数据，升级不覆盖）

│ ├── data/ # 数据库文件（生产数据，升级不覆盖）

│ └── logs/ # 运行日志（生产数据，升级不覆盖）

└── client/ # 客户端程序

├── bin/ # 客户端可执行文件（编译制品，升级时替换）

└── configs/ # 客户端配置（生产数据，升级不覆盖）

```

核心原则：生产数据 vs 编译制品

可覆盖（编译制品）：bin/、lib/、models/、scripts/、systemd/、run.sh、VERSION

• 这些是编译生成的文件，每次升级都用新版本替换
• 丢了也没关系，重新部署一份就行

严禁覆盖（生产数据）：configs/、data/、logs/

• 这些是客户的配置、历史数据、日志，升级时绝对不能碰
• 丢了可能导致客户要重新配置、历史告警记录丢失，是严重事故

这个分离原则是部署架构的基石。 升级脚本只替换编译制品目录，生产数据目录原封不动。这样不管怎么升级，客户的配置和数据都安全。

为什么叫「热插拔扁平布局」？

• 扁平：目录结构不深，所有关键目录都在部署根目录下，运维人员一眼就能看懂，找文件方便
• 热插拔：整个部署目录可以整体打包、传输、解压、替换，像插 U 盘一样简单。不需要复杂的安装器，不需要解决依赖，解压就能用
• 后端和客户端分树（backend/ 和 client/ 分开），可以只升级后端不升级客户端，或者反过来，灵活方便

---

三、冷部署：新机器怎么装系统？

冷部署是指全新的 RK3588 设备，第一次安装我们的系统。这时候设备上什么都没有，需要从零开始部署。

冷部署的流程

我们把冷部署流程设计成「传两个文件，跑一条命令」：

1. 准备两个文件：

- 冷部署包（tar.gz 格式，包含完整的编译制品 + 初始配置模板 + 部署脚本）

- 引导脚本（bootstrap_deploy.sh，负责解压、校验、安装）

1. 把两个文件传到新机器上（用 U 盘拷贝或 scp 传输）

1. 跑一条命令：

```

sudo ./bootstrap_deploy.sh --archive 部署包.tar.gz --dest /部署目录 --install-systemd

```

1. 等待完成——引导脚本自动完成所有操作，完成后系统已经在运行了

引导脚本做了什么？

引导脚本（bootstrap）内部做了这些事情：

1. SHA256 清单校验——部署包里带了一个清单文件（manifest），记录了每个文件的 SHA256 哈希。引导脚本解压后，逐一校验每个文件的哈希，确保部署包在传输过程中没有损坏、没有被篡改。校验失败就中止，不继续安装。

1. 权限自愈——解压后的文件可能权限不对（比如从 Windows 传过来的文件丢了执行权限）。引导脚本自动修复所有文件和目录的权限——可执行文件加 +x，配置文件设为合适的权限，目录设为合适的权限。确保不会因为权限问题导致服务起不来。

1. 白名单合并——如果设备上已经有旧版本的配置（比如之前装过 demo 版），引导脚本会把旧配置和新配置模板合并，保留客户的自定义配置，而不是直接覆盖。

1. 保留生产数据——如果设备上已经有 data/ 和 logs/（比如重装系统），引导脚本不会删除它们，而是保留下来。

1. 安装 systemd 服务——把 systemd unit 文件安装到系统目录，enable 并 start 服务。安装完成后，系统会自动启动，并且开机自启。

整个过程不需要运维人员懂 Linux，只需要会传文件、会敲一条命令就行。 而且每一步都有校验和保护，不容易出问题。

为什么严禁用 Xftp 散文件覆盖？

有些运维人员图省事，用 Xftp 之类的工具把文件一个个传到设备上，覆盖整个目录。我们严禁这种做法，原因是：

• 丢执行权限：Xftp 传输可能丢失文件的执行权限（+x），导致服务起不来
• 无法校验完整性：散文件传输没有 SHA256 校验，传坏了也不知道
• 可能覆盖生产数据：散文件覆盖可能不小心覆盖了 configs/、data/、logs/，导致配置和数据丢失
• 版本混乱：散文件覆盖可能新旧文件混杂，不知道哪个版本是哪个

正确的做法永远是：用打包好的部署包 + 引导脚本，不要散文件覆盖。

---

四、OTA 升级：已有设备怎么安全更新？ [Yuewell Inside]

冷部署只做一次（新机器装系统），之后所有的更新都走 OTA（Over-The-Air）升级。OTA 升级是边缘设备运维中最频繁、也最容易出问题的环节。

OTA 升级的设计目标

我们设计 OTA 升级机制时，定了几个目标：

1. 不中断业务——升级过程尽量短，最好几秒内完成
2. 可回滚——升级出了问题，能立即回滚到旧版本，不能变砖
3. 不丢数据——升级不碰配置和数据
4. 操作简单——运维人员在客户端界面点几下就能完成，不需要敲命令
5. 可校验——升级包完整性校验、依赖检查，确保升级后能正常运行

OTA 升级包和冷部署包的区别

很多人会问：OTA 升级包和冷部署包有什么区别？为什么不直接用冷部署包升级？

核心区别：OTA 升级包不含配置和数据，只包含编译制品（bin/lib/models/scripts）。 因为升级的时候，客户的配置和数据必须原封不动地保留。

OTA 升级的流程

OTA 升级通过客户端（UI/交互层进程）的图形界面操作，运维人员不需要敲命令：

1. 运维人员在客户端打开「系统设置 → 设备基础运维 → 升级软件」
2. 选择 OTA 升级包（tar.gz 格式）
3. 客户端把升级包流式上传给后端（边缘核心服务）
4. 后端做升级前检查（preflight）：

- 磁盘余量检查（确保有足够空间解压升级包）

- 数据库 schema 版本检查（确保新版本兼容当前数据库）

- systemd 检查（确保服务管理方式正确）

- 升级包 SHA256 校验（确保包完整无损）

1. 检查通过后，后端应用升级：

- 停止后端服务

- 备份当前版本的 bin/ 到 backup 目录（用于回滚）

- 用升级包的新 bin/lib/models/scripts 替换旧版本

- 启动后端服务

- Watchdog 开始监控

1. Watchdog 监控期（约 10 秒）：

- 如果服务正常启动、健康检查通过 → 升级成功，清理备份

- 如果服务启动失败、健康检查不通过 → 自动回滚：从 backup 恢复旧版本，重启服务，确保设备恢复正常

1. 客户端显示升级结果：成功或失败（失败时显示回滚成功）

整个升级过程通常只需要 10-30 秒（取决于升级包大小），业务中断时间就是服务重启的那几秒。如果升级失败，Watchdog 自动回滚，设备恢复到升级前的状态，不会变砖。

客户端热切换

如果升级包包含客户端更新（--with-client），客户端的升级更讲究——因为升级过程中客户端正在运行，不能直接覆盖正在运行的可执行文件。

我们的做法是客户端热切换：

1. 新版本客户端解压到 client/bin_staging/（临时目录）
2. 后端升级完成、Watchdog 确认后端正常后，触发客户端重启
3. 客户端重启时，用原子操作（rename）把 bin_staging/ 替换成 bin/
4. 新版本客户端启动，升级完成

原子 rename 保证了切换的瞬间性——要么还是旧版本，要么已经是新版本，不会出现「半新半旧」的中间状态。即使切换过程中断电，重启后也能恢复到一致的状态。

依赖检查（dependency_check）

升级不仅仅是替换文件，还要确保新版本的依赖在当前设备上都满足。我们做了依赖检查：

• glibc 版本检查：新版本编译时用的 glibc 版本，设备上的 glibc 不能太旧，否则运行会报错
• 系统库检查：新版本依赖的系统库（如 libstdc++、libssl 等）是否存在
• bundled 库校验：我们打包的依赖库（gRPC、FFmpeg、MPP、RKNN、RGA 等）的 SHA256 是否和预期一致，确保没有损坏
• BSP 版本检查：RK3588 的板级支持包（BSP）版本是否兼容（MPP、RGA、RKNN 驱动版本要和 BSP 匹配）

任何一项检查不通过，升级就中止，不会继续。这样可以避免「升级完了才发现依赖不满足，服务起不来」的尴尬。

---

五、部署免疫层：让部署更健壮的保护层 [Yuewell Inside]

冷部署和 OTA 升级的流程中，我们嵌入了一层「部署免疫层」——一组自动执行的保护机制，确保部署和升级过程中不会因为权限、完整性、依赖等问题导致服务起不来。

免疫层的组成

1. 权限自愈（heal_deploy_permissions）

• 在启动、安装、OTA、冷部署等各个环节自动执行
• 修复所有文件和目录的权限——可执行文件加 +x，配置文件设为 644，目录设为 755
• 单个文件的权限修复失败不中断主流程（Tier-2 容错），记录日志继续
• 解决了「从 Windows 传文件丢执行权限」「解压后权限不对」等常见问题

2. SHA256 清单校验

• 冷部署包和 OTA 升级包都带 manifest 文件，记录每个文件的 SHA256
• 部署/升级时逐一校验，确保文件完整、未被篡改
• 校验失败立即中止，不继续安装

3. preflight 检查

• 升级前做全面检查：磁盘余量、数据库 schema、systemd 状态、依赖库版本、BSP 版本
• 任何一项不通过就中止升级，给出明确的错误提示
• 避免「升级到一半发现条件不满足，进退两难」

4. Watchdog 回滚

• OTA 升级后自动监控服务启动状态
• 10 秒内服务未就绪 → 自动回滚到旧版本
• 回滚后再次启动服务，确保设备恢复正常
• 回滚过程也有日志记录，方便排查

5. 生产数据保护

• 所有部署/升级脚本都明确排除 configs/、data/、logs/ 目录
• 这些目录不会被替换、删除、覆盖
• 即使升级脚本出 bug，也不会碰生产数据（代码层面的硬保护）

部署免疫层的核心思想是：假设运维人员会犯错、假设网络会出问题、假设文件会损坏，然后在每个环节都加上自动保护机制，让系统自己「免疫」这些常见问题。

---

六、四类部署场景：什么时候用哪种方式？

我们把部署场景分成四类，每类用不同的方式，不要混用：

使用原则：

• 日常开发优先用场景 A（最快），需要验证 OTA 流程时用场景 B
• 新机器只做一次场景 C（冷部署），之后一律用场景 D（OTA），不要再用冷部署包做日常更新
• 严禁用 Xftp 散文件覆盖整个部署目录

---

七、实战案例：50 台设备的批量 OTA 升级

我们有一个客户，现场部署了 50 台 RK3588 边缘设备，分布在园区的各个角落。有一次我们发布了一个重要版本（算法模型升级 + 后端性能优化），需要给 50 台设备全部升级。

升级前的准备

1. 在测试环境充分验证——先在实验室的 3 台测试设备上跑 OTA 升级，验证升级流程、Watchdog 回滚、升级后功能正常
2. 小范围灰度——先给客户现场的 2 台设备升级，观察 24 小时，确认稳定
3. 准备回滚方案——确认升级包有问题时，运维人员知道怎么手动回滚（虽然 Watchdog 会自动回滚，但要有手动方案兜底）
4. 选择升级时间窗口——和客户确认在业务低峰期（如凌晨 2-4 点）升级，减少对业务的影响

批量升级过程

因为设备分散在园区各处，运维人员不可能一台一台地接显示器操作。我们的做法是：

1. 运维人员带着笔记本电脑，连接到园区内网
2. 用客户端的「批量升级」功能（我们后来加的功能），一次性选择所有 50 台设备
3. 上传 OTA 升级包，客户端自动并行推送给所有设备
4. 每台设备独立执行 OTA 升级流程（preflight 检查 → 替换文件 → 重启 → Watchdog 监控）
5. 客户端实时显示每台设备的升级进度和结果

升级结果

50 台设备中：

• 48 台升级成功，耗时约 5 分钟（并行升级，不是一台一台串行）
• 2 台升级失败——一台是磁盘余量不足（preflight 检查拦截，没有开始升级），一台是升级后服务启动异常（Watchdog 自动回滚，恢复到旧版本）
• 运维人员对失败的 2 台做了处理（清理磁盘、检查日志），然后重新升级，全部成功

整个批量升级过程不到 1 小时，没有一台设备变砖，没有一台设备丢失配置和数据。 客户对这个结果很满意。

一次 Watchdog 回滚救场的真实案例

还有一次印象深刻的升级：我们发布了一个版本，在测试环境验证没问题，但到了客户现场，有一台设备升级后服务起不来——原因是那台设备的 BSP 版本比较老，新版本依赖的 RGA 驱动接口在老 BSP 上不兼容。

幸运的是，Watchdog 在 10 秒内检测到服务未就绪，自动回滚到了旧版本，设备恢复正常。运维人员收到回滚通知后，联系我们排查，发现是 BSP 版本问题，给那台设备单独升级了 BSP，然后重新升级应用，成功完成。

如果没有 Watchdog 自动回滚，那台设备就变砖了——运维人员要跑到现场，接显示器，手动恢复，非常麻烦。 Watchdog 回滚机制在关键时刻救了场。

---

八、踩坑实录

部署和升级的过程中，我们踩了很多坑，分享几个印象深刻的。

坑一：升级覆盖了客户配置，客户暴怒

我们早期的升级脚本很简单——直接 tar 解压覆盖整个部署目录。有一次升级，把客户的 configs/ 目录覆盖了，客户花了半天配置的 20 多路摄像头参数、ROI 区域、任务设置全部丢失，恢复成了默认配置。

客户发现后非常生气：「你们升级怎么把我的配置搞没了？我要重新配一遍，你们知道要花多久吗？」

教训：从那以后，我们把生产数据（configs/data/logs）和编译制品（bin/lib/models/scripts）严格分离，升级脚本只替换编译制品，绝对不碰生产数据。并且在代码层面做了硬保护——升级脚本里明确排除生产数据目录，即使想覆盖也覆盖不了。

坑二：散文件传输丢执行权限，服务起不来

有一次运维人员用 Xftp 把编译后的可执行文件传到设备上，覆盖了旧版本。结果服务起不来，排查了半天才发现——Xftp 传输把文件的执行权限（+x）弄丢了，文件变成了 644，没有执行权限，systemd 启动时报「Permission denied」。

教训：严禁用 Xftp 散文件覆盖，必须用打包好的部署包 + 引导脚本/OTA 升级。引导脚本里有权限自愈机制，自动修复所有文件的执行权限。

坑三：升级后 systemd 无法启动，日志权限不对

有一次 OTA 升级后，服务起不来，查日志发现是 logs/ 目录的属主不对——升级脚本是以 root 身份运行的，创建的 logs/ 目录属主是 root，但服务是以普通用户（linaro）身份运行的，没有权限写 logs/，导致启动失败。

教训：升级脚本中增加了运行时权限修复（fix_runtime_permissions）——升级完成后，把 data/ 和 logs/ 目录的属主改回服务运行用户。并且在部署免疫层的权限自愈中也加入了属主检查和修复。

坑四：OTA 升级包和冷部署包搞混，配置被重置

有一次运维人员给已经部署了的设备做日常更新，误用了冷部署包（而不是 OTA 升级包）。冷部署包包含初始配置模板，引导脚本在「白名单合并」时，把客户的一些自定义配置重置成了默认值。

虽然没有完全丢失配置（白名单合并保留了大部分），但有几个扩展字段被重置了，客户需要重新设置。

教训：在冷部署包和 OTA 升级包的文件名、包内清单、客户端 UI 上都做了明确区分——文件名前缀不同（yw_avis_deploy_ vs yw_avis_upgrade_），包内 manifest 里有 package_type 字段，客户端 UI 会检查包类型，用错了会提示并拒绝。运维人员很难再搞混。

⚠️ 工程坑点与技术壁垒警告

提示：部署与升级看起来是「传文件、解压、重启」这么简单，但工程落地中有极高的技术壁垒：
生产数据与编译制品的严格分离：说起来简单，但要在所有脚本、所有流程、所有异常情况下都保证生产数据不被碰，需要在代码层面做硬保护，并且经过大量故障注入验证。一个疏忽就可能导致客户配置丢失，是严重事故。
Watchdog 回滚的可靠性：升级失败自动回滚说起来简单，但要保证回滚过程本身不失败、回滚后服务一定能起来、回滚过程中不会丢数据，需要大量的工程细节和异常处理。如果回滚机制本身有 bug，升级失败就可能导致设备变砖。
跨 BSP 版本的兼容性：不同客户的 RK3588 设备可能用不同版本的 BSP，MPP、RGA、RKNN 驱动接口可能有差异。升级包要兼容多种 BSP 版本，或者在 preflight 检查中精确识别并拒绝不兼容的版本。这些兼容性细节需要大量的真机测试。
这些工程细节不是看几篇博客就能搞定的，需要在真实设备上反复调试、压测、故障注入。越微团队在这上面投入了大量时间，才打磨出稳定的部署与升级体系。

---

九、几点经验总结

回头看冷部署和 OTA 升级的设计和落地过程，总结几点：

1. 生产数据和编译制品分离，是部署架构的第一原则

这是我们用客户暴怒换来的教训。配置、数据、日志是客户的资产，绝对不能在升级中丢失或覆盖。目录结构、升级脚本、代码层面都要做硬保护，确保生产数据万无一失。

2. 冷部署和 OTA 升级是两回事，不要混用

冷部署面向全新设备，包含初始配置；OTA 面向已有设备，不含配置。两者的包格式、应用方式、回滚机制都不同。要在文件名、manifest、UI 上做明确区分，避免运维人员用错。

3. Watchdog 自动回滚是 OTA 升级的「安全带」

没有任何升级能保证 100% 成功——测试环境没问题，不代表客户现场没问题（BSP 版本、硬件差异、网络状况都可能导致问题）。Watchdog 自动回滚能在升级失败时自动恢复旧版本，确保设备不变砖。这是 OTA 升级必须有的机制，不能省。

4. 部署免疫层不是「锦上添花」，是「必需品」

权限自愈、SHA256 校验、preflight 检查、生产数据保护——这些机制看起来琐碎，但每一个都是踩坑踩出来的。边缘设备的现场环境复杂，运维人员水平不一，没有这些免疫层，部署和升级会频繁出问题。免疫层让系统对常见问题有「自愈能力」，大大降低了运维成本。

5. 升级操作要图形化，不要要求运维人员敲命令

边缘设备的现场运维人员可能不懂 Linux，不会敲命令。把升级操作做成客户端图形界面的「选择文件 → 点升级 → 看进度」，运维人员零学习成本就能操作。而且图形界面可以做更多校验和提示（包类型检查、preflight 结果展示、进度条、失败原因），比命令行更友好、更安全。

6. 批量升级要并行，不要串行

几十台上百台设备，如果一台一台串行升级，耗时太长。要支持并行升级——客户端同时给多台设备推送升级包，每台设备独立执行升级流程，客户端统一监控进度和结果。50 台设备并行升级 5 分钟完成，串行可能要几个小时。

---

写在最后

部署和升级，是边缘计算产品「最后一公里」的问题。算法再准、系统再快，如果部署不上去、升级出问题，客户就用不起来。我们在这上面花了很多时间，踩了很多坑，才搭起一套「冷部署简单可靠、OTA 升级安全可回滚、部署免疫层自动保护」的完整方案。

这些经验都是我们（越微智能）在实际项目中踩坑踩出来的。我们团队一直在做工业 AI 视觉、边缘计算部署、机器人二次开发这些落地工作，边缘 AI 视频分析系统是我们的核心产品之一。下一篇是这个系列的收官篇，我们会回顾整个边缘 AI 视觉系统的架构演进，聊聊未来的发展方向。

如果你也在做边缘设备部署、OTA 升级、嵌入式系统运维相关的工作，欢迎交流，我们一起踩坑、一起进步。

---

关于作者与团队：
越微智能（Yuewell）是一支专注具身智能与工业 AI 视觉落地的技术团队，提供工业级视觉算法定制（30+ 算法）、RK3588 边缘一体机、具身机器人调度管理平台、全品牌机器人二次开发（适配宇树/优必选/智元/傅利叶等）、ROS2 系统开发等产品和服务，支持从算法、硬件到产线实机部署的全栈交付。
我们将这套经过大量现场验证的部署与升级体系，封装为了工业级边缘 AI 视觉基座（Yuewell Edge Framework）的核心模块，支持硬件/算法快速二次开发，帮助客户跳过最痛苦的部署运维阶段。
📌 获取更多技术白皮书、工业 AI 视觉方案与产品交流，欢迎访问越微智能官网：https://yuewell.com/
下一篇预告（系列收官）： 《边缘 AI 视觉系统的架构演进与未来方向》，我们将回顾整个系列的核心内容（三进程架构、MPP+RGA 硬加速、同源多任务调度、零拷贝通信、多模型推理、事件融合、部署运维），聊聊边缘 AI 的行业趋势（大模型边缘化、VLA 与视觉融合、边缘-云协同），以及越微智能在这个领域的实践和思考，敬请关注。