升级与回滚

概述

本文给出「升级前要知道什么、按什么顺序做」。回滚完全依赖备份，请先阅读 备份与恢复。适用部署：Docker Compose、原生包（Linux / systemd）、多实例集群（PostgreSQL 族 / MySQL 族元数据库）和内置 H2 单机。

三条硬约束

1. 元数据库迁移不可逆：升级后不能用旧版本程序直接启动旧库。
2. 回滚 = 恢复库 + 数据目录 + 连接密钥，三者成对，缺一不可。不要「只换回旧 jar、不恢复库」，也不要让旧版本实例继续连已迁移的新库。
3. 没有自动回滚，也没有自动滚动升级：逐台替换、摘挂负载均衡、是否回滚都由人决定。

升级前检查清单

缺一项不要开始升级。

自动体检脚本

tools/preupgrade-check.sh 把能自动判定的项跑一遍（只读：不修改文件、不重启服务、不执行 SQL）；--dry-run 只打印计划：

tools/preupgrade-check.sh \
  --url http://127.0.0.1:18680 \
  --data-dir /opt/sight-datalink/data \
  --backup-dir /backup/datalink \
  [--db-url 'jdbc:postgresql://db:5432/datalink'] [--cluster]

输出 [PASS] 通过、[WARN] 需人工确认、[FAIL] 必须修复后再升级；末尾给出 PASS / WARN / FAIL 计数，FAIL 大于 0 时退出码为 1，可直接作为变更流水线的门禁。

• version / schemaVersion 只对本机回环调用返回。从宿主机经发布端口访问 Docker 实例时通常拿不到，请在容器内获取：docker compose exec -T app sh -c 'curl -s http://127.0.0.1:18680/api/health'。
• 脚本不检查运行中的作业、维护窗口、回滚决策人与升级包校验和，这些仍需人工确认。
• 多实例请每台都跑一次并加 --cluster。

提示：正式升级前，建议先在预发环境用同版本的备份演练一次「升级 + 回滚」。

升级顺序

Docker Compose（单实例）

1. 备份（见 备份与恢复），记录 manifest.sha256。
2. 拉取或构建新镜像，记录 digest。
3. docker compose up -d 重建容器。
4. 按下文「升级后验证」检查。

默认 stop_grace_period 为 10 秒。有大查询在跑时，先在界面停止运行再升级；被强杀的运行会进入「中断 / 提交未知」状态，恢复后需人工确认（不会重复提交，但不会自动续跑）。

原生包（systemd）

解压新 ZIP 到临时目录 → 停服务 → 备份旧 jar 与脚本 → 覆盖 sight-datalink.jar 与 *.sh（data/ 原样保留）→ systemctl restart sight-datalink → 验证。sudo ./install.sh 也可完成脚本与服务单元更新（会重启服务）。

多实例集群

不要让多台新实例同时抢着迁移：

1. 从负载均衡摘掉一台，先升级它，其余实例保持旧版本继续服务。
2. 这台实例启动时执行数据库迁移。等日志出现 Started DFDataLinkBackendApplication，/api/health/ready 返回 200，且 schemaVersion 升到目标版本。
3. 在它上面做「升级后验证」，无异常后挂回负载均衡。
4. 逐台替换其余实例，一次一台，替换后立刻校验 ready 再动下一台。
5. 全部替换完成后统一验证，GET /api/ops/cluster 确认成员版本一致、无实例反复重启。

迁移失败、实例反复重启或冒烟不通过时：立即停止替换其他实例，保留日志和 /api/health 输出，按下文「回滚」决策。

内置 H2（单机小规模）

迁移在同一 JVM 内执行。升级前仍必须停服务完成文件级备份；H2 不能多实例，也不要让 data/ 目录被两个进程共用。

迁移失败与启动异常

升级后验证

1. GET /api/health 返回 200 且 schemaVersion 等于目标版本；GET /api/health/ready 返回 200。
2. 登录正常（本地账号与外部登录各一人）。
3. 任务、管道、实时任务、数据服务列表可读；打开一个流程任务画布正常渲染。
4. 手动跑一个轻量任务成功，运行日志与追踪 ID 正常。
5. 数据源「测试连接」通过（证明连接密钥仍可解密）；受管文件与驱动目录可读。
6. GET /api/system/actuator/prometheus 能抓取且有新指标，见 监控、告警与审计。
7. 平台日志出现本次操作审计。
8. 发布 / 回滚一个任务版本，确认权限与版本冲突语义未变。
9. 无实例处于非 ready 状态、无反复重启；GET /api/ops/cluster 成员版本一致。

回滚

触发回滚的条件（任一满足，且在维护窗口内）：迁移失败且没有修复版本；升级后核心链路（登录、任务执行、数据源连接）不可用超过 15 分钟；数据正确性存疑（重复或丢失）；安全修复引入阻塞问题。

回滚必须成对恢复：

1. 停全部实例（集群：每台 systemctl stop / docker compose stop）。
2. 恢复元数据库、数据目录和连接密钥（旧数据目录会被保留）：

   tools/restore.sh --dir '<升级前的备份目录>' --db-url '<DB_URL>' \
     --data-dir /opt/sight-datalink/data --yes
   

3. 换回与备份同版本的程序（jar 或镜像 digest）。
4. 启动并按「升级后验证」检查，确认版本号与 schemaVersion 回到备份时的值。
5. 负载均衡 / DNS 切回，通知使用方，在变更单记录恢复的备份 hash、时间与实际 RTO。

回滚期间，新版本产生的数据会随恢复丢失（以备份点为准）。升级后已有业务写入时，回滚前先评估丢失量是否可接受，或改为向前修复。多实例回滚要全部回到同一版本，不能混跑。

已知边界

• 没有「原地降级」工具，回滚只能恢复库。
• 升级前自动备份与校验没有内置到发布物中，请按本文和 tools/backup.sh 手工执行。
• 集群没有自动滚动升级编排，逐台替换与摘挂负载均衡由部署方完成。
• 迁移失败后的半迁移库需要人工判断后恢复，不提供 repair 封装。
• 告警规则与 Grafana 仪表盘是示例资产，接入通知渠道由部署方配置。

变更记录模板

变更单：            升级人 / 复核人：
当前版本 → 目标版本：
备份目录 / manifest.sha256：        备份校验：通过/失败
升级开始/结束：                     实际耗时：
单实例迁移实例：                    其余实例替换顺序：
验证 1–9： 1☐ 2☐ 3☐ 4☐ 5☐ 6☐ 7☐ 8☐ 9☐
异常与处置：
是否回滚：是/否     回滚原因：            实际 RTO：
后续改进项：

相关文档

• 备份与恢复
• 安装与部署
• 监控、告警与审计