升级与回滚

升级 Crest 前要把“能否成功升级”和“失败后如何退回”同时设计好。正式环境不建议在没有备份、没有验证、没有回滚方案的情况下直接替换版本。

升级不是单纯替换镜像或安装包。它可能涉及数据库迁移、前端资源变化、权限模型变化、内置示例变化和配置项变化。越是正式环境，越要把升级当成一次可回溯的变更处理。

升级后第一轮页面验证建议从工作台开始。工作台能正常打开，说明登录、菜单、基础资源统计和前端静态资源已经通过初步检查。

随后继续验证数据源、数据集、仪表盘、大屏、分享、导出和审计日志，不能只停留在“能登录”。

升级前检查

升级前建议把当前环境状态截图或记录下来：版本号、服务状态、数据库备份文件、当前镜像、配置文件、管理员登录结果和关键页面访问结果。这样升级后出现问题时，可以明确是升级引入还是升级前已存在。

推荐升级流程

升级过程中不要同时做无关配置变更。例如不要一边升级版本，一边改域名、SSO、数据库密码、加密模式或权限模型。多个变更叠加会让问题定位变得困难。

从旧版本升级到 v1.5.7 时，如果不需要国密能力，继续保持 CREST_CRYPTO_MODE=standard 即可；用户操作流程不需要调整。如果项目需要启用 sm-suite，应先在测试环境验证密钥、登录、数据源、数据集、仪表盘、大屏、分享、导出和 SSO，再安排生产维护窗口。

v1.5.7 的升级路径需要按来源版本区分：

v1.5.6 到 v1.5.7 是数据集缓存、公开分享、API 数据源和数据源校验维护版本，没有数据库结构、系统参数或初始化数据变更。v1.5.4 到 v1.5.5 会写入账号安全相关系统参数，必须执行对应升级 SQL。

升级当天建议准备一张操作记录表，按时间记录命令、输出、截图和结论。出现问题时，这张表比事后回忆更可靠。

升级后验证清单

升级到 v1.5.7 后，建议额外验证：

1. MySQL 数据源数据集可切换直连和缓存读取。
2. 缓存支持立即更新、定时更新、全量更新和增量更新。
3. 缓存状态能展示最近执行状态、缓存可用状态、源数据行数、缓存行数和一致性校验结果。
4. 已登录用户访问 /link/:uuid 仍进入分享展示页。
5. API 数据源启用 JsonPath 后能按指定节点解析字段。

验证时建议至少使用两个账号：管理员账号和普通业务账号。管理员能打开页面，不能证明普通用户的权限、菜单和资源均正常。

验证截图建议保留登录页、工作台、系统参数、一个数据源、一个数据集、一个仪表盘、一个大屏预览、导出中心和审计日志。截图不需要包含敏感数据，但要能证明关键链路已经访问过。

回滚策略

回滚不能只替换为旧版本安装包。如果升级过程执行了数据库迁移，必须同时考虑数据库结构和数据。

升级观察期

升级完成后的 24 到 72 小时，建议重点观察：

• 登录失败次数是否异常。
• 数据源连接是否出现超时。
• 图表查询是否明显变慢。
• 导出失败率是否上升。
• 后台任务是否积压。
• 日志中是否出现重复异常。
• 用户是否反馈页面空白、权限异常或资源丢失。

升级记录建议保存到运维台账，包括版本号、操作人、时间、命令、备份位置、验证结果和遗留问题。

升级沟通模板

正式环境升级前，可以提前向业务方说明：

升级完成后再发一次结果通知，说明版本、验证结果、已知问题和观察期安排。