问题

演示站或生产环境登录后，某个业务模块（例如 WMS 仓储）页面报错：

[WMS 仓库管理系统 yudao-module-wms - 已禁用][参考 … 开启]

但合同、OA 等其它模块接口正常。Jenkins 构建显示该模块编译成功，容器也健康，源码里模块依赖和控制器都在，为什么还是「已禁用」？

答案

多数是单体部署时，该模块的 *-server 子工程被错误打成 Spring Boot 可执行 fat jar，嵌进主 app.jar 后类加载不到，运行时没有注册控制器，请求落到框架兜底接口。 在对应 *-server/pom.xml 的 spring-boot-maven-plugin 中补上 <skip>${skip.repackage}</skip>，mvn clean 全量重打并重新部署即可。

详细说明

1. 「已禁用」是什么意思？

后端 DefaultController 为未启用模块提供了兜底路由（如 /admin-api/wms/**）。当没有真实的 WmsXxxController 注册时，请求会命中兜底并返回「xxx 模块 - 已禁用」。

因此：不是前端缓存问题，而是运行时该模块的 Java 类未被加载。

2. 常见误判：401 不代表模块已启用

未登录直接访问 /admin-api/wms/... 可能返回 {"code":401,"msg":"账号未登录"}。鉴权发生在路由之前，401 不能区分「真实控制器」与「兜底已禁用」。

运维/二开排查应在服务器容器内查注册表（免登录）：

CID=$(docker ps -qf publish=48080)
docker exec $CID curl -s 127.0.0.1:48080/actuator/mappings > /tmp/m.json
grep -oE 'Wms[A-Za-z]+Controller' /tmp/m.json | sort -u   # 有输出=已注册；空=未注册

3. 根因：fat jar 嵌套（以 WMS 为例）

单体模式（Maven -P boot）下，各 yudao-module-*-server 应产出薄 jar（类在 jar 根目录），由 yudao-server 统一打成一个大 app.jar。

若某模块 pom.xml 中 spring-boot-maven-plugin 缺少：

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

则该模块会被 repackage 成可执行 fat jar（体积可达上百 MB，zip 时间戳常为 1980-02-01）。嵌进主 jar 的 BOOT-INF/lib/ 后，外层类加载器在依赖 jar 根目录找不到 cn/iocoder/yudao/module/...，该模块全部 Bean/Controller 不注册。

对比正常模块 jar：体积通常 0.3～3 MB，构建时间与同批模块一致。

4. 修复步骤

1. 对比同仓库其它正常模块（如 yudao-module-mes-server/pom.xml），在问题模块的 spring-boot-maven-plugin 补上 <skip>${skip.repackage}</skip>。
2. 执行 mvn clean 后重新 Jenkins 构建（避免复用本地/仓库中已坏的 fat jar）。
3. 部署新镜像，容器内再次 grep WmsXxxController /tmp/m.json 确认已注册。
4. 浏览器刷新验证模块页面。

5. 演示环境连接（frp）

公网	内网	用途
182.92.106.252:13022	192.168.30.130:22	SSH
182.92.106.252:13306	192.168.30.130:3306	MySQL
182.92.106.252:48080	192.168.30.130:48080	后端 API

工作区内可使用 Cursor 技能 remote-env-troubleshoot 执行容器列表、actuator 探活、日志抓取等预设命令。

涉及代码 / 配置

• ruoyi-office/pom.xml：boot profile 的 skip.repackage=true
• ruoyi-office/yudao-module-*/yudao-module-*-server/pom.xml：各模块 spring-boot-maven-plugin 应含 <skip>${skip.repackage}</skip>
• ruoyi-office/yudao-server/.../DefaultController.java：模块未注册时的「已禁用」兜底

相关链接

• 开发向完整排障（现象、unzip 验证、易混淆 MES Wm* 类名）：日常问题-演示站WMS已禁用-fat-jar嵌套未注册

修订记录

日期	修改
2026-06-22	初稿