> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/advanced/migrations.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-6b19a6239745-cover.svg)
这一页解决一件事:给应用加表、加列、建索引、补数据时,脚本放哪、怎么打包、什么时候被执行、写错了怎么救。
一句话结论:脚本放插件的 migrations/,随应用包走,安装 / 升级时自动按文件名顺序执行; 平台不让你手工执行 SQL,也不让插件代码自己建表。
# 在插件仓库根目录运行(路径:wujies/wujies-plugins/)
# 本机已有 keys/private.pem 时会自动用它签名 —— 宿主是 enforce,不签名等于白打一个包
pwsh -File package.ps1 -Plugin wujies-hello
不想动 app.json、只想额外塞一个修数据脚本时,用 -MigrationPath 指向它 (package.ps1 的 .EXAMPLE 里有原样可抄的命令,四种情况的表格见 [打包与产物](/docs/wujies/1.x/package/build))。
服务器上唯一知道"这个应用有哪些表"的地方,就是这些脚本里的 CREATE TABLE —— 所以建表语句必须进包。
图床原本是宿主编译期模块,5 张表建在平台初始化 SQL 里。改成插件应用之后, 客户那台只导入平台 SQL 的部署装上它就是所有页面报表不存在; 而且"彻底删除"时平台也无从知道该删哪些表。
所以建表脚本有两个身份:① 安装时建表;② 卸载时被平台读出来当删表清单。
执行链路
| 环节 | 谁做 | 说明 |
|---|---|---|
| 打包 | package.ps1 | 默认取插件目录的 migrations/*.sql;-MigrationPath 可指定目录或单个文件 |
| 落位 | AppPackageDeployService | 解到 <pluginDir>/migrations/<appCode>/(落位前先清空该目录,见下) |
| 执行 | AppMigrationService.applyPending | 扫描该目录 → 按文件名排序 → 逐个执行 |
| 记账 | app_schema_history | 键 (app_code, script),含 checksum / success / execution_ms |
| 删表依据 | AppMigrationService.declaredTables | 从脚本里解析 CREATE TABLE 的表名,供"彻底删除"用 |
安装 / 升级的完整顺序(PluginAppInstaller):
产物落位 → 执行迁移脚本 → 加载新插件代码 → 同步菜单与授权
这个顺序是刻意做出来的:AppPackageDeployService.deploy(versionId, false) 只落位, 加载交给排在迁移之后的 assertBackendLoaded。所以插件在启动时机直接读新加的列是安全的。
控制台「部署」按钮走的是单参版本(落位即加载),它不跑迁移脚本 —— 只改表结构、不改代码时才用它。
脚本放哪、怎么命名
wujies/wujies-plugins/wujies-<app>/migrations/
01-create-<app>-tables.sql 建表,纯 DDL(CREATE TABLE IF NOT EXISTS)
0N-create-<app>-seed-data.sql 示例 / 必需基础数据(INSERT IGNORE + 显式主键)
0N-create-<app>-dictionaries.sql 字典(MAX(dict_id)+N + WHERE NOT EXISTS)
0N-create-<app>-website-config.sql 站点配置(MAX(config_id)+N + WHERE NOT EXISTS)
- 文件名排序即执行顺序,所以必须有
01-/02-这样的数字前缀; - 编号只表示顺序,取下一个空号,别为了整齐重排既有脚本;
.sql必须是该目录的顶层文件:打包只扫顶层,子目录里的脚本会被告警跳过;- 脚本以 UTF-8 读取(
AppMigrationService.read显式用StandardCharsets.UTF_8)。
范例应用 wujies-hello 就是这四个文件的最小样本: 01-create-hello-tables.sql(一张表:业务列 + tenant_id + BaseEntity 的公共列 + del_flag)、 02-create-hello-seed-data.sql(两条示例数据)、 03-create-hello-website-config.sql(sys_config,config_category = 'hello')。 字典与站点配置的取值策略、生成工具见 [种子数据与站点配置](/docs/wujies/1.x/plugin-dev/advanced/seed-data)。
本页只讲迁移,但新表往往要配实体与 Mapper。别去找 *-api 契约模块 —— 平台里没有这个模块(wujies-modules/*-api 数量为 0)。 实体 / BO / VO / Mapper 接口 与 Mapper XML / Service / controller 全在 wujies-plugins/wujies-<app>/src/ 下,例如 wujies-gallery/src/main/resources/mapper/gallery/GalleryImageMapper.xml。 XML 由 PluginMapperRegistrar 在插件加载时动态注册,不是靠 mapperLocations 扫出来的。
四条硬规矩 + 一条表结构约束
这五条都能在 AppMigrationService 的类注释里找到完整推导。
### 1. 只做 up,不回滚
app.json 的 migrations(含 down)是预留字段,当前不参与执行。 要回退表结构,请自己写一个"反向"的新迁移脚本,当作一次正常变更发布。
### 2. 脚本必须幂等
MySQL 的 DDL 是隐式提交的,AppMigrationService 刻意不声明事务 —— 包一个大事务只会让人误以为失败能整体回滚。重试时已成功的会跳过, 失败的那个必须能重跑。
CREATE TABLE IF NOT EXISTS `hello_item` (
id bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
name varchar(64) NOT NULL COMMENT '名称',
remark varchar(255) DEFAULT NULL COMMENT '备注',
create_dept bigint DEFAULT NULL COMMENT '创建部门',
create_by bigint DEFAULT NULL COMMENT '创建者',
create_time datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
update_by bigint DEFAULT NULL COMMENT '更新者',
update_time datetime DEFAULT NULL COMMENT '更新时间',
tenant_id varchar(20) DEFAULT '000000' COMMENT '租户编号',
del_flag int DEFAULT 0 COMMENT '删除标志',
PRIMARY KEY (id),
-- `KEY` 这种行内索引写法 MySQL 与沙箱的 H2 (MODE=MySQL) 都认
KEY idx_hello_item_tenant (tenant_id)
);
失败时会写一条 success='0' 的记录并中断安装;人工处理后重试, 已成功的脚本会被跳过、失败的那条(脚本多半已修正)复用同一行重跑。
加列前要用 information_schema 判断,再动态执行。
### 3. 已执行过的脚本内容不能改
账本判据是 (app_code, script),同一个 script 名再来时比对 checksum, 不一致直接报错拒绝执行:
迁移脚本 <name> 的内容已被修改(摘要与首次执行时不一致),
为避免同一脚本产生两种结果,拒绝执行。请改用新的脚本名。
要变更就新增一个脚本。这是刻意的保护,不要绕过它: 01 让全新安装走到某个状态,02 让存量部署补齐到同一状态。
工作区是 CRLF、Linux 上是 LF,语义相同但摘要不同。 AppMigrationService.checksumMatches 同时认 LF 归一化摘要与 CRLF 摘要 (记账统一存 LF 归一化那份),真正的改动照旧拒绝。
*
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-6b19a6239745-guide.svg)


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