> 本文整理自平台文档 docs/wujies/1.x/ops/troubleshooting.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-f34d64587c36-cover.svg)
这一页解决「现在坏了,先看哪儿」:按现象给判据与处理。每条都来自实测记录(wujies-platform/AGENTS.md 的实测段落、工作区 docs/开发问题与解决方案.md、以及平台源码本身),不是推测。
写法上刻意写到可核对的粒度:类名、配置键、日志原文、文件路径都给出来。标了「见某文件」的,就是让你直接去读那处代码 —— 宁可让你自己核对,也不写一句查不到的话。
设计意图(为什么会这样)不在这里,各节末尾与页脚给出对应页面。
1. 第一站永远是「我的应用 → 应用任务」。 安装/升级/卸载的步骤与日志是边跑边落库的,失败原因(含服务端异常文本)就在那条任务记录里,比翻服务端日志快。见 [任务中心与日志](/docs/wujies/1.x/ops/task-center)。 2. 验证跨进程调用时,不要一边用 curl 手工打对端。 否则对端访问日志里那几条 GET /app/catalog/... 是你自己打的,你会把「我打成功了」当成「调用方链路通了」—— 这个坑真实踩过。同理 HTTP 200 不等于成功:远程目录出现过「返回 200 但 body 是错误信封」。 3. 先看「非对称」。 同一流程里 A 成 B 败,B 的差异点就是线索:jar 删不掉的死循环就是靠「同一分钟里 im 的 jar 删得掉、mall 的删不掉」定位的。 4. 每次只改一件事,并让失败可见(日志/计数/断言),改完如实说「改完了,请验」,不要说「修好了」。
---
启动与加载
| 现象 | 判据与原因 | 处理 |
|---|---|---|
启动直接失败,最后一句是 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/1.x/reference/config) 的「不能只写在 yml 里的配置」 |
插件控制器启动即报 expected single matching bean but found 2 | 宿主上下文里注册了与插件实现同类型的 bean(哪怕是转发代理):Spring 按类型注入会把父子上下文的候选一起算 | 宿主侧不要注册插件实现类型。宿主取插件服务只有两条路:PluginServiceProvider(wujies-common-core),或 MemberServiceLocator / PayServiceLocator / ImServiceLocator(wujies-common-plugin-sdk)。见 [插件运行时](/docs/wujies/1.x/advanced/plugin-runtime) |
正在运行的服务突然抛 NoClassDefFoundError | 有人在正在跑的 JVM 上执行了 mvn install:compiler 插件先清空输出目录再全编,而运行中的 JVM 按需懒解析类 | 不要在别人正在跑的 JVM 上 install;要并行就改工作副本或先停服务。见 [必须遵守的不变量](/docs/wujies/1.x/plugin-dev/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 报一串中文乱码 + Unexpected token | 脚本 script/prune/prune-plugins.ps1 当前没有 UTF-8 BOM,Windows PowerShell 5.1 按 ANSI 解码中文源码 → 解析失败(已实测复现) | 给该文件补回前三字节 EF BB BF 再跑,或按清单手工删残留 jar。script/prune/start-host.ps1 有 BOM、能解析,但它内部同样是用 powershell.exe 调这个脚本,所以它那一步"清理旧 jar"当前会失败并只打一条警告(不阻断启动) |
# 手工启动:-D 参数必须加引号
java "-Dloader.path=plugins-dist" "-Dspring.profiles.active=prod" -jar wujies-admin\target\wujies-admin.jar
script/prune/prune-plugins.ps1 还有一个目录推断错位:-PluginDir 留空时它按「脚本的上级目录 + plugins-dist」推断,算出的是 wujies-platform/script/plugins-dist,而不是平台根下的 plugins-dist(见该文件第 31-34 行)。所以必须显式传 -PluginDir:
# 在 wujies-platform 目录下执行;脚本有 BOM 之后这两条才跑得起来
powershell -NoProfile -ExecutionPolicy Bypass -File script\prune\prune-plugins.ps1 -PluginDir plugins-dist -DryRun
powershell -NoProfile -ExecutionPolicy Bypass -File script\prune\prune-plugins.ps1 -PluginDir plugins-dist
它只删「同一个 appCode 名下、但不是当前生效版本」的 jar,手工放进去的 jar 不碰。start-host.ps1 内部传的是绝对路径,不受推断错位影响(但受上面那条 BOM 影响)。
---
改了没生效:构建与验证
| 现象 | 判据与原因 | 处理 |
|---|---|---|
| 改了后端代码,行为没变 | 只跑了 mvn compile —— 它不会更新 wujies-admin.jar,你启动的还是旧代码 | mvn -pl wujies-admin -am -B install -DskipTests 后重启。确认 jar 是新的:模块类在 fat jar 里是嵌套的(BOOT-INF/lib/wujies-<模块>-<版本>.jar,本机实测 29 个),在顶层找 cn/wujies/...class 永远找不到;嵌套条目的时间戳也不可靠 —— 要把嵌套 jar 抽出来看里面那个 class |
改了注解/常量后 BUILD SUCCESS,但行为仍是旧的 | maven-compiler-plugin 按时间戳判断是否重编:源码与上次的 class 落在同一秒内会被判「已是最新」,装进本地仓库的还是旧注解 | 验证前先 mvn -pl <模块> clean install;下结论前用 javap -v 看 jar 里那个 class |
| 新增的测试「跑了」但没执行 | 根 pom 的 surefi |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-f34d64587c36-guide.svg)


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