基于 RuoYi-Vue 3.9.2 的灵珑（LingFrame）灵核化改造演示项目。
声明：本项目为第三方改造演示，非若依官方项目。若依原版代码遵循 MIT LICENSE（Copyright (c) 2018 RuoYi）。
本项目是 LingFrame 生态的官方改造范例，展示如何用灵珑微内核对存量 Spring Boot 单体做零侵入运行时治理。关于灵珑框架本身的设计理念与价值定位，请参阅 灵珑主仓库。
# 执行全量自动化测试（包含单测、治理集成测试与微内核闭环验证）
mvn clean test# 启动灵核单体应用（默认端口 8080，Dashboard 控制面: /dashboard.html）
java -jar lingframe-ruoyi-lingcore/target/lingframe-ruoyi-lingcore.jar# 生产环境使用 prod profile（关闭 dev-mode、强 token、严格安全模式）
java -jar lingframe-ruoyi-lingcore/target/lingframe-ruoyi-lingcore.jar --spring.profiles.active=prod生产环境必需的环境变量见 docs/production-hardening.md 上线前核验表。
启动后按以下步骤体验灵元热插拔（无需重启）：
- 打开 Dashboard 控制面：
http://localhost:8080/dashboard.html（开发模式 token：lingframe） - 在灵元列表查看 6 个已自动加载的灵元（
ling-roots配置的目录自动扫描） - 将
ling-storage-oss权重设为 100 → 文件上传切走阿里云 OSS - 将权重设为 0 → 自动回退灵核本地存储兜底
- 热卸载
ling-export-fast→ 导出回退原生 POI；重新部署 → 恢复流式导出
全程不停机、不重启、前端 0 感知。事件流实时查看：http://localhost:8080/lingframe/dashboard/sse
# 构建镜像（多阶段构建：灵核 fat jar + 全部灵元 jar）
docker build -t lingframe-ruoyi:latest .
# 启动容器（生产配置通过环境变量注入）
docker run -d \
-p 8080:8080 \
-e SPRING_PROFILES_ACTIVE=prod \
-e MYSQL_URL="jdbc:mysql://db:3306/ry-vue?..." \
-e MYSQL_USERNAME=root \
-e MYSQL_PASSWORD=${MYSQL_PASSWORD} \
-e REDIS_HOST=${REDIS_HOST} \
-e REDIS_PASSWORD=${REDIS_PASSWORD} \
-e TOKEN_SECRET=${TOKEN_SECRET} \
-e LINGFRAME_DASHBOARD_TOKEN=${LINGFRAME_DASHBOARD_TOKEN} \
-e LINGFRAME_MODE_SWITCH_PASSWORD=${LINGFRAME_MODE_SWITCH_PASSWORD} \
-e DRUID_USERNAME=${DRUID_USERNAME} \
-e DRUID_PASSWORD=${DRUID_PASSWORD} \
lingframe-ruoyi:latestCI/CD 配置见 .gitlab-ci.yml（构建 → 测试 → 打包 → 镜像 → 部署）。
LingFrame-RuoYi/
├── pom.xml # 根 POM：统一版本与构建顺序管理
├── lings/ # [灵元矩阵] 独立业务能力单元
│ ├── ling-notice-v2/ # [模式 1] 通知公告 v2 灰度切流灵元 (ISysNoticeService)
│ ├── ling-storage-oss/ # [模式 1] 阿里云 OSS 存储接管灵元 (ISysStorageService)
│ ├── ling-storage-cos/ # [模式 1] 腾讯云 COS 存储接管灵元 (ISysStorageService)
│ ├── ling-export-fast/ # [模式 1] 大数据流式导出接管灵元 (ISysExportService)
│ ├── ling-sms-aliyun/ # [模式 2] 阿里云多通道短信与验证码灵元 (ISysSmsService)
│ └── ling-sensitive-filter/ # [模式 3] 敏感词检测与文本合规脱敏灵元 (自包含端点)
└── lingframe-ruoyi-lingcore/ # [灵核] 若依原版纯净单体 + 灵珑 starter 纯净底座
灵核 13 个 Java 文件内部结构：
src/main/java/com/lingframe/ruoyi/
├── RuoYiApplication.java # 启动类（扩展 scanBasePackages）
├── contract/ # 契约接口（灵元实现，灵核兜底）
│ ├── ISysStorageService.java # 存储契约
│ ├── ISysExportService.java # 导出契约
│ └── ISysSmsService.java # 短信契约
├── bridge/ # AOP 桥接（拦截若依 Controller，转交灵元）
│ ├── StorageBridgeAspect.java # 上传桥接
│ └── ExportBridgeAspect.java # 导出桥接
├── provider/ # 兜底 Provider（灵元卸载后自动回退）
│ ├── LocalStorageServiceImpl.java # 本地存储兜底
│ ├── PoiExportServiceImpl.java # POI 导出兜底
│ └── DefaultLocalSmsProvider.java # 本地短信兜底
├── config/ # 灵珑接入配置
│ ├── DashboardWebMvcConfig.java # Dashboard MVC 配置
│ └── LingSecurityPermitPostProcessor.java # Security 白名单注入
├── web/controller/sms/ # 模式 2 薄门面
│ └── SysSmsController.java # 短信门面 Controller
└── exception/
└── LingGatewayExceptionHandler.java # 灵元网关异常处理
若依原版以
ruoyi-adminjar 依赖引入，源码不在本项目中，物理上零改动。
| 层 | Java 文件数 | 代码行数 | 职责 |
|---|---|---|---|
| 灵核底座 | 13 | 522 | 契约接口 / AOP 桥接 / 兜底 Provider / 配置 / 异常处理 |
| 灵元矩阵 | 41 | 2,898 | 6 个独立业务能力单元（存储/导出/短信/通知/敏感词） |
| 合计新增 | 54 | 3,420 | |
| 若依原版改动 | 0 | 0 | jar 依赖，源码未触碰 |
| 维度 | 灵核化方案 | 直接改若依源码 |
|---|---|---|
| 业务代码改动 | 0 行 | ~15 个 Controller × 修改 export 方法体 |
| 热插拔 / 回退 | 秒级，不停机 | 需重启 |
| 治理（限流/超时/内存预算） | 内置，声明式 | 需自行实现 |
| 多实现灰度共存 | 权重路由 | 不支持 |
| 作用范围 | 1 个切面 + 1 个契约 + 1 个灵元 | 每个场景逐个改 Controller |
在灵珑微内核架构体系中，针对不同业务诉求提供三大标准落地模式：
快速选择：存量业务增强 → 模式 1；新业务统一门面 → 模式 2；独立能力即插即用 → 模式 3。详见 改造指南·三大模式选择指南。
| 维度 | 模式 1：存量业务透明接管模式 | 模式 2：新业务契约门面模式 | 模式 3：新业务自包含独立端点模式 |
|---|---|---|---|
| 业务定位 | 存量系统渐进式绞杀与性能增强 | 企业核心新业务、平台中台能力扩展 | 完全独立即插即用扩展能力包 |
| 典型代表 | ling-storage-*、ling-notice-v2、ling-export-fast |
ling-sms-aliyun（多通道短信网关） |
ling-sensitive-filter（敏感词合规脱敏） |
| Controller 归属 | 灵核底座（原样复用，零修改） | 灵核提供薄门面（统一鉴权与入参校验） | 灵元内部自包含（动态挂载端点） |
| 调用与治理链路 | 灵核 AOP / @LingReference 动态代理 |
灵核注入 @LingReference 动态契约路由 |
灵珑微内核动态注册 Spring MVC 端点 |
| 容灾兜底机制 | 灵核默认实现 100% 自动兜底（永不 404） | 灵核统一熔断降级与本地控制台 Provider 保底 | 卸载后端点即时注销，零内存残留 |
| 核心收益 | 前端 0 感知，系统具备极限容灾兜底 | 统一安全审计与 API 规范，业务灵活多态 | 零侵入即插即用，灵核无需提前声明契约 |
| 场景 | 对应模式 | 机制与实现 | 核心价值与治理机制 | 前端改动 | 灵核 POM 依赖 | 灵核源码改动 |
|---|---|---|---|---|---|---|
| 1. 存量业务灰度切流 | 模式 1 | 原生 ISysNoticeService 契约• 灵核 SysNoticeServiceImpl• 灵元 NoticeV2ServiceImpl |
• 灵核/灵元双 Provider 双活 • 反向 Pinning 委托灵核 MyBatis 数据通道 • 动态权重分流、秒级回退与可证 GC 回收 |
0 | 0 | 0 |
| 2. 文件上传云化与热插拔 | 模式 1 | 接管 POST /common/upload• 阿里云 OSS 灵元 • 腾讯云 COS 灵元 |
• 前端 0 感知同路由无缝接管 • 秒级多云热替换、加权双活分流 • 热卸载自动回退本地磁盘保存 |
0 | 0 | 0 |
| 3. 大数据流式导出防 OOM | 模式 1 | 接管 POST /system/user/export• EasyExcel 流式导出灵元 |
• 前端 0 感知同路由同参数无缝接管 • 边查边流式写出，常驻内存仅数兆 • 彻底杜绝 POI DOM 模型引发的 JVM OOM • 热卸载自动回退原生 POI 导出 |
0 | 0 | 0 |
| 4. 多通道短信与验证码网关 | 模式 2 | 灵核门面 POST /system/sms/sendCaptcha• 契约 ISysSmsService• 灵元 AliyunSmsServiceImpl• 灵核 DefaultLocalSmsProvider |
• 灵核统一把控 60s 防刷与 Security 鉴权 • 控制台随时加权切流或热替换短信商 • 热卸载自动平滑回退本地控制台 Provider 兜底 |
0 | 0 | 新增薄门面 |
| 5. 敏感词合规检测与文本脱敏 | 模式 3 | 自包含端点 POST /ling/filter/**• 灵元 SensitiveFilterController• 内置 DFA 离线合规词库引擎 |
• 灵核底座 0 契约、0 Controller • 纯离线微秒级合规检测与脱敏 • 灵元加载动态挂载端点，热卸载干净注销 |
0 | 0 | 0 |
各场景的完整操作步骤与热插拔回滚见 改造指南。
| 文档 | 内容 |
|---|---|
| 改造指南 | 从若依原版到灵核化的完整路径：步骤、回滚预案、监控接入、踩坑说明、FAQ |
| 生产硬化清单 | 生产环境配置硬化、密钥管理、上线前核验表、灵元上线流程 |
若有自己的若依项目需要灵核化改造，可使用脚手架脚本快速生成底座结构：
./scripts/scaffold-lingcore.sh /path/to/RuoYi-Vue /path/to/output生成的底座包含灵核模块骨架、灵元模板、配置占位与文档指引。灵元开发完整步骤（创建模块 → 实现启动类 → 编写 ling.yml）见 改造指南·灵元开发。