SpringOpen
搜索 K

外观

升级指南 ​

升级指南用于规划从一个版本升级到另一个版本时的操作顺序。版本能力边界请看 版本发布，接口兼容规则请看 API 兼容策略。

升级前检查 ​

升级前建议先确认：

检查项说明
版本号Maven revision、镜像 tag、发布说明和 Git tag 是否一致
数据库备份数据库，确认 Liquibase changelog 未被手动改坏
配置对比 .env、application.yml 和数据库配置差异
前端确认 Admin / App / PC / Install / Docs 构建产物与后端接口版本匹配
API破坏性 REST 变更是否进入新版本路径，公共 starter / core jar 是否通过 api-compat 检查
依赖是否有安全漏洞依赖升级、JDK / Spring Boot 基线变化
部署Nginx、Docker、WebSocket 代理和静态资源路径是否仍匹配

标准升级流程 ​

推荐顺序：

  1. 停止写入流量或进入维护窗口。
  2. 备份数据库和 storage/ 中的持久化文件。
  3. 拉取新代码或新镜像。
  4. 对比环境变量和配置文件，补齐新增配置。
  5. 启动应用，让 Liquibase 自动执行新增迁移。
  6. 访问健康检查、登录后台、检查安装 / 系统运维页。
  7. 抽查核心 API、WebSocket、文件上传和前端静态页面。
  8. 确认无误后恢复流量。

Docker 升级 ​

Docker 场景建议：

bash
docker compose pull
docker compose up -d

如果使用一体化镜像，升级前必须确认挂载目录仍然指向持久化目录：

目录作用
storage/私有持久化文件、数据库文件、运行日志、缓存和安装锁
public/对外公开静态文件
docker/data/Docker Compose 依赖服务数据

不要把 storage/ 当作临时目录清理。

数据库迁移 ​

  • Liquibase changelog 由应用启动自动执行。
  • 禁止手工删除 database_changelog 或 database_changelog_lock。
  • 如果迁移失败，先保留现场日志，不要直接删除数据表。
  • 新增字段和新增表属于兼容迁移；删除字段、改字段含义、不可逆数据转换必须有单独升级说明。
  • V1.0 前做 Liquibase 基线冻结时，先运行 ./scripts/release migration-freeze 生成只读快照报告，和 ./.ai/scripts/check migrations、空库 / 二次幂等 smoke、升级 smoke 结果一起归档；报告只读取迁移文件，不修改 XML 或数据库。

旧版本升级 smoke ​

历史开发阶段曾重排初始化基线迁移，旧版本库直接升级时可能遇到 changeSet 身份、旧表已存在或当前基线新增列之间的差异。当前开发期改为保护已迁移文件，新增变更使用真实时间戳增量迁移，V1.0 发布前再单独做基线整理。不要只靠手工修改 database_changelog.author 处理旧库；Liquibase 使用 filename + id + author 识别 changeSet，基线重排后旧库差异通常不止 author。

升级前先用隔离环境执行版本升级 smoke：

bash
./scripts/docker upgrade-smoke --from-tag v0.6.0

该命令会：

  1. 使用 git archive 导出旧 tag 源码，不切换当前工作区。
  2. 使用独立 Docker MySQL / Redis、独立端口和临时数据目录，不触碰开发库。
  3. 启动旧版本应用初始化旧库。
  4. 生成只作用于 smoke 库的临时基线桥接 SQL，对齐旧表已存在、当前基线列缺失和 seed 幂等差异。
  5. 启动当前应用执行升级，再启动一次当前应用验证二次幂等。

通过标准：当前版本启动成功，第二次启动不新增 changeSet，database_changelog 无重复记录。该 smoke 只验证升级路径和迁移幂等，不会把旧兼容逻辑写回正式 Liquibase 基线。

本地开发库不再把“清库重来”作为常规处理方式；日常开发中已经执行过的迁移应保持稳定，后续变更走新增增量迁移。只有维护者明确要求重置开发数据、或 V1.0 基线整理 / 升级 smoke 需要全新库验证时，才按对应脚本或隔离环境处理。生产或共享环境必须先备份数据库，再用隔离库复现升级路径；不要通过删除 database_changelog、删除业务表或只刷新 checksum 来处理迁移失败。

旧开发库 changeSet author 对齐 ​

Liquibase 使用 filename + id + author 识别 changeSet。author 不是普通署名，已经执行过的 changeSet 如果只改 author，Liquibase 会把它当成一条新迁移重新执行，常见表现是启动时报“表已存在”或“唯一键已存在”。

