中国 帮助

升级与补丁

已在运行的部署升版本时,平台自身与应用两条线各要执行什么、表结构由谁负责、失败了怎么退回去。

升级与补丁
封面

> 本文整理自平台文档 docs/wujies/5.x/deploy/upgrade.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-223f081df6be-cover.svg)

升级有两条互不相干的线:平台(宿主)自己的版本,和应用(插件)的版本。两条线各有产物、各有表结构、各有回滚路径,谁也不触发谁:升应用不改平台表,升平台不碰应用表。分得开的依据是仓库边界(见[仓库与目录结构](/docs/wujies/5.x/platform/architecture/repo-layout)):实体 / BO / VO / Mapper 接口与 XML / Service / controller / listener / task / app.json / migrations 全在插件仓 plugins/wujies-<app>-plugin/ 下,平台对 cn.wujies.<app>.* 的 Java 引用为 0。升级一个应用不需要动平台一行代码,不需要重建宿主 jar,也不需要重启 JVM。

动手前先确认两件事。第一,app-market.deploy.plugin-dir 与 frontend-dir 两个路径按进程工作目录解析(Paths.get(...).toAbsolutePath()),不是相对仓库根;换启动目录后先看启动日志那两行 [deploy] plugin-dir = <绝对路径> 与 [deploy] frontend-dir = <绝对路径>,猜目录的后果是产物落进另一块磁盘,表现是「升级任务成功、点进去是远程视图不可用」。第二,库归你管:平台表结构靠手工执行 script/sql/update/ 里的补丁脚本,应用表结构靠包内 migrations/*.sql 在升级时自动执行,两边不会互相触发。

两条线各自要做什么

平台(宿主)应用(插件)
产物wujies-admin.jar + 前端 dist + 平台 SQL应用包(后端 jar + 前端产物 + migrations/)
表结构手工执行 script/sql/update/ 补丁自动执行包内 migrations/*.sql
怎么生效换 jar / 重建镜像后重启落位 → 迁移 → 热加载,不重启 JVM
失败影响面应用起不来 / 接口 500单个应用的升级任务失败,平台不受影响

读这张表要带着的问题是「这次发布动的是哪一行」:只动应用产物就在页面上点升级,动到平台表结构就得手工跑补丁,两边都动则两条都做一遍。

一、平台线

### 换产物:改动类型决定要不要重建镜像

三条路线的命令见[后端部署](/docs/wujies/5.x/deploy/backend),这里只留升级时的判断。

  • 主机直跑 jar:先停正在跑的实例。运行中的 JVM 锁着 wujies-admin.jar,mvn install 写目标文件会失败;构建与启动的工作目录都得是 wujies-platform/。
  • 1Panel / 镜像:sql/files/*.sql、data.yml、docker-compose.yml 是包里的文件,换文件即可;jar、前端 dist/、entrypoint.sh 打进镜像,必须 docker build,标签要和 compose 里的 image: 一致。
  • 改版本号的地方:包侧四处(build-1panel.ps1 的 $Version、包内 5.6.x/ 目录名、compose 镜像 tag、gen-appstore-data.mjs 的 VERSION)与宿主自身三处(pom.xml 的 <revision>、AppMarketConstants.PLATFORM_VERSION、中心那条版本行的 version)必须是同一个数,当前口径是 5.6.2。漏一处的表现是「面板装的是新包、拉的是旧镜像」,或在线更新页面比对出两个不同的号。
  • 已装实例换镜像不等于换 SQL:入口脚本只在库里没有 sys_config 的 platform.init.version 标记行时导入 /app/sql/files/*.sql,而 SQL 是 bind mount、换文件不用重建镜像,标记行还在就照样跳过。只改数据(种子、字典、参数)时删标记行 + 重启容器,包内脚本本身幂等;改了表结构时 IF NOT EXISTS 不会动已有表,清表会丢数据,有真实业务数据的部署走下面那节手工执行补丁。别 DROP DATABASE:面板只授权到那一个库,库删了建不回来。

### 表结构:手工跑 script/sql/update/ 里的补丁

安装包只有 01-platform.sql + 02-app-market.sql 两层,全新部署一步到位,这个目录是留给存量库按需补的:一个功能一个文件、幂等、只动自己的行,头部写了背景与手工回滚方式。

脚本补什么
appmarket_catalog_config.sqlappmarket.catalogBaseUrl / catalogToken 两个参数行
oss_folder.sqlOSS 目录表
menu_scope_and_console_access.sqlmenu_scope / role_scope 列与 system:console:access 权限点
pay_seed_secret_repair.sqlpay 种子脚本脱敏后的迁移账本修复
app_license.sqlapp_license 表与「授权管理」菜单
host_update_menu.sql「系统更新」菜单与 app:host:update 权限点

跑之前先对账,缺表 / 缺列一次报全,别等启动失败再逐张补:把 information_schema 的列清单导成 TSV,跑 node wujies-platform\deploy\tools\platform-schema-gap.mjs --live <导出文件>,加 --write 会生成 platform_align_columns.sql 与 platform_align_collation.sql;platform_config_site.sql 由 gen-app-seed-sql.mjs 生成。这三份都是生成物,仓库里默认没有,别手改也不进安装包。

2026-10-26 的 d0cc5cd90 把 update/ 里那批一次性脚本连同 script/sql/README.md 删净了(判据:全新部署由 platform_init.sql 一步到位,存量按需手工补)。要读原样内容用 git show d0cc5cd90^:script/sql/update/<脚本名>.sql;其中随包走的 9 段已逐字并进 script/sql/app_market_schema.sql,新装不用手工跑。之后新加的补丁就往这个目录放。

### 后台「系统管理 → 系统更新」(只有 jar 直跑能用)

它换的正是正在运行的这个 jar:点下去这个服务必然下线,新实例起来之前没人能点回滚,所以换文件与拉起新实例交给外层 apply-script(deploy/host/apply-update.sh / .ps1:备份 → 结束当前实例 → 换文件 → 用原命令在原工作目录拉起,输出进 <staging-dir>/apply.log)。这条路线刻意做成只有人能触发:没有定时检查、没有自动应用,还要把目标版本号原样再敲一遍。

键(前缀 app-market.host-update.)默认值什么时候会踩
staging-dirhost-update(WUJIES_HOST_UPDATE_DIR,相对工作目录)待生效产物、host-update.json、backup/、apply.log 都在这,磁盘位置不合适就改
current-jar空(WUJIES_HOST_JAR)留空时检查与下载照常用,「更新并重启」当场被拒;IDEA 里直跑 target/classes 没有可替换的产物,就该留空。指错文件等于把别的产物装上生产机,用 ps -eo pid,args(Windows 用 Get-CimInstance Win32_Process)看 -jar 后面那串
apply-script空(WUJIES_HOST_APPLY_SCRIPT)脚本只认 --jar / --target / --backup-dir。systemd / NSSM / 计划任务托管的实例留空:控制器会拿旧文件立刻拉起实例,和刚换上的打架
max-package-mb1024宿主 fat jar 连前端产物上百 MB(实测约 224MB),下载走流式写盘,不能沿用应用包那个 200MB 上限(PluginDevInstallService.MAX_PACKAGE_BYTES),否则下载或解压阶段就报超限

另两个前提:本部署有中心地址(sys_config 的 appmarket.catalogBaseUrl 优先,环境变量 APP_MARKET_CATALOG_BASE_URL 兜底),且中心登记并发布了 `a

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-223f081df6be-guide.svg)

章节导览
THE END

喜欢就支持以下吧

评论区需要浏览器启用 JavaScript 才能加载。

回到内容