5.4 版本管理与升级：无损换件

5.4 版本管理与升级：无损换件

本节摘要：升级是运维里最大的变更动作，也是最容易翻车的一环。本节给出五步升级法：前置核对、全量备份、试验环境彩排、生产换件、上线验证，外加回退预案与升级窗口的编排。核心原则一句话：升级不是事件，是流程。

前几节把家安好、仪表装好、病历写好，现在练手艺巅峰——不停车换件。平台与插件都在持续演进，升级不可避免；翻车与否的分水岭，在于你把它当一次性的「冒险」还是标准化的「工序」。

一、升级五步法

图 5-3 升级流水线：五步一退路

二、第①步前置核对：清单先行

升级通知发布后，先别拉镜像。拿 4.2 的插件台账过一遍：本次升到的版本，每个在用插件是否声明兼容？商业插件的许可证是否覆盖新版本？自研插件按 4.3 的方法跑一遍构建，接口有没有变化？三项里任何一项存疑，就放缓升级节奏——平台版本的「抢跑红利」从来不值得用生产事故去换。

前置核对清单（复制到升级工单里逐项打勾）：
  □ 目标版本号与本实例当前版本号记录在案
  □ 阅读官方升级说明，标注「破坏性变更」条目
  □ 插件台账逐个核对兼容声明，存疑插件标出
  □ 自研插件在开发工程按新版本构建通过
  □ 升级窗口已公告，回退预案已写好
  □ 试验环境可用，且能拿到生产的全量备份
​

三、第②③步：备份与彩排

备份在 5.1 是例行公事，在升级这里升级为「命脉」：数据库全量、附件目录、当前配置导出包，三样齐活并校验可读。彩排是五步法里最容易被省略、也最不该省略的一步——把生产备份恢复到试验环境，在这个「生产分身」上执行升级，观察迁移日志，跑冒烟清单。彩排会暴露兼容问题的第一现场，同时实测回退时间。彩排通过的升级，生产上只是把同样的动作重放一遍。

彩排后的迁移日志值得逐行读一遍警告：迁移脚本对数据结构做的每个改动都写在这里，出现「跳过」「警告」字样时先弄懂再继续，带着疑问上生产等于把疑问放大十倍。

四、第④⑤步：换件与验证

生产换件选业务低峰，动作本身很短——拉新镜像、替换插件包、重启容器，随后盯启动日志直到插件全部加载完成。容器化部署的升级命令序列如下：

# 生产升级命令序列（编排文件方式）
docker pull nocobase/nocobase:<新版本号>        # 提前拉取镜像，别在窗口内干等下载
docker compose down                              # 停应用容器，数据库容器按编排保留
docker compose up -d                             # 以新版本镜像重建应用容器
docker logs -f <应用容器名>                       # 盯启动日志：迁移执行、插件加载、服务就绪
# 异常时的回退：把编排文件里的镜像与插件包换回旧版本号，再 up -d，随后恢复备份
​

上线验证用一份固定冒烟清单：登录、核心页面打开、一条代表性流程跑通、附件可下载、日志无新增错误形态。验证通过不等于收工——升级后的两三天用 5.2 的巡检加密度观察，版本升级引入的问题常有延迟表现。

⚠️ 常见坑：跳过彩排直上生产。「这次改动不大」是升级事故语录的第一名。彩排的成本是一次试验环境的操作，事故的成本是一次全公司的等待——这笔账不难算。

💡 关键直觉：升级能力的成熟度体现在「敢不敢升」和「多久能退」。清单和彩排做得越足，升级窗口越短，回退越有底气——工序换来的不是慢，是稳。

深入一格：版本对齐台账

五步法的第①步核对，落成一张常驻台账，升级日的核对就从翻记忆变成查表：

版本对齐台账（随插件台账合并维护）：
  平台当前版本：x.y.z     目标版本：x.y+1.z
  官方插件兼容：审批（兼容）工作流（兼容）公式字段（未声明，缓升）
  商业插件许可证：均覆盖新版本，续期在 x 月
  自研插件：工作日计算——新版本构建通过，接口无破坏性变更
  结论：可升 / 缓升（原因：公式字段未声明，等下一版）
  决策人与日期：运维甲 x 月 x 日
​

这张台账把「跟多紧」的策略决策固化成记录：每一行结论都带着原因与决策人，缓升不是拖延而是有据的风险控制。升级完成后追加一行实际结果（迁移有无警告、观察期有无异常），几个版本下来，这张台账就是你们环境的升级史——哪个插件总是拖后腿、哪个版本跨度最稳，一目了然。下一次评估「要不要抢跑新版」时，答案就在自己家的历史里。

升级日的时间表

把五步法落到升级日当天，给一张可直接执行的时间表（以夜间低峰为例）：

升级日时间表（预估两小时，含缓冲）：
  21:30  前置核对清单终审，确认缓升或继续
  21:45  全量备份三件套并校验
  22:00  试验环境彩排复验（备份恢复加升级加冒烟）
  22:40  生产换件：拉镜像、停起容器、盯日志
  23:10  冒烟清单执行，异常则触发回退预案
  23:30  完成通报发群：版本号、耗时、观察要求
  次日起  连续三天加密巡检，异常记入台账
​

时间表的价值在于把「紧张的大事」拆成「按表办事的流程」，每一行都有明确的完成判据。彩排环节放在当晚重复一次，是因为生产备份是最真实的彩排素材——白天的预演加当晚的复验，双保险才敢按下换件的按钮。时间表跑熟之后，升级的心理成本会降到「一次稍长一点的例行发布」，这正是无损换件的最终形态。

升级节奏的年度规划

升级不用等通知来了再临时安排。做一张年度节奏表，把主动权拿回自己手里：每年锁定两个升级窗口（比如季度末与年中），每次窗口只升一个小版本段；窗口之间出新版，记进台账不动手，留给下一个窗口评估。生产实例因此永远处于「落后但稳定」的区间，试验实例月度跟进新版，负责提前踩雷。这张节奏表与 4.2 的插件兼容声明联动，构成你们环境的版本战略。

年度升级节奏（示例，按团队实际调整）：
  每月      试验实例跟进新版，踩雷记录进台账
  季度末    生产窗口一：评估台账，升或明确缓升理由
  年中      生产窗口二：同上，兼顾跨大版本的评估
  随时      安全类紧急升级例外处理，五步法照走但加急
​

装配要点回顾

• 五步工序：核对、备份、彩排、换件、验证，跳步就是赌；
• 核对三件：插件兼容、许可证覆盖、自研插件构建，存疑即放缓；
• 彩排双重价值：暴露兼容问题第一现场、实测回退时间；
• 回退预案：触发条件、动作、时间目标三要素，彩排时写好并演练；
• 验证后观察：冒烟清单加三天加密巡检，延迟问题不漏网；
• 下一站：第 6 章交付工单——把装配与运维的手艺装进项目方法论，收束全册。