日常问题：演示站 WMS 返回「已禁用」，合同等模块正常

问题现象

• 演示站 ruoyioffice.com 登录后访问 WMS 首页，页面弹出多条错误： [WMS 仓库管理系统 yudao-module-wms - 已禁用][参考 https://doc.iocoder.cn/wms/build/ 开启]
• 同期 合同（/admin-api/contract/**）等模块接口正常。
• Jenkins 构建日志显示 yudao-module-wms-server 编译 SUCCESS，容器 yudao-server:64 健康检查通过。
• 源码中 yudao-server/pom.xml 已依赖 yudao-module-wms-server，WmsReceiptOrderController 等控制器存在且无 @ConditionalOnProperty 开关。

根因

不是旧容器、不是 nginx 路由错误，而是 WMS 模块 jar 被打成 Spring Boot 可执行 fat jar，嵌套进外层 app.jar 后类加载器找不到 WMS 类，运行时未注册任何 Wms*Controller。

1. yudao-module-wms-server/pom.xml 的 spring-boot-maven-plugin 缺少 与其它模块一致的：

   <configuration>
       <skip>${skip.repackage}</skip>
   </configuration>

2. 单体模式（-P boot）下根 pom.xml 设 skip.repackage=true，各模块应产出薄 jar；WMS 漏配后仍执行 repackage，产出约 150MB 的 fat jar。
3. 该 fat jar 被放入外层 app.jar 的 BOOT-INF/lib/。外层类加载器在依赖 jar 根目录扫描 cn/iocoder/yudao/...，而 WMS 类在 BOOT-INF/classes/ 下 → 不可见 → 无 Bean、无 Controller。
4. 请求 /admin-api/wms/** 无真实映射，落到 DefaultController.wms404() → 返回「已禁用」。

易误判点：裸 curl 返回 401 不能证明控制器已注册

/admin-api/** 的鉴权在 DispatcherServlet 路由之前。未带 token 时，无论真实控制器是否存在，都可能返回 {"code":401,"msg":"账号未登录"}。必须用 /actuator/mappings 或 /actuator/beans 判定。

排查步骤

演示环境经 frp 穿透，可用项目技能 remote-env-troubleshoot（scripts/ssh_run.py）或 SSH 连 182.92.106.252:13022（→ 内网 192.168.30.130:22）。

1. 确认运行容器与镜像

docker ps -a --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
docker images | grep yudao-server

确认 48080 上是否为预期 tag（如 yudao-server:64），无旧容器占用同端口。

2. 用 actuator 判定控制器是否注册（权威）

CID=$(docker ps -qf publish=48080)
docker exec $CID sh -c 'curl -s 127.0.0.1:48080/actuator/mappings > /tmp/m.json'
docker exec $CID sh -c "grep -oE 'Wms[A-Za-z]+Controller' /tmp/m.json | sort -u"
docker exec $CID sh -c "grep -oE 'Contract[A-Za-z]+Controller' /tmp/m.json | sort -u"
docker exec $CID sh -c "grep -oE '/admin-api/wms[A-Za-z/{}*-]*' /tmp/m.json | sort -u"

现象	含义
有 WmsXxxController	WMS 已注册
仅有 /admin-api/wms/**，无 Wms*Controller	仅兜底 wms404，模块未加载
Contract*Controller 有多条而 WMS 为空	典型 fat jar 嵌套问题

docker exec $CID sh -c 'curl -s 127.0.0.1:48080/actuator/beans > /tmp/b.json'
docker exec $CID sh -c "grep -oE 'cn[a-zA-Z0-9_.]*module[.]wms[a-zA-Z0-9_.]*' /tmp/b.json | sort -u | head"

注意：WmSalesNoticeController 等可能来自 MES（cn.iocoder.yudao.module.mes...wm...），不要与 WMS 混淆。

3. 检查 app.jar 内模块 jar 形态

宿主机需 unzip（CentOS：yum install -y unzip）。

docker cp $CID:/yudao-server/app.jar /tmp/app.jar
unzip -l /tmp/app.jar | grep yudao-module | grep server

异常特征（WMS）：

150171913  02-01-1980 00:00   BOOT-INF/lib/yudao-module-wms-server-....jar   # ~150MB，1980 时间戳
 2769996  06-21-2026 13:14   BOOT-INF/lib/yudao-module-mes-server-....jar    # 正常薄 jar ~MB 级

解嵌套 jar 确认 fat 结构：

mkdir -p /tmp/nx && cd /tmp/nx
unzip -oq /tmp/app.jar BOOT-INF/lib/yudao-module-wms-server-*.jar
unzip -l BOOT-INF/lib/yudao-module-wms-server-*.jar | head -20    # 含 org/springframework/boot/loader/
unzip -l BOOT-INF/lib/yudao-module-wms-server-*.jar | grep -c BOOT-INF   # >0 即为 repackage 的 fat jar

类在 BOOT-INF/classes/cn/iocoder/yudao/module/wms/...，而非 jar 根目录。

修复

在 ruoyi-office/yudao-module-wms/yudao-module-wms-server/pom.xml 的 spring-boot-maven-plugin 中补上（与 yudao-module-mes-server 等一致）：

<configuration>
    <!-- 单体模式下跳过 repackage，由 yudao-server 统一打包 -->
    <skip>${skip.repackage}</skip>
</configuration>

重新构建部署：

1. mvn clean 全量重打（避免复用 .m2 中坏的 150MB wms-server jar）。
2. Jenkins 新构建并部署新镜像。
3. 验证：

   docker exec $CID sh -c "curl -s 127.0.0.1:48080/actuator/mappings | grep -o WmsReceiptOrderController"

   浏览器 WMS 首页不再报「已禁用」。

修复后 unzip -l app.jar 中 yudao-module-wms-server-*.jar 应为 MB 级、时间与同批模块一致（非 1980）。

关联代码 / 配置

路径	说明
ruoyi-office/yudao-module-wms/yudao-module-wms-server/pom.xml	漏写 <skip>${skip.repackage}</skip> 的根因
ruoyi-office/pom.xml	boot profile 中 skip.repackage=true
ruoyi-office/yudao-server/src/main/java/.../DefaultController.java	wms404() 兜底 /admin-api/wms/**
.cursor/skills/remote-env-troubleshoot/	演示/生产 SSH、docker、actuator 排查技能

相关链接

• 知识库（客户向简述）：演示站某模块显示已禁用——单体打包 fat jar 嵌套

修订记录

日期	修改
2026-06-22	初稿：演示站 WMS #64 排障结论与 fat jar 嵌套根因