4. 固件版本管理：语义化版本号、版本兼容性矩阵、版本回滚策略

版本管理这事儿，看着简单，做起来全是坑。我见过太多团队，固件版本号随便写，今天 v1.0，明天 v2.0，后天又来个 v1.5。结果呢？现场设备升级后出问题，连哪个版本能回滚都搞不清楚。

说白了，版本管理不是给版本号编个号就完事了。它要回答三个问题：这个版本改了啥？跟其他版本能不能搭？出问题了怎么退回去？ 咱们一个一个说。

4.1 语义化版本号：别让版本号变成流水号

语义化版本号（SemVer）的规则其实很简单：主版本号.次版本号.修订号。但真正用好的团队不多。

字段	含义	什么时候加1
主版本号	不兼容的API/协议变更	修改了通信协议、数据格式、硬件接口
次版本号	向下兼容的功能新增	增加了新功能，旧功能不受影响
修订号	向下兼容的问题修复	修bug、性能优化、安全补丁

举个例子。我做过一个项目，网关的MQTT数据上报格式从JSON改成了Protobuf。这就是主版本号变更——从 v2.x.x 跳到 v3.0.0。因为旧版云平台解析不了新格式，必须同步升级。

但如果你只是给Web管理页面加了个重启按钮，那就是次版本号变更，v2.1.0 就够。修了个内存泄漏的bug，v2.0.1 搞定。

4.2 版本兼容性矩阵：一张表说清楚能不能搭

网关固件不是孤立的。它要跟Bootloader、云平台、子设备固件、配置工具打交道。版本之间能不能搭，不能靠猜。

我建议每个项目维护一张版本兼容性矩阵。这张表长这样：

网关固件	Bootloader ≥ 2.0	云平台 ≥ 3.1	子设备固件 ≥ 1.5	配置工具 ≥ 2.0
v3.0.0	✅ 必须	✅ 必须	✅ 必须	✅ 必须
v2.5.0	✅ 必须	✅ 必须	⚠️ 建议升级	✅ 必须
v2.0.0	✅ 必须	⚠️ 建议升级	✅ 必须	✅ 必须
v1.0.0	❌ 不兼容	❌ 不兼容	✅ 必须	❌ 不兼容

这张表怎么用？升级前先查一下。比如你想把网关从 v2.0.0 升到 v2.5.0，一看表：Bootloader 和配置工具都兼容，但子设备固件建议升级。那你就得评估，不升子设备会不会出问题。

兼容性矩阵的维护方式，我推荐用YAML文件放在代码仓库里，每次发版时更新。这样CI/CD流程可以直接读取，自动生成升级策略。

# compatibility_matrix.yaml
gateway_firmware:
  v3.0.0:
    bootloader: ">=2.0.0"
    cloud_platform: ">=3.1.0"
    sub_device: ">=1.5.0"
    config_tool: ">=2.0.0"
  v2.5.0:
    bootloader: ">=2.0.0"
    cloud_platform: ">=2.0.0"
    sub_device: ">=1.0.0"
    config_tool: ">=2.0.0"

4.3 版本回滚策略：留好退路

升级失败怎么办？这是每个做网关的人必须面对的问题。我的原则是：没有回滚方案的升级，就是耍流氓。

回滚策略分三个层次：

1. 应用层回滚：只回滚固件本身，Bootloader不动。适用于功能bug、性能问题。
2. 系统层回滚：回滚整个系统镜像，包括内核和文件系统。适用于驱动不兼容、启动失败。
3. 硬件层回滚：通过物理手段（比如串口、SD卡）强制刷写。适用于Bootloader损坏、分区表错误。

具体怎么做？我推荐双分区方案：

• Active分区：当前运行的固件
• Standby分区：备份的固件（通常是上一个稳定版本）

升级流程是这样的：

1. 新固件下载到 Standby 分区
2. 校验完整性（CRC、签名）
3. 设置启动标志为 Standby 分区
4. 重启设备
5. 如果启动成功，把 Active 分区标记为可覆盖
6. 如果启动失败，自动切回 Active 分区

回滚策略的决策树，我画了张图：

4.4 版本管理的工程实践

最后分享几个我在项目中沉淀下来的实践：

• 版本号硬编码在固件里：编译时从Git tag自动生成，不要手动改。我见过有人手抖把 v2.0.0 写成 v2.0.1，排查了三天。
• 兼容性检查放在升级前：不要在升级过程中才发现不兼容。我习惯在升级请求里带上当前版本号，服务端查表后返回"允许升级"或"拒绝升级"。
• 保留至少两个历史版本：Standby分区里永远存着上一个稳定版本。如果升级后发现问题，可以一键回滚。
• 回滚日志必须记录：谁、什么时间、从哪个版本回滚到哪个版本、原因是什么。这些日志是后续排查问题的关键线索。