升级与回滚

这一篇是干什么的：把系统从旧版本换成新版本；万一新版本有问题，退回旧版本。

先记住一句话：升级前系统会自动做一次完整备份。真出问题，还能退回来。

升级前先知道三件事

1. 升级会替换程序，还会自动调整数据库表结构（叫"数据库迁移"——给数据库的表加字段、加表，不会清掉数据）。
2. 升级和回滚都不会删除或重建数据卷。客户数据、缓存、上传的文件都保留。
3. 升级过程会自动生成一份备份，放在 backups/ 下，名字以 upgrade- 开头。

在线升级

./scripts/upgrade.sh 1.2.0

把 1.2.0 换成新版本号。脚本自动做这几件事：

1. 先做一次完整数据备份
2. 记下当前版本的配置
3. 拉新代码、构建新镜像
4. 跑数据库迁移
5. 启动新版本，等自检（/readyz）通过

升级成功：最后会打印 upgrade completed: 新版本号。

升级失败：脚本自动把程序退回升级前的版本，并恢复升级前的备份。屏幕上会打印恢复结果。

离线升级

服务器不能上网时：

1. 先把新版本的镜像包导入服务器（发行方提供新版本的 images.tar）
2. 执行：

./scripts/upgrade.sh 1.2.0 --offline

回滚（退回上一版）

./scripts/rollback.sh

它只做一件事：把程序换回上一版镜像。

数据库、缓存、上传的文件都不动。

两个绝对不能碰的东西

• docker compose down -v：这个命令的 -v 会把数据卷一起删掉，客户数据全部消失。任何情况下都不要敲。
• 手动改数据库：直接改表会让系统状态对不上。要退数据，走备份与恢复。

什么时候"回滚"不够，要用"恢复备份"

回滚只换程序，不换数据。

如果新版本已经改过数据库结构，而你要退回到旧的结构，就要用备份恢复。恢复前想清楚：

• 恢复备份 = 数据回到备份那一刻，备份之后新产生的数据会丢。
• 所以恢复前，先给"现在"再备份一份。

出错了怎么办

现象	什么意思	怎么办
升级卡在健康检查	新版本起不来	等脚本自动恢复；没恢复成功，按屏幕提示的备份目录手动恢复
屏幕显示 upgrade failed; restoring the pre-upgrade backup	脚本正在自动回退	等它跑完，把屏幕内容留存，联系技术支持
回滚提示 no previous release record	没有上一版记录	说明还没升级过，无需回滚
升级后页面打不开	浏览器缓存问题	先刷新、清缓存；还不行看日常巡检

常见问题

Q：升级要停服务多久？

一般几分钟。脚本会尽量缩短停机时间。

Q：多久升级一次？

看发行方的版本通知。有安全更新时建议尽快安排。

Q：什么时间升级比较好？

业务低峰期，比如晚上或周末。升级前手动再跑一次 ./scripts/backup.sh 也不嫌多。

Q：升级前要通知谁？

通知用系统的同事，尤其是常用群发的运营同事，避开他们正在发消息的时间。

相关页面

• 备份与恢复 — 升级自动备份，恢复用这篇
• 离线安装（不能联网的服务器） — 离线环境的来龙去脉
• 日常巡检与故障处理 — 升级后有问题怎么查
• 密钥与安全边界 — 升级和密钥的关系