快速开始

这一页只解决一件事：在开发机上从空库走到「装上第一个应用」，把数据库、后端宿主、插件运行时、前端、迁移与菜单这条链路走通。

读完之后你能回答下面这些问题：

本页不讲：怎么写一个应用（见 应用清单、必须遵守的不变量）、怎么打包上架（见 发布应用包）、生产部署（见 在部署里使用应用、升级）。

1. 先认清楚三个仓库复制标题链接

三个仓库没有共同的 git 根，各自提交、各自分支。

后端模块地图复制标题链接

有三样东西不存在，别去找：

• 平台里没有任何给应用准备的契约模块。wujies-modules/ 下只有上表那几个，平台对 cn.wujies.<app>.* 的 Java 引用数量是 0。契约随插件走。
• 没有 wujies-job / wujies-generator / wujies-demo 模块（已删除）。定时任务随应用走，宿主只提供 wujies-common-job。
• 平台仓库里没有 plugins/ 目录。插件本体在另一个仓库。

应用长什么样复制标题链接

每个应用是 wujies-plugins/wujies-<app>/ 下一个自包含工程，契约与实现同处一室：

wujies-plugins/wujies-gallery/
├── app.json                       清单：code / version / assets / menus
├── pom.xml                        平台依赖一律 provided
├── migrations/01-create-gallery-tables.sql
└── src/main/
    ├── java/cn/wujies/gallery/{domain,domain/bo,domain/vo,mapper,service,service/impl,controller,open,listener}
    └── resources/mapper/gallery/*.xml     ← Mapper XML 在插件里，随 jar 走

• 实体 / BO / VO / Mapper 接口 / Mapper XML / Service 接口与实现 / controller / open / listener / task 全在插件模块自己的 src/ 下；
• Mapper XML 由 PluginMapperRegistrar 在插件加载时动态注册进宿主的 SqlSessionFactory，不是靠宿主扫 mapperLocations；
• 插件之间要对方的契约时，依赖兄弟插件构件（同样 provided）。

应用有两种形态，都不奇怪：

2. 建库：按这个顺序导 SQL复制标题链接

全新部署只认平台自己的初始化脚本。应用自己的表不在这里，它们随应用包走。

第 ② 步的清单与顺序（不是"按文件名排序"，是这份固定清单）：

app_market.sql                     应用市场核心表（app_info / app_version / app_install / app_schema_history …）
app_market_app_model.sql           install_mode / audience 列
fix_app_version_unique_index.sql   UNIQUE(app_id, version_active)
app_market_home_path.sql           home_path 列
app_market_sync_icon.sql           app_info.icon 跟随菜单表
app_market_schema_history_fix.sql  迁移账本唯一键 (app_code, script)
app_market_register_modules.sql    把平台自带模块登记成应用

依据是 deploy/tools/build-1panel.ps1 里的 $appMarketScripts 数组与 script/sql/README.md 第四节 —— 这也是安装包实际导入的那 7 个。

• script/sql/ry_job.sql 只在启用 SnailJob 调度中心时需要，它建的是调度中心自己的 sj_* 表。
• script/sql/update/ 里其余的 platform_*.sql、app_market_<app>_migrate.sql、fix_* / cleanup_* 是存量库专用的一次性脚本，全新部署不需要。

初始化是否完整，不要看 sys_config 里的 platform.init.version 这一行 —— 它不在 platform_init.sql 里， 而是后端容器首次启动、导入完成之后才写进去的标记（wujies-platform/deploy/docker/backend/entrypoint.sh， 约 L103–106，值取环境变量 PLATFORM_INIT_VERSION，插入是幂等的）。 所以手工导库时这一行必然不存在，拿它当判据会把一次成功的初始化误判成失败。

手工导库要判断初始化是否完整，去看表和数据在不在：

• 表：sys_user / sys_menu / sys_config / app_info 是否都建出来了；
• 行：sys_user 里有没有 user_id = 1 的默认账号、sys_menu 里有没有菜单行；
• app_info 有没有目录种子行 —— 0 行说明第 ③ 步（app_catalog_seed.sql）没导进去，市场会是空的。

改连接串复制标题链接

3. 编译并打包后端复制标题链接

所有命令的工作目录都是 wujies-platform/。

& $mvn -B -q compile -DskipTests                        # 全反应堆编译（根 pom 默认 skipTests=true，编译不跑测试）
& $mvn -pl wujies-admin -am -B install -DskipTests      # 打可运行 jar → wujies-admin/target/wujies-admin.jar

4. 启动后端宿主复制标题链接

手工启动（推荐，最少魔法）复制标题链接

java "-Dloader.path=plugins-dist" "-Dspring.profiles.active=dev" -jar wujies-admin\target\wujies-admin.jar

三个要点：

1. 工作目录必须是 wujies-platform/。app-market.deploy.plugin-dir（plugins-dist）与 frontend-dir（../wujies-admin/app-market-dist/remote-apps）都是相对路径，见 wujies-admin/src/main/resources/application.yml。
2. profile 要显式传。application.yml 里的 spring.profiles.active 是构建期由 Maven 属性 @profiles.active@ 替换的（根 pom.xml 里 dev 是默认激活的 profile），别依赖它：本地用 -Dspring.profiles.active=dev（读 application-dev.yml），部署用 prod。
3. -Dloader.path 只在打包后的 jar 上生效。wujies-admin/pom.xml 配了 layout=ZIP，只有它才认这个参数；从 IDE 直接跑主类时它会被静默忽略 —— 表现为 plugins-dist 里明明有 jar，安装应用却报「当前 JVM 没有加载 xxx.jar」。

调整端口用 -Dserver.port=8087（application.yml 的默认值是 8086）。

启动脚本：先读这段再决定用不用复制标题链接

wujies-platform/script/prune/start-host.ps1 的意图是「先清理上一版插件 jar，再打包，再用正确的 loader.path / profile 启动」。

5. 启动前端复制标题链接

cd plus-ui
npm install
npm run dev

6. 登录复制标题链接

打开 http://localhost/login：

接口请求要同时带 Authorization 与 clientid 两个头，缺一不可 —— clientid 会被 wujies-common-security 的 SecurityConfig 与 token 里记录的值比对。前端已处理好（plus-ui/src/utils/request.ts 从 VITE_APP_CLIENT_ID 设默认头），手工调接口时注意。

7. 装一个应用，验证整条链路复制标题链接

登录后的菜单结构来自 platform_init.sql 的 sys_menu 种子行：

步骤：

1. 应用市场里挑一个应用（例如「图床管理」），点安装；
2. 打开 我的应用 → 应用任务，看进度、当前步骤与日志 —— 这是排查问题的第一站，步骤与日志是边跑边落库的，失败原因（含服务端异常文本）都在那里，见 任务中心与日志；
3. 安装成功后左侧菜单出现该应用的入口。

全程不需要重启后端。

一次安装实际发生什么：

1. 生成 app_install_task 记录（任务中心看的就是它）
2. 检查本机有没有产物
   ├─ 已有 → 就地使用（同一版本重装）
   └─ 没有 / 正在升级 → 按 packageUrl 从市场拉包
        ├─ 校验 MD5 / SHA256
        ├─ 安全检查：产物白名单 + 签名校验
        ├─ 解包落位：jar → plugin-dir 根下；前端 → frontend-dir/<appCode>/
        └─ 记录 active-plugins.txt
3. 执行包内 migrations/*.sql（按文件名排序，幂等，只做 up）
4. 加载后端插件            ← 在迁移之后
5. 同步菜单与授权（按 app.json 的 menus 幂等 upsert）
6. 任务置为成功

三条值得记住的设计：

• 迁移在加载之前是刻意的：先改表结构、再切换代码。反过来的话，新代码在启动时机读一个还没加的列就会炸。

• 升级会强制重新落位（按 fromVersion != toVersion 判断），「文件存在就跳过」只在同版本重装时成立。

• plugins-dist/active-plugins.txt 是运行期选版本的依据，一行一条 appCode=jarFileName：

  复制代码

  gallery=wujies-gallery-plugin-1.0.5.jar
  mall=wujies-mall-plugin-1.0.3.jar

  插件 jar 与前端目录都落位在部署内全局共享的位置，所以「彻底删除」受两道闸约束（别的租户还在用就不动、平台表前缀受保护），详见 生命周期。

8. 跑测试复制标题链接

工作目录同为 wujies-platform/：

& $mvn -pl wujies-modules/wujies-app-market -B test "-DskipTests=false" "-Dprofiles.active=dev"

起不来？先看这几条复制标题链接

更多症状见 wujies-platform/AGENTS.md 第 5 节「已知坑」与 docs/开发问题与解决方案.md；故障排查 一节的部分命令仍是改造前的写法，读时按本页的命令替换。

相关阅读复制标题链接

• 环境要求 —— 版本、端口、依赖矩阵
• 核心概念 —— 宿主 / 应用 / 契约这些词在当前架构下的含义
• 必须遵守的不变量 —— 改代码前扫一遍
• 应用清单、菜单注册、迁移脚本 —— 写应用时的三份规范
• 在部署里使用应用 —— 安装、升级、停用、卸载的完整操作
• 数据模型、生命周期 —— 表与状态机

界面截图复制标题链接

后台登录页（截图占位）

/images/docs/quickstart-login.png

建议 1920 × 1080，截登录表单与验证码。