> 本文整理自平台文档 docs/wujies/5.x/deploy/ops/troubleshooting.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-45dd31fe1db1-cover.svg)
这一页解决「现在坏了,先看哪儿」:按现象给判据与处理。每条都来自实测记录(wujies-platform/AGENTS.md 的实测段落、wujies-platform/docs/开发问题与解决方案.md、以及平台源码本身),不是推测。
写法上刻意写到可核对的粒度:类名、配置键、日志原文、文件路径都给出来。标了「见某文件」的,就是让你直接去读那处代码 —— 宁可让你自己核对,也不写一句查不到的话。
设计意图(为什么会这样)不在这里,各节末尾与页脚给出对应页面。
1. 第一站永远是「我的应用 → 应用任务」。 安装/升级/卸载的步骤与日志是边跑边落库的,失败原因(含服务端异常文本)就在那条任务记录里,比翻服务端日志快。见 [任务中心与日志](/docs/wujies/5.x/deploy/ops/task-center)。 2. 先看「非对称」。 同一流程里 A 成 B 败,B 的差异点就是线索:jar 删不掉的死循环就是靠「同一分钟里 im 的 jar 删得掉、mall 的删不掉」定位的。 3. 每次只改一件事,并让失败可见(日志/计数/断言),改完如实说「改完了,请验」,不要说「修好了」。
---
启动与加载
| 现象 | 判据与原因 | 处理 |
|---|---|---|
启动直接失败,最后一句是 Result Maps collection already contains value | 同一个 appCode 名下两个版本的 jar 同时进了 MyBatis,各自带一份同样的 mapper XML。两个加载时机(启动期的 PluginClassPathLoader.listJars、运行期的 PluginRuntimeManager)都按 active-plugins.txt 选版本,但清单缺失或为空时两者都不过滤,退化成「目录下所有 jar 全挂」 | 先确认 <插件目录>/active-plugins.txt 存在且非空(格式 appCode=jar 文件名)。再清残留 jar(见下面那条 warning)后重启 |
启动日志有 跳过 N 个不在 active-plugins.txt 里的 jar(刻意不挂载),或运行期 WARN 插件 X 有 N 个 jar 在场但未生效(不在 active-plugins.txt 里) | 旧版本残留。Windows 上被 JVM 占用的 jar 删不掉是常态,所以这个状态是刻意允许的 | 不用处理。但若某个应用本该生效却没生效,说明清单里那一行丢了:重装一次该应用,或按 appCode=jar 文件名 手工补回清单 |
| 插件完全没加载,只打一条醒目告警 | 只在 yml 里改了 app-market.plugin-runtime.enabled。启动加载器在 Spring 之前执行,读的是系统属性(PluginRuntimeManager.ENABLED_PROPERTY),application.yml 里根本没有这个键 → 启动器让路、运行期又没开 | 只在要退回旧行为时用 JVM 参数 -Dapp-market.plugin-runtime.enabled=false;正常启用不要在 yml 里写这个键。见 [配置项索引](/docs/wujies/5.x/deploy/configuration) 的「不能只写在 yml 里的配置」 |
插件控制器启动即报 expected single matching bean but found 2 | 宿主上下文里注册了与插件实现同类型的 bean(哪怕是转发代理):Spring 按类型注入会把父子上下文的候选一起算 | 宿主侧不要注册插件实现类型。宿主取插件服务只有两条路:PluginServiceProvider(wujies-common-core),或 MemberServiceLocator / PayServiceLocator / ImServiceLocator(wujies-common-plugin-sdk)。见 [插件运行时](/docs/wujies/5.x/platform/architecture/plugin-runtime) |
正在运行的服务突然抛 NoClassDefFoundError | 有人在正在跑的 JVM 上执行了 mvn install:compiler 插件先清空输出目录再全编,而运行中的 JVM 按需懒解析类 | 不要在别人正在跑的 JVM 上 install;要并行就改工作副本或先停服务。见 [必须遵守的不变量](/docs/wujies/5.x/platform/plugin/basics/invariants) 第 11 条 |
日志出现 ZipException: invalid LOC header (bad signature),或重装后行为诡异 | 边读边写:被启动期加载器打开着的 jar 被同名新 jar 覆盖了(Windows 上覆盖允许、删除被拒) | 停宿主 → 删残留 jar → 重装。「停掉宿主 → 删 jar → 重装」这条土办法每次有效,正因为它绕开了覆盖 |
PowerShell 里报 ClassNotFoundException: /path=plugins-dist | -D 参数没加引号,PowerShell 把 .path 当路径拆开了 | 加引号,见下面的代码块 |
老命令 powershell ... -File script\prune\prune-plugins.ps1 报「找不到文件」 | script/prune/ 整目录(prune-plugins.ps1 / prune-plugins.sh / start-host.ps1)已在 2026-10-26 的 d0cc5cd90 删除,仓库里没有这条命令了 | 按 [运维手册](/docs/wujies/5.x/deploy/ops/) 第五节手工清:只删「同一个 appCode 名下、不在 active-plugins.txt 清单里」的 jar。顺带一提它原来的两个坑(Windows PowerShell 5.1 缺 UTF-8 BOM 会把中文源码按 ANSI 解码、留空 -PluginDir 时按「脚本上级目录」推断出 script/plugins-dist)现在都由「显式指定目录 + 只看清单」这两条纪律替代 |
# 手工启动:-D 参数必须加引号
java "-Dloader.path=plugins-dist" "-Dspring.profiles.active=prod" -jar wujies-admin\target\wujies-admin.jar
平台仓库里已经没有清理脚本(script/prune/ 于 2026-10-26 的 d0cc5cd90 删除),所以这一步只能手工做,而且只有一条判据:同一个 appCode 名下、不是 active-plugins.txt 记录的那个 jar 才是残留。
- 清单在
<插件目录>/active-plugins.txt,一行一条appCode=jarFileName;目录默认是plugins-dist(容器路线是宿主./data/plugins-dist)。 - 手工拷进来试的、不属于任何已登记应用的 jar 不要碰 —— 老脚本一律不碰它们,手工删前先确认。
- Windows 上被运行中的 JVM 占用的 jar 删不掉是常态:先停宿主再删(见「卸载」一节
AppPurgeService那条)。 - 命令与逐条解释见 [运维手册](/docs/wujies/5.x/deploy/ops/) 第五节「清理残留的旧插件 jar」。
---
改了没生效:构建与验证
| 现象 | 判据与原因 | 处理 |
|---|---|---|
| 改了后端代码,行为没变 | 只跑了 mvn compile —— 它不会更新 wujies-admin.jar,你启动的还是旧代码 | mvn -pl wujies-admin -am -B install -DskipTests 后重启(⚠️ 先停掉正在跑的宿主进程,别在活的 JVM 上 install)。确认 jar 是新的:模块类在 fat jar 里是嵌套的(BOOT-INF/lib/wujies-<模块>-<版本>.jar),在顶层找 cn/wujies/...class 永远找不到;嵌套条目的时间戳也不可靠 —— 要把嵌套 jar 抽出来看里面那个 class |
改了注解/常量后 BUILD SUCCESS,但行为仍是旧的 | maven-compiler-plugin 按时间戳判断是否重编:源码与上次的 class 落在同一秒内会被判「已是最新」,装进本地仓库的还是旧注解 | 验证前先 mvn -pl <模块> clean install;下结论前用 javap -v 看 jar 里那个 class |
| 新增的测试「跑了」但没执行 | 根 pom 的 surefire 配了 <groups>${profiles.active}</groups>,没打 @Tag 的测试根本不会被执行 | 照抄现有测试的 @Tag("dev") @Tag("local") @Tag("prod"),并在新增后**核对 Tests run |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-45dd31fe1db1-guide.svg)


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