> 本文整理自平台文档 docs/wujies/5.x/platform/app-market/using-apps.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-c1409c50d2f2-cover.svg)
这一页面向在部署里操作应用的人(租户管理员 / 运维):从哪个页面装、每个动作后端真实做了什么、菜单为什么有时候不立刻出现、卡住时去哪看。
它不解释"为什么这么设计"。机制与取舍见 [应用生命周期](/docs/wujies/5.x/platform/app-market/lifecycle)、[插件运行时](/docs/wujies/5.x/platform/architecture/plugin-runtime) 和 [菜单归属与保护](/docs/wujies/5.x/platform/app-market/menu-ownership)。
下面的操作都在宿主前端里做,需要对应权限:浏览市场 app:market:list,安装/升级/启停/卸载 app:install:edit(或 app:install:add),看任务 app:install:list。接口清单见 [HTTP 接口索引](/docs/wujies/5.x/platform/reference/api)。
操作入口在哪
| 想做的事 | 页面 | 路由 | 前端源码 |
|---|---|---|---|
| 逛市场、安装、升级 | 应用市场 | /appmarket/market | wujies-admin/src/views/appstore/market/index.vue |
| 看已装应用的版本与状态、启停、卸载 | 我的应用 → 已安装应用 | /myapps/installed | wujies-admin/src/views/appstore/installed/index.vue |
| 看进度、步骤、失败原因 | 我的应用 → 应用任务 | /myapps/task | wujies-admin/src/views/appstore/tasks/ |
| 从工作台进应用 | 工作台「我的应用」卡片 | /index | wujies-admin/src/views/workplace/index.vue |
两个页面上的动作都会在任务中心留下一条 app_install_task:安装、升级、启用、停用、卸载都是异步的,接口先返回 taskId,过程在后台跑。排查任何生命周期问题,第一站都是应用任务,见 [任务中心与日志](/docs/wujies/5.x/deploy/ops/task-center)。
安装
界面上是「应用市场 → 选应用 → 安装 → 确认」,装完会自动启用(前端提示「安装成功,已自动启用」)。
后端按固定顺序做四件事(PluginAppInstaller,源码:wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/spi/impl/PluginAppInstaller.java):
| # | 任务日志里的步骤 | 做了什么 |
|---|---|---|
| 1 | 「从应用市场拉取安装包」 | 先判断本机有没有该版本产物;缺(或正在换版本)就按目录里的 packageUrl 下载 → 校验 MD5/SHA256 → 产物白名单 + 签名校验 → 解包落位 → 写 active-plugins.txt。这一步不加载代码 |
| 2 | 「执行版本迁移脚本」 | 扫 <plugin-dir>/migrations/<appCode>/,按文件名排序逐个执行包内 migrations/*.sql,结果记进 app_schema_history;执行后清字典与参数的 Redis 缓存 |
| 3 | 「校验后端产物:<jar>」 | 先问插件运行时,再问 classpath 探针,最后"磁盘上有就装上";三种都拿不到就抛错,安装失败 |
| 4 | 「同步菜单与授权」 | 按 app.json 的 menus 幂等 upsert,再把该版本菜单授权给本租户的管理员角色 |
进度台阶是 10 / 20 / 30 / 40 / 60 / 100,状态迁移为 installing → installed → enabled,最后 AppMenuCache 按租户失效一次。编排与状态机在 wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/service/impl/AppInstallServiceImpl.java。
真实顺序是 产物落位 → 变更表结构 → 切换代码 → 同步菜单。落位与加载被拆成两步(安装/升级调 AppPackageDeployService.deploy(versionId, false) 只落位),加载交给第 3 步。
反过来(先加载新代码再改表)的话,插件在启动时机读一个还没建的列就会炸。迁移失败会中断,且不会加载新代码 —— 宁可停在旧代码上。
某些失败(例如后端插件未加载)会让接口直接抛异常,前端拿不到 taskId。但任务记录在动作执行之前就已落库,日志一定在。所以失败弹窗会直接把你送去「应用任务」。
菜单为什么没有立刻出现
这是安装/升级/卸载之后最常见的疑问,涉及三样不同的东西。
后端两份数据:
| 数据 | 变化时机 |
|---|---|
sys_menu 里的菜单行 | 安装/升级时由清单幂等 upsert(按 menu_key 复用既有 menu_id);卸载(保留数据)时保留,彻底删除时才删 |
| 本租户可见哪些菜单 | 停用/卸载后,AppMenuFilterImpl.invisibleMenuIds() 让这些菜单不再出现在 /system/menu/getRouters 的结果里。该结果按租户缓存在 AppMenuCache,安装/升级/启用/停用/卸载的状态落库处会主动失效 |
前端第三样:菜单树只在登录时生成一次。 所以上述动作改完数据后,同一会话里那份旧树会继续生效,表现是「装完回工作台没有这个应用,强刷才出来」或「升级后页面还在按旧路径解析」。
前端为此提供了重建入口:wujies-admin/src/plugins/appmarket/menuRefresh.ts 的 refreshMenus() —— 重新拉菜单并重建路由(幂等)。它失败不抛给调用方,只打 console.warn,顶多这次没刷新到。
| 动作成功后刷新菜单的地方 | 说明 |
|---|---|
wujies-admin/src/views/appstore/market/index.vue | 安装成功、市场内一键升级成功后各调一次 |
wujies-admin/src/views/appstore/installed/index.vue | 升级/启用/停用/卸载走同一个 runAndShowTask,任务成功即调一次 |
wujies-admin/src/views/workplace/index.vue | 工作台自愈:发现已装应用在旧树里找不到入口,先重建再判定 |
还是没出现时按顺序试:
1. 手动刷新页面(等价于重新走一遍登录后的菜单生成); 2. 去「应用任务」确认那次动作真的成功了 —— 失败时前端不会重建菜单; 3. 菜单行本身漂移了(挂到了已删除的菜单 ID 上),用 POST /app/install/{installId}/sync-menus(权限 app:install:edit)重新同步,它是幂等的;自愈逻辑丢弃死映射时会在任务日志里 WARN 出被丢弃的 menu_key。
升级
「我的应用」列表里版本旁出现「可升级 x.y.z」时才显示升级按钮;市场卡片上也能一键升级到最新版。
相对安装,升级的行为差异是:
| 差异 | 说明 |
|---|---|
| 强制重新拉包落位 | 只要目标版本与当前版本不同,本机现有产物(按定义是旧版本)一律不复用。「文件存在就跳过」只在同版本重装时成立 |
| 菜单按新版本清单幂等 upsert | 同名 menu_key 复用既有 menu_id,租户已分配的权限不失效 |
| 保留原启停状态 | 已停用的应用升级完仍是停用(状态迁移为 upgrading → disabled) |
第一次差异是刻意做的:沿用旧产物会同时踩两个静默坑 —— 前端还是旧版、包内 migrations/*.sql 根本不落位。
后端会直接拒绝:「当前已是该版本,无需升级」。想重装请走重新安装或已安装页的「部署」。
### 回到旧版本
从市场选一个更低的版本安装或升级即可,菜单会按旧版本清单同步回去。
但表结构不会回滚 —— 迁移脚本只做 up。回退前请自己确认旧代码能不能吃新表结构,规则见 [数据库迁移](/docs/wujies/5.x/platform/plugin/advanced/migrations)。
停用与启用
| 动作 | 后端真实行为 | 状态可迁移自 |
|---|---|---|
| 停用 | 只做 unload(关子 Spring 上下文与类加载器、注销接口)。不动 app_install.status 之外的任何数据:菜单行、授权都保留 | enabled |
| 启用 | 先 load(把插件后端装回来)再补授权、放出菜单 | ` |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-c1409c50d2f2-guide.svg)


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