升级与变更管理

概述

升级的核心动作是：停止服务、替换产品 jar、启动服务。启动时程序会自动对配置库执行数据库迁移（Flyway），授权保存在配置库中，不因替换 jar 而丢失。没有单独的升级工具或节点 Agent。

数据库迁移是升级中唯一不可逆的部分：迁移一旦执行，配置库的表结构就已改变。所以升级前必须备份配置库。

升级前准备

1. 阅读 更新日志，留意不兼容变更。
2. 备份配置库。使用数据库自身的备份工具做一次全量备份，这是回滚的依据。同时可在「系统 > 智能运维 > 备份恢复」页点击「立即备份」，生成一份平台备份包，见 备份与恢复。
3. 备份程序目录下的 data/work/database.config（配置库连接信息）。使用内置数据库时，在停服后备份整个 data/work/db/ 目录。
4. 保留旧版本 jar：替换前把旧 jar 改名为带时间戳的名字并放到程序目录之外或其他位置。注意程序目录里只能保留一个 sight-*.jar，否则脚本会警告并取第一个。
5. 选择业务低峰时段，先在测试环境演练。

单机升级步骤

1. 停止服务：

   sudo systemctl stop sight-report
   

   前台运行时按 Ctrl+C。Windows 可用 schtasks /end /tn sight-report 或结束进程。

2. 保存旧 jar，再放入新 jar：

   cd /opt/sight-report
   mv sight-report.jar /opt/backup/sight-report.jar.$(date +%Y%m%d%H%M)
   cp /path/to/new/sight-report.jar ./sight-report.jar
   

3. 如果新版本包里有 start.sh、install.sh 的更新，一并覆盖。服务已注册的情况下，install.sh 无需重跑，除非需要变更 profile 或 JVM 环境变量。

4. 启动服务：

   sudo systemctl start sight-report
   journalctl -u sight-report -f
   

5. 观察日志：升级时日志会出现执行 Flyway 数据库迁移的记录。迁移完成、服务启动后，请求 GET /api/health，确认 ready 为 true。

6. 登录系统验证：在「系统 > 注册管理」查看「产品版本」与授权状态；打开几张典型报表确认能正常运行。

用 zip 整包覆盖时的注意事项

发行包里带有一个 data/ 目录，其中只有 data/models/（语义检索模型，随版本走的只读文件）。用 unzip、tar 或 FTP 普通覆盖上传时，是逐文件合并：只会替换同名的模型文件，data/ 下的 backups、cache、drivers、work 等原样保留。

下面三种做法会连同数据库连接配置、内置数据库、授权相关文件、备份包一起删除，必须避免：

推荐做法：日常升级只替换 jar 这一个文件，其余目录不动；只有模型本身有更新时才需要替换 data/models/。

集群升级

1. 先做配置库备份与平台备份，见上文。
2. 节点在启动时执行数据库迁移，先启动的新版本节点会改变配置库表结构。为避免新旧版本同时读写同一个库，建议在维护窗口内先停止全部节点，再逐个替换 jar 并启动。这是建议做法，程序没有提供「新旧版本混跑」的兼容保证。
3. 每启动一个节点，用 GET /api/health 确认 ready 为 true，并在「系统 > 智能运维 > 运行状态」页确认该节点出现在活跃节点列表中。
4. 全部节点启动后，验证登录、报表运行、定时任务。
5. 节点数受授权 nodeMax 限制，见 集群与高可用。

升级与授权

• 授权保存在配置库，替换 jar 不影响授权。集群中任一节点导入授权后，其他节点自动同步。
• 授权页上的「授权版本」仅作展示，不参与校验。
• 从较早版本升级时，如果程序目录里存在历史文件 env-secret，新版本首次启动会读取它并收进配置库，已注册的授权不受影响。升级前不要删除该文件。
• 机器绑定默认强制（app.license.bind-enforce=true）。旧授权如果没有写入绑定信息，则直接放行，升级对这类授权没有影响。带绑定的授权在机器变化时有 14 天宽限期，见 运行配额与机器绑定。

回滚

注意：数据库迁移不可逆，换回旧 jar 并不会把表结构改回去。回滚到旧版本必须连同配置库一起还原。「备份恢复」页的恢复预检要求备份包与当前库迁移链一致，不适合作为跨版本回滚手段。

升级后检查清单

相关文档

• 备份与恢复
• 安装包与启动脚本
• 集群与高可用
• 授权与许可
• 更新日志