升级与补丁

升级这件事有两条互不相干的线：平台（宿主）自身的版本，和应用（插件）的版本。两者不会互相触发 —— 升应用不会改平台表，升平台也不会碰应用表。本页解决三个具体问题：改了什么要敲哪条命令、已经装着的实例怎么让改动生效、迁移脚本在这两条线里的位置。

前提是平台与插件仓库的边界（见 /design/repo-layout）：平台里没有 *-api 契约模块，实体 / BO / VO / Mapper 接口与 Mapper XML / Service / controller / listener / task / app.json / migrations 全在插件仓库 wujies/wujies-plugins/wujies-<app>/ 下，平台对 cn.wujies.<app>.* 的 Java 引用为 0。所以升级一个应用不需要动平台一行，这也是两条线能彻底分开的原因。

两条升级线复制标题链接

平台升级复制标题链接

路线一：jar 直跑复制标题链接

先停掉正在跑的实例 —— 运行中的 JVM 会锁住 jar，mvn install 写目标文件会失败。

# 1) 存量库补结构：只跑这次发布需要的脚本（全新库跳过，见下面的「补丁脚本从哪来」）
mysql -h <host> -u <user> -p <db> < script/sql/update/app_market_schema_history_fix.sql

# 2) 重新打包
$env:JAVA_HOME = "C:\Users\<you>\.jdks\corretto-23.0.2"
$mvn = "C:\Program Files\JetBrains\IntelliJ IDEA 2025.3.3\plugins\maven\lib\maven3\bin\mvn.cmd"
& $mvn -pl wujies-admin -am -B install -DskipTests

# 3) 启动（脚本会先清掉上一版残留的插件 jar，再启动）
powershell -NoProfile -ExecutionPolicy Bypass -File script\prune\start-host.ps1 -Build

• -Build 可以省掉（第 2 步已手工打包过）；
• script\prune\start-host.ps1 先跑同目录的 prune-plugins.ps1 是有顺序讲究的：-Dloader.path 只加载目录根下的 jar，同 appCode 两个版本同时在位会撞重复的 mapper XML。现在启动瞬间的 loader.path 与运行期一样按 active-plugins.txt 过滤，残留 jar 不再致命，但清理仍然是推荐动作（且 Windows 上被占用的 jar 只能停服务后清）；
• 全部启动参数见 /deploy/backend。

路线二：1Panel 应用包（什么时候要重建镜像）复制标题链接

包的构成决定了「哪类改动要重建镜像」：SQL / data.yml / compose 是包里的文件，jar 与前端 dist/ 是打进镜像的。

# 只改 SQL / data.yml / compose（几十秒，不重建镜像）
powershell -ExecutionPolicy Bypass -File wujies-platform\deploy\tools\build-1panel.ps1 -SkipFrontend -SkipBackend

# 只改了后端 Java
powershell -ExecutionPolicy Bypass -File wujies-platform\deploy\tools\build-1panel.ps1 -SkipFrontend

# 全量（前端 vite build --mode docker + 后端 mvn install + 组装 + tar.gz）
powershell -ExecutionPolicy Bypass -File wujies-platform\deploy\tools\build-1panel.ps1

主机侧（只有镜像变了才需要 docker build，标签必须与 compose 里的 image: 一致）：

tar -xzf wujies-platform-1panel-5.6.3.tar.gz -C /root/pkg

cd /root/pkg/docker/backend  && docker build -t wujies-platform/backend:5.6.3 .
cd ../frontend               && docker build -t wujies-platform/frontend:5.6.3 .
cd ../snailjob               && docker build -t wujies-platform/snailjob-server:5.6.3 .
cd ../monitor                && docker build -t wujies-platform/monitor-admin:5.6.3 .

