升级
校对日期:2026-11-16。适用于社区版及全部商业版。
升级只需要换上新版本的程序:启动时程序自动判断数据库的版本并升级表结构,不需要手动执行升级脚本。 要保留的是配置、上传文件和前台模板。
一、升级之前
- 备份数据库和整个部署目录。
- 阅读
CHANGELOG.md中新旧版本之间的全部条目,留意标有!的破坏性变更及其要求的额外操作。 - 看安装包的
upgrade/目录里有没有对应版本的 SQL 脚本。文件名带before的在升级前对数据库执行,带after的在升级后执行。 - 曾经关闭过表结构自动升级(
spring.等)的,先重新开启,否则表结构不会升级。liquibase. enabled: false
二、Jar 部署的升级
停止程序。
删除旧的
ujcms-x.x.x.jar,换成新版本的 jar;用新版本的static/cp/整个替换旧目录。其余文件保留:
文件 / 目录 处理 config/application. yaml 保留,并对照新版本的同名文件补上新增的配置项 static/uploads/保留(上传的文件) static/themes/保留(前台模板,在后台对模板的修改也保存在这里)。要用新版本的默认主题时,自行对比合并 static/WEB-INF/保留。其中全文索引 lucene/可以删除,之后在后台 系统 → 生成管理 中重建启动程序。
三、Tomcat 部署的升级
停止 Tomcat。
把旧的
webapps/ROOT移出webapps/作为备份,再把新版本的ROOT拷贝进去;同时删除tomcat/缓存目录(如果存在)。work/ Catalina/ localhost/ ROOT 从旧目录复制回以下内容:
目录 内容 uploads/上传的文件 themes/前台模板(在后台对模板的修改也保存在这里)。要用新版本的默认主题时,自行对比合并 WEB-INF/lucene/全文索引。也可以不复制,之后在后台 系统 → 生成管理 中重建 WEB-INF/backup/备份文件 重新填写
WEB-INF/中的数据库连接等配置。以新版本的文件为基础修改,不要用旧文件直接覆盖: 新版本可能新增了配置项。classes/ application. yaml 启动 Tomcat。
四、Docker 部署的升级
换用新版本的镜像后重新创建容器即可,数据在挂载的卷里。主题模板不会随镜像自动更新, 见 Docker 部署的“主题随镜像更新”一节。
五、跨版本升级的注意事项
大多数版本之间按上面的步骤升级即可。下面两种跨版本升级还需要额外的操作,Jar、Tomcat、Docker 部署都适用。
从 12.x 及更早版本升级
13.0 把 ujcms_config 的各 *_settings_ 列、ujcms_user 的 mobile_ / email_、ujcms_ 的联系方式列改为大文本,ujcms_ 改存裸主题名。变更日志按"表里有没有数据"自动选路:空库删列重建,有数据的库逐列搬移、 保全存量值(13.2.1 及更早的 13.x 没有这条升级路径,会清空上述列,从 12.x 升级请直接用本版本)。升级前备份数据库与 WEB_ROOT。升级后:
- 用户手机号、邮箱仍是明文且盲索引为空,按手机号 / 邮箱登录、找回密码、查重找不到老用户,须以超级管理员调用
POST /回填一次(见 用户个人信息盲索引重建)。api/ backend/ core/ user/ rebuild-pii-index - 主题目录由
templates/改为{站点ID}/ {主题} themes/,并采用结构化布局:页面模板放{站点ID}/ {主题} templates/、静态资源放assets/并以${assets}引用(原${files})、栏目 / 文章 / 专题的alias改为slug([@Channel slug=),'…'] templates/error改为themes/error。程序不迁移主题文件:自定义主题须按主题开发手工移植后放到新目录,再启动新版本; Docker 的UJCMS_只覆盖镜像内置主题,对自定义主题勿开。THEME_ SYNC - 「全局设置 › 模板存储」的路径 / URL 由变更日志从 12.x 默认值
/templates改为/themes(${assets}与控制台模板管理都按它定位); 改过默认值的部署(如 URL 指向 CDN 域名)不动,须自行核对。升级后在控制台重新生成全部静态页(存量静态页仍引用旧的templates/资源),确认无误再删除旧的{站点ID}/ {主题}/ _ files/ templates/目录。
从 13.1.x 升级
把 spring.(Docker 为 UJCMS_DB_URL;未设置它的部署无需改动)里的 jdbc:mysql:// 改为 jdbc:mariadb://,spring. 删掉或改为 org.(Docker 的 UJCMS_DB_DRIVER 同理); 原来的 serverTimezone、characterEncoding、nullCatalogMeansCurrent 等参数不再需要,留着也会被忽略,useSSL=true 一类改为 sslMode=trust。数据迁移的源数据库类型 mariadb 并入 mysql(界面显示为 "MySQL / MariaDB")。 各发行包附带 NOTICE、licenses/ 与 bom.json(软件物料清单),jar / war 内的 META-INF/ 列出全部 Java 依赖及其许可证,控制台目录 cp/THIRD-PARTY-LICENSES. 列出前端依赖。
六、常见问题
- 升级后启动报
Could not acquire change log lock。 上一次启动在升级表结构时被强行中断。清空数据库中databasechangeloglock和flw_两张表的数据(注意不是ev_ databasechangeloglock databasechangelog)后重新启动。 - 只迁移表结构、不迁移数据可以吗? 不可以。表结构和数据必须一起迁移,否则程序会重复建表而报错。 只想要一个空的新库时什么都不用迁移:程序连接到空数据库时会自动建表并写入初始数据。