VelaGuard 是我们在 openvela（NuttX）上为 STM32H750B-DK 开发的一款工业边缘网关：它通过 Modbus 采集现场数据，在本地完成规则判断与告警，再经由 MQTT 把关键信息上送云端，并借助 AI 助手完成诊断与配置建议。

在项目演进的过程中，我们陆续记录下五项架构决策（ADR，Architecture Decision Record）。它们看起来是零散的技术选型，背后却贯穿着一条一致的思路：

现场可靠性优先，云端只是增强，绝不成为依赖。

本文把这五条决策整理成文，并说明每一条背后的权衡。

一、独立网关，本地安全回路优先（ADR 0001）

决策：VelaGuard 是一台独立的 STM32H750B-DK 网关，而不是挂在 PC 上的“边车”式演示。

背景：不少物联网演示项目把采集、判断与展示都放在 PC 或云端，开发板只是传感器前端。一旦网络或云端服务不可用，整套系统便随之瘫痪。

理由：VelaGuard 的工业价值恰恰在于“现场依然有用”。因此，Modbus 采集、规则评估、界面告警、本地日志、本地告警音——这一整条本地安全回路——必须在没有网络、没有 MQTT、没有 AI Bridge、没有 MiMo/TTS/ASR、也没有连接电脑的情况下照常运转。云端能力失效时，网关仍然守在现场。

二、经 MQTT Broker 与 AI Bridge 接入云端，板端不直连 MiMo（ADR 0002）

决策：板端只与 MQTT Broker 通信；MiMo、TTS、ASR 与手册解析等 AI 能力，统一由独立的 AI Bridge 服务通过 HTTPS 调用。

背景：如果让板子直接调用大模型与语音服务的 HTTPS API，重试、鉴权、凭据管理以及高流量的 AI 工作流，都会被压在一块嵌入式板卡上。

理由：多引入一个轻量云组件，换来的是把重量级的 HTTPS/API 处理、重试与凭据逻辑、大型 AI 工作流全部移出 H750B-DK。网关保持“独立网关”的形态，云侧的复杂度被关在云侧。

三、生产固件的设备 ID 稳定且不可在运行时修改（ADR 0003）

决策：生产固件从 STM32 UID 派生 device_id，并且不提供任何运行时修改接口；测试固件可以通过代码或编译期配置覆盖。

理由：设备身份是 MQTT Topic、ACL、鉴权、日志与云端路由的共同基础。如果它能在 UI、串口、HTTP 或 MQTT 上被意外改动，整条云链路的可靠性与安全性都会动摇。身份稳定，是其余一切云侧机制成立的前提。

四、AI 生成的配置必须经过设备端确认（ADR 0004）

决策：AI 可以生成候选配置，但 VelaGuard 只有在设备端完成 schema 校验、风险评估、试读验证与本地确认之后，才会真正激活它。

背景：直接采纳 AI 输出是最省事的路径——但一个错误的 Modbus 寄存器、阈值或规则，即使 AI 的输出看起来头头是道，也可能在工业现场制造出误导性的告警。

理由：在“AI 看起来很合理”与“现场数据真实可靠”之间，我们把最后一道闸门放在设备端：AI 提供建议，本地负责确认。

五、OTA 只走 MQTT 拉取，不加板端 HTTPS 下载器（ADR 0005）

决策：固件升级的控制与分片传输统一走 MQTT/TLS；不在板端实现 HTTPS 下载器。

背景：大文件固件交付在工业产品中通常选择 HTTPS，这本身是常见且合理的选择。

理由：本项目更看重一条单一的鉴权通路：经过认证的 MQTT 链路、更简单的嵌入式网络栈、直接复用 Broker 的 ACL，并能与本地确认、进度上报、失败回滚紧密集成。少一条协议通路，就少一类攻击面，也少一类调试成本。

结语

回头看，这五条决策可以压缩成一句话：把可靠性留在现场，把复杂性留在云侧，把最终决定权留在设备端。

  • 本地安全回路（ADR 0001）保证离线可用；
  • Broker + AI Bridge（ADR 0002）保证板端轻盈；
  • 稳定身份（ADR 0003）保证云侧链路可信；
  • 设备端确认（ADR 0004）保证 AI 不越权；
  • MQTT 统一 OTA（ADR 0005）保证升级路径收敛。

对一个要在现场长期运行的工业网关来说，这些选择的价值，往往要等到云端真正出故障的那一天才会显现。

本文整理自团队仓库 docs/adr/ 中的 0001–0005 决策记录。