处理顺序：

  1. 优先确认当前主迁移是否应保持旧身份稳定。已经发布或已经在开发库执行过的 changeSet，不应仅为了统一 author 而改动。
  2. 本地开发数据可丢弃时，直接重建本地库最干净，例如使用 ./scripts/docker db-reset --yes。
  3. 本地开发数据需要保留时，先备份数据库，再只更新确认过的 changelog 元数据，不删除 database_changelog。

排查命令：

sql
SELECT id, author, filename
FROM database_changelog
WHERE author <> 'system'
ORDER BY dateexecuted, orderexecuted;

如果维护者已经确认某批 changeSet 的 author 需要对齐，只更新精确命中的记录，并把目标值改成当前迁移 XML 中实际保留的 author：

sql
UPDATE database_changelog
SET author = '<当前迁移文件里的 author>'
WHERE author = '<旧开发库里记录的 author>'
  AND filename = '<db/changelog/migrations/...xml>'
  AND id IN ('<精确 changeSet id 1>', '<精确 changeSet id 2>');

这类 SQL 只用于已备份的开发库或隔离升级验证库。生产或共享环境应先通过 ./scripts/docker upgrade-smoke --from-tag <旧版本> 复现升级路径，再按具体版本说明执行。

API 兼容 smoke ​

升级前同时检查公共 jar API。优先用发布脚本生成上一版本与当前版本的兼容检查命令：

bash
./scripts/release api-compat --previous-version 0.7.0

脚本会按上一版本 tag 与当前工作区交集生成 starter / core 模块列表，并输出隔离 Maven 仓库的安装与 japicmp verify 命令。上一版本 jar 不在本地仓库时，也可以手工先把上一 tag 安装到隔离 Maven 仓库，再用当前源码执行 api-compat profile：

bash
API_COMPAT_ROOT="target/api-compat-$(date +%Y%m%d%H%M%S)"
API_COMPAT_REPO="$(pwd)/$API_COMPAT_ROOT/repository"
mkdir -p "$API_COMPAT_ROOT/v0.7.0"
git archive v0.7.0 | tar -x -C "$API_COMPAT_ROOT/v0.7.0"

(cd "$API_COMPAT_ROOT/v0.7.0" && \
  ./mvnw -pl spring-open-starters/spring-open-starter-common -am install \
    -DskipTests \
    -Dmaven.repo.local="$API_COMPAT_REPO")

./mvnw -pl spring-open-starters/spring-open-starter-common -am verify \
  -Papi-compat \
  -DskipTests \
  -Dapi.compat.previousVersion=0.7.0 \
  -Dmaven.repo.local="$API_COMPAT_REPO"

通过标准：japicmp 不报告二进制不兼容变更；若公开 API 必须破坏性调整，需要进入新主版本或在发布说明中给出迁移方案。

配置升级 ​

配置优先级遵循项目现有规则：

  1. 数据库配置。
  2. .env / 环境变量。
  3. application.yml / 环境配置文件。
  4. starter 默认值。

新增配置项优先写入正式文档。生产环境建议只把敏感信息和环境差异放到环境变量，其余配置放到配置文件或后台数据库配置。

前端升级 ​

前端源码在 views/，构建产物按模块输出到 public/ 或对应视图模块。升级时注意：

  • 后端 API 路径必须包含版本号。
  • 静态站点部署到子路径时应使用相对路径。
  • 文档站构建产物默认在 public/docs/。
  • Admin / App / PC 需要和后端接口 contract 同步发布。

回滚策略 ​

推荐回滚顺序：

  1. 保留失败版本日志和错误截图。
  2. 停止新版本服务。
  3. 回滚镜像或代码到上一版本。
  4. 恢复数据库备份；如果只执行了兼容新增迁移，可评估是否无需恢复。
  5. 恢复旧配置。
  6. 重新启动并验证核心链路。

如果升级涉及不可逆迁移，必须先准备专门回滚脚本和数据恢复方案。

发布后验证 ​

升级完成后至少检查：

  • /actuator/health 返回 UP。
  • 后台登录和菜单加载正常。
  • API 文档可访问。
  • WebSocket 能握手并收到消息。
  • 文件上传、公开访问和私有下载正常。
  • 队列、调度、通知、短信、邮件等运维页无异常。
  • 关键前端页面无资源 404。

Released under the Apache License 2.0.

Copyright © SpringOpen