部署更新指南
SpringOpen 当前处于 V1.0 前开发阶段，只维护当前版本的代码、配置和数据库基线，不提供 V0.x 之间的原地升级或公共 jar 二进制兼容方案。API contract 规则见 API Contract 治理。
更新前检查
| 检查项 | 说明 |
|---|---|
| 版本号 | Maven revision、镜像 tag、发布说明和 Git tag 一致 |
| 数据库 | 当前环境使用干净数据库初始化；不要复用旧开发基线 |
| 配置 | 对比 .env、application.yml 和数据库配置，补齐当前配置 |
| 前端 | Admin / App / PC / Install / Docs 与当前后端一起构建和发布 |
| Contract | 后端、前端、OpenAPI、权限、i18n 和正式文档保持一致 |
| 依赖 | JDK、Spring Boot、Node.js 和外部基础设施满足当前基线 |
| 部署 | Nginx、Docker、WebSocket 代理和静态资源路径匹配当前版本 |
当前部署流程
- 停止写入流量或进入维护窗口。
- 备份需要保留的业务数据和
storage/持久化文件。 - 拉取当前代码或镜像。
- 准备符合当前 schema 的干净数据库。
- 对比并补齐当前环境变量和配置。
- 启动应用，让 Liquibase 执行当前全量基线。
- 再次启动应用，确认 Liquibase 二次执行幂等。
- 检查健康状态、后台登录、权限菜单、核心 API 和前端入口。
- 验证通过后恢复流量。
旧开发数据如确需保留，应按当前 schema 显式导出、转换和导入，不在应用源码或 Liquibase 中保留历史兼容分支。
Docker 更新
bash
docker compose pull
docker compose up -d持久化目录：
| 目录 | 作用 |
|---|---|
storage/ | 私有文件、运行日志、缓存和安装状态 |
public/ | 对外静态文件 |
docker/data/ | Docker Compose 依赖服务数据 |
不要把 storage/ 当作临时目录清理。只有开发者明确要重置本地开发数据库时，才执行：
bash
./scripts/docker db-reset --yes该命令会删除并重建目标开发数据库，执行前必须确认容器和数据库名称。
数据库基线
- Liquibase changelog 由应用启动自动执行。
- schema 和 seed 按 owning module 分文件维护。
- 开发期直接维护当前基线，不保留旧表、旧列、旧 checksum、旧 author 对齐脚本或跳过式 precondition。
- 发布前运行
./.ai/scripts/check migrations和./scripts/release migration-freeze。 - 使用干净数据库完成首次启动，再次启动确认 changeSet 数量不变且无重复记录。
- 禁止通过
clear-checksums、篡改database_changelog或兼容 SQL 掩盖当前基线错误。
配置更新
配置优先级：
- 数据库配置。
.env/ 环境变量。application.yml/ profile 配置。- starter 默认值。
运行期可变配置统一通过 ConfigManager / ConfigResolver 读取；静态启动配置只用于基础设施装配。删除或重命名配置时同步更新代码、配置 schema、环境变量样例和正式文档，不保留旧配置别名。
前端更新
- Admin / App / PC 必须与当前后端 contract 同步发布。
- 静态站点部署到子路径时使用项目既有相对路径配置。
- 文档站构建产物默认输出到
public/docs/。 - 后端接口变化必须同步 API client、TypeScript 类型、页面路由和 i18n。
回滚
当前版本发生部署故障时：
- 保留日志、TraceId 和错误截图。
- 停止故障版本。
- 恢复部署前数据库与
storage/备份。 - 恢复上一份完整可运行镜像及其配套配置和前端产物。
- 重新启动并验证核心链路。
回滚单位是“应用 + 数据库 + 配置 + 前端”的完整快照，不依赖当前代码兼容旧数据库。
发布后验证
/actuator/health返回UP。- 后台登录、权限和菜单加载正常。
- API 文档可访问。
- WebSocket 能鉴权并收发消息。
- 文件上传、公开访问和私有下载正常。
- Queue、Scheduler、通知、短信、邮件等运维页无异常。
- Admin、App、PC、Install 和 Docs 无资源 404、空白页或未翻译 key。