4. 版本管理基础

在 rootfs 升级与回滚的工程实践中，版本管理不是“给文件起个名字”这么简单。它决定了设备能否准确判断“我当前是什么版本”“目标版本是否兼容”“升级失败后应该回到哪个版本”。如果版本号、镜像命名、元数据和依赖关系没有统一规范，回滚机制就会变成一场灾难：设备可能回滚到错误版本，或者因为依赖缺失而无法启动。本节将从四个维度建立版本管理的基础设施。

一、版本号规范：语义化版本与构建号

rootfs 版本号建议采用“语义化版本 + 构建号”的组合形式，例如 1.4.2-20240612.3。其中 1.4.2 是语义化版本，分别表示主版本、次版本和修订号；20240612.3 是构建号，表示日期和当日构建序号。语义化版本用于表达兼容性：主版本变化通常意味着不兼容的接口或分区布局变更；次版本变化表示向后兼容的功能新增；修订号变化表示向后兼容的问题修复。构建号则用于区分同一语义版本下的多次构建，便于追溯具体产物。

在设备端，版本号需要被解析为可比较的结构，而不是简单字符串比较。例如 1.10.0 在字符串比较中会小于 1.9.0，但语义上它更大。因此建议在元数据中同时存储版本号字符串和可比较的版本编码，如 version_code=10400。这样升级逻辑可以快速判断新旧关系，避免因字符串比较导致误判。

二、镜像命名：从文件名读出关键信息

镜像命名应遵循“可读、可解析、可校验”的原则。推荐格式为：{产品名}-{版本号}-{硬件型号}-{构建类型}.{扩展名}。例如：

rootfs-gateway-1.4.2-20240612.3-rk3568-release.img
rootfs-gateway-1.4.2-20240612.3-rk3568-debug.img
rootfs-gateway-1.4.3-20240620.1-rk3568-release.img

文件名中必须包含硬件型号，因为不同硬件的 rootfs 可能包含不同的内核模块、设备树和固件。构建类型用于区分 release 和 debug 版本，debug 版本可能包含更多日志和调试工具，但不适合量产设备。扩展名统一为 .img 或 .tar.gz，便于脚本识别。命名中避免空格、中文和特殊字符，确保在 shell 脚本和 URL 中安全使用。

三、元数据管理：版本清单与依赖关系

元数据是版本管理的核心。每个 rootfs 镜像应附带一个 JSON 格式的元数据文件，描述版本号、构建时间、硬件兼容性、依赖组件、校验和等信息。元数据与镜像分离存储，便于在不下载完整镜像的情况下进行版本判断。一个典型的元数据示例如下：

{
  "product": "gateway",
  "version": "1.4.2",
  "build": "20240612.3",
  "version_code": 10402,
  "hardware": ["rk3568", "rk3568b"],
  "rootfs_size": 268435456,
  "sha256": "a3f5c9...e8b2",
  "dependencies": {
    "bootloader": ">=2.1.0",
    "kernel": ">=5.10.110",
    "app_layer": ">=3.2.0"
  },
  "min_compatible_version": "1.2.0",
  "release_notes": "修复网络稳定性问题，更新WiFi固件"
}

其中 dependencies 字段描述了 rootfs 对 bootloader、kernel 和应用层的版本要求。升级前，设备必须检查当前 bootloader 和 kernel 是否满足目标 rootfs 的依赖。如果不满足，应先升级依赖组件，或者拒绝升级并给出明确提示。min_compatible_version 用于回滚判断：如果当前版本低于目标版本的最小兼容版本，回滚可能失败，需要特殊处理。

版本清单（manifest）则是所有可用版本的集合，通常由服务器维护。设备通过请求清单获取可用版本列表，再根据自身硬件型号和当前版本选择合适的目标版本。清单中应包含每个版本的元数据摘要、下载地址和优先级。这样设备不需要遍历所有镜像，只需按清单指引下载。

四、版本清单与依赖关系的协同工作流程

设备启动升级检查时，首先请求版本清单，清单返回可用版本列表。设备根据自身硬件型号过滤出兼容版本，再按 version_code 排序，选择高于当前版本且满足依赖约束的目标版本。然后下载目标版本的元数据，校验 sha256，检查 dependencies 中的 bootloader 和 kernel 版本是否满足。如果满足，则下载镜像并写入备用分区；如果不满足，则记录日志并跳过该版本，尝试下一个候选版本。

回滚时，设备从本地保存的历史版本元数据中查找回滚目标。回滚目标必须满足两个条件：一是其 min_compatible_version 不高于当前版本，二是其依赖的 bootloader 和 kernel 与当前运行版本兼容。如果找不到安全回滚目标，设备应进入恢复模式，而不是盲目回滚。

五、案例复盘：一次因依赖缺失导致的回滚失败

某网关设备从 1.3.0 升级到 1.4.0 后，WiFi 模块无法加载。运维人员决定回滚到 1.3.0。但回滚后设备无法启动，串口日志显示内核模块版本不匹配。排查发现，1.4.0 升级时同时更新了 bootloader 到 2.2.0，而 1.3.0 的 rootfs 依赖 bootloader <2.2.0。回滚时只回滚了 rootfs，没有回滚 bootloader，导致依赖断裂。

复盘结论：回滚不是简单地切换 rootfs 分区，而是需要版本管理系统提供完整的依赖快照。每个版本元数据中应记录“升级时同时变更的组件”，回滚时按快照恢复。如果无法恢复依赖组件，则应拒绝回滚并提示人工介入。这个案例说明，版本管理基础不牢，回滚机制就会在关键时刻失效。