# 应用包同步进面板（走 tar 解包，别用 scp 直传资源目录）
cp -r /root/pkg/apps/* /opt/1panel/resource/apps/local/
chmod -R a+rX /opt/1panel/resource/apps/local/wujies-platform-*
# 然后：面板 → 应用商店 → 本地应用 → 同步

• ⚠️ 改版本号要同时动四处：build-1panel.ps1 的 $Version、包内 5.6.x/ 目录名、compose 里的镜像 tag、gen-appstore-data.mjs 的 VERSION。漏一处就是「面板装的是新包、拉的是旧镜像」。
• ⚠️ build-1panel.ps1 必须保持 UTF-8 with BOM；*.sh 会被脚本统一成 LF（CRLF 的 shell 脚本在容器里报 bad interpreter）。理由与修复片段见 /deploy/backend。
• ⚠️ 用 scp 直接传进 /opt/1panel/resource/apps/local/ 会建出 0700 目录，容器里的非 root 用户读不到挂载文件；走 tar 解包不会踩。
• 中间件（MySQL / Redis / RabbitMQ）与对象存储都不在包里，由面板的官方应用或外部实例提供，所以升级平台不需要动它们。

已装实例：换镜像 ≠ 换 SQL复制标题链接

后端容器的入口脚本只在库里没有 sys_config.platform.init.version 这一行时导入 /app/sql/files/*.sql（该目录由 compose 的 ./sql:/app/sql:ro 从实例目录挂进来）。也就是说：

• SQL 是 bind mount，换文件不用重建镜像；
• 但标记行在，导入照样会跳过 —— 换完镜像、docker compose up -d 之后，新 SQL 不会被重跑。

# 只改数据：删标记 + 重启（脚本幂等，可重复执行）
docker exec <mysql容器> mysql -uroot -p<root密码> -e \
  "delete from \`wujies_xxxxxx\`.sys_config where config_key='platform.init.version'"
docker restart <backend容器>

平台补丁脚本从哪来、该跑哪些复制标题链接

• 这一堆 SQL 的权威地图在 script/sql/README.md（哪个权威、哪个只给存量库、哪个已归档），照它判断比照记忆猜安全。

• 升级前先对账，缺表 / 缺列一次报全：

  复制代码

  # 拿真实库的列清单（information_schema 导出成 TSV）与「包里会执行的所有 SQL」逐列比对
  node wujies-platform\deploy\tools\platform-schema-gap.mjs --live <导出文件>
  # 加 --write 会重新生成 platform_align_columns.sql / platform_align_collation.sql

• ⚠️ 生成物不要手改：platform_align_columns.sql / platform_align_collation.sql 由 platform-schema-gap.mjs 生成，platform_config_site.sql 由 gen-app-seed-sql.mjs 生成。要改内容就改生成器或加一条新的幂等脚本。

• ⚠️ 平台只支持 MySQL 8.x（排序规则通篇 utf8mb4_0900_ai_ci，MariaDB 没有这个排序规则）。

应用升级复制标题链接

升级链路：落位 → 迁移 → 加载 → 同步菜单复制标题链接

后端与前端两条产物、菜单与状态机细节见 /advanced/lifecycle。

接口（权限 app:install:edit，返回任务 ID；versionId 不传则升到最新已发布版本）：

curl.exe -X POST "http://<host>/app/install/<installId>/upgrade?versionId=<versionId>" \
  -H "Authorization: Bearer <token>"

上架一个新版本是升级的上游动作，见 /package/publish。

⚠️ 迁移脚本只在 install / upgrade 里跑复制标题链接

这是本页最容易被误解的一条，因为「把包传上去」和「控制台点部署」看起来都像在升级：

代码依据：迁移由安装器的 install() / upgrade() 在「落位之后、加载之前」调 applyPending；而控制台「部署」直接调的是只做「下载 → 校验 → 解包落位 → 热加载」的那条路径。

所以拿到新表结构 / 新种子数据的路径只有两条：发一个新版本再升级；或者彻底删除（purge=true）后重装 —— 后者会连数据表一起删，只在数据可丢时用。上架端只换包内容、不升版本号，存量部署不会有任何变化。

升级会强制重新落位复制标题链接

判据是 fromVersion != toVersion：「本机文件已存在就跳过」只在同版本重装 / 修复时成立。升级时若沿用旧产物，会同时踩两个静默坑 —— 前端还是旧版、migrations/ 根本不落位（表结构没变，但任务显示成功）。所以升级一律重新拉包落位，多一次下载换「前端、后端、表结构三者同版本」。

升级完成后怎么确认复制标题链接

• 任务中心（我的应用 → 应用任务）是排查第一站：看「执行版本迁移脚本」这一步里的 已执行: / 已执行过，跳过:，以及失败原因；用法见 /ops/task-center。
• 部署报告里有 hotLoaded=true 与 hotLoadNote（组件数 / 接口数）；纯前端应用没有后端产物可加载，任务日志会写明。
• 菜单行数不变（升级是幂等 upsert，不该多出菜单）。
• 远程应用入口带版本号查询串（GET /app/runtime/remote-apps 返回的 entry 形如 /remote-apps/<code>/index.js?v=<版本>），升级后浏览器缓存会自动失效；如果页面还是老样子，先核对这里而不是先怀疑后端。

迁移的四条硬规矩 + 一条表结构约束复制标题链接

第 3 条的 checksum 比对容忍 LF / CRLF 差异（记账统一存 LF 归一化摘要），真正的改动照旧拒绝。写脚本的完整规范见 /plugin-dev/advanced/migrations，种子数据的取名与生成见 /plugin-dev/advanced/seed-data。

两个必须先跑的修复脚本复制标题链接

Duplicate entry '000000-exam-1.0.1' for key 'app_schema_history.uk_schema_history'

存量部署的补数据脚本复制标题链接

script/sql/update/ 下的一次性脚本按用途分四类，全部幂等、可重复执行，脚本头部都写了背景与手工回滚方式。随包走的只有上一节列的那 7 个，其余都不进安装包（全新部署由 platform_init.sql 一步到位）—— 包里塞三十多个补丁只会让人不知道该跑哪些。

一、表结构修正类复制标题链接

二、菜单与归属修复类复制标题链接

三、清理重复类复制标题链接

四、平台表对齐类复制标题链接

给「用上游 SQL 起的存量库」补平台的表 / 列 / 数据，缺哪张会怎样写在脚本头部。

回滚能力复制标题链接

升级前的备份复制标题链接

升级前至少确认这几项的备份，丢失代价从高到低：

备份与恢复的完整步骤、密钥纪律见 /ops/backup-security。

相关阅读复制标题链接

• /deploy/backend —— 三条部署路线、镜像构建与启动参数
• /deploy/configuration —— 哪些配置是启动期读入的（改完必须重建宿主）
• /deploy/multi-deployment —— 目录集中时升级的目录侧变化
• /plugin-dev/advanced/migrations —— 迁移脚本的编写规范与自检清单
• /plugin-dev/advanced/seed-data —— 字典 / 站点配置 / 示例数据怎么随包发
• /ops/task-center —— 升级任务的分步日志怎么看
• /ops/troubleshooting —— 摘要不一致、撞唯一键、表不存在的排查路径
• /advanced/lifecycle —— 安装 / 升级 / 停用 / 卸载的状态机与卸载安全闸
• /package/publish —— 上架新版本（升级的上游动作）