在线与手动升级

升级会更新什么

矩阵盘正式发行采用内嵌单二进制：主程序、公开前台、Vben 管理后台和配套数据库迁移属于同一次发行。在线升级和手动升级使用同版签名 ZIP，不需要另外上传前端目录。

升级前准备

在安装目录执行：

./backup.sh

确认备份完成并保存校验文件。然后检查：

• 当前没有正在运行或等待写入的重要任务；
• 磁盘能容纳下载包、解压文件、旧程序和备份；
• 当前版本、平台和 CPU 架构显示正确；
• 已阅读目标版本说明、兼容要求和已知限制；
• 你知道程序恢复与数据库恢复是两件事。

在线升级

1. 点击“检查更新”；
2. 阅读目标版本、更新摘要和平台信息；
3. 点击“安装更新”并确认影响；
4. 等待下载、大小与 SHA-256 校验、签名校验、替换和重启；
5. 页面断开时不要立即重复点击，等待服务恢复；
6. 重新打开后台，确认运行版本和界面构建已经切到目标版本。

在线检查失败时可以使用官方签名包手动升级，但不要使用第三方重新打包文件。

手动升级

1. 下载与产品、平台和 CPU 架构一致的 juzhenpan_linux_*.zip；
2. 在程序升级页选择文件；
3. 阅读页面对“上传并安装”的真实说明；
4. 确认安装；
5. 等待校验、替换、重启和就绪检查。

系统会检查产品、版本、操作系统、架构、程序 SHA-256 与 Ed25519 签名，并拒绝同版本覆盖和降级。

升级后验收

• /healthz 返回正常；
• 后台显示的运行版本等于目标版本；
• 前台、后台资源属于同一构建；
• 管理员登录、搜索、资源详情、任务和日志正常；
• 软件授权、实例 ID、站点配置和上传文件仍在；
• 数据库迁移没有错误。

只有程序、前台、后台和就绪状态都确认后，才能认为升级完成。

新程序无法启动

官方安装包提供程序恢复脚本：

JUZHENPAN_UPGRADE_RECOVERY_CONFIRM=RESTORE_PREVIOUS ./recover-upgrade.sh

它会恢复安装器保留的上一版程序和版本记录，并保留失败程序用于诊断。该操作不会回滚数据库。如果新版本执行了与旧程序不兼容的迁移，还必须按升级前备份恢复数据库和相关文件。

不要通过修改版本文件、绕过签名或强行安装低版本处理失败。完整数据流程见备份与恢复。