# LingFrame-RuoYi

**Repository Path**: LingFrame/LingFrame-RuoYi

## Basic Information

- **Project Name**: LingFrame-RuoYi
- **Description**: 本项目是 LingFrame 生态的官方改造范例，展示如何用灵珑微内核对存量 Spring Boot 单体做零侵入运行时治理
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LingFrame-RuoYi

基于 [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue) `3.9.2` 的灵珑（LingFrame）灵核化改造演示项目。

> **声明**：本项目为第三方改造演示，非若依官方项目。若依原版代码遵循 [MIT LICENSE](LICENSE)（Copyright (c) 2018 RuoYi）。

> 本项目是 LingFrame 生态的官方改造范例，展示如何用灵珑微内核对存量 Spring Boot 单体做零侵入运行时治理。关于灵珑框架本身的设计理念与价值定位，请参阅 [灵珑主仓库](https://gitee.com/lingframe/lingframe)。

---

## 一、快速开始

### 1. 全量编译与自动化集成测试

```bash
# 执行全量自动化测试（包含单测、治理集成测试与微内核闭环验证）
mvn clean test
```

### 2. 启动灵核与控制面

```bash
# 启动灵核单体应用（默认端口 8080，Dashboard 控制面: /dashboard.html）
java -jar lingframe-ruoyi-lingcore/target/lingframe-ruoyi-lingcore.jar
```

### 3. 生产环境启动

```bash
# 生产环境使用 prod profile（关闭 dev-mode、强 token、严格安全模式）
java -jar lingframe-ruoyi-lingcore/target/lingframe-ruoyi-lingcore.jar --spring.profiles.active=prod
```

生产环境必需的环境变量见 [`docs/production-hardening.md`](docs/production-hardening.md) 上线前核验表。

### 4. 最小演示路径：体验热插拔

启动后按以下步骤体验灵元热插拔（无需重启）：

1. 打开 Dashboard 控制面：`http://localhost:8080/dashboard.html`（开发模式 token：`lingframe`）
2. 在灵元列表查看 6 个已自动加载的灵元（`ling-roots` 配置的目录自动扫描）
3. 将 `ling-storage-oss` 权重设为 100 → 文件上传切走阿里云 OSS
4. 将权重设为 0 → 自动回退灵核本地存储兜底
5. 热卸载 `ling-export-fast` → 导出回退原生 POI；重新部署 → 恢复流式导出

全程不停机、不重启、前端 0 感知。事件流实时查看：`http://localhost:8080/lingframe/dashboard/sse`

---

## 二、容器化部署

```bash
# 构建镜像（多阶段构建：灵核 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:latest
```

CI/CD 配置见 [`.gitlab-ci.yml`](.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-admin` jar 依赖引入，**源码不在本项目中，物理上零改动**。

### 新增代码统计

| 层 | 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。详见 [改造指南·三大模式选择指南](docs/改造指南.md#14-三大模式选择指南)。

| 维度 | 模式 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` 契约<br>• 灵核 `SysNoticeServiceImpl`<br>• 灵元 `NoticeV2ServiceImpl` | • 灵核/灵元双 Provider 双活<br>• 反向 Pinning 委托灵核 MyBatis 数据通道<br>• 动态权重分流、秒级回退与可证 GC 回收 | **0** | **0** | **0** |
| **2. 文件上传云化与热插拔** | **模式 1** | 接管 `POST /common/upload`<br>• 阿里云 OSS 灵元<br>• 腾讯云 COS 灵元 | • 前端 0 感知同路由无缝接管<br>• 秒级多云热替换、加权双活分流<br>• 热卸载自动回退本地磁盘保存 | **0** | **0** | **0** |
| **3. 大数据流式导出防 OOM** | **模式 1** | 接管 `POST /system/user/export`<br>• EasyExcel 流式导出灵元 | • 前端 0 感知同路由同参数无缝接管<br>• 边查边流式写出，常驻内存仅数兆<br>• 彻底杜绝 POI DOM 模型引发的 JVM OOM<br>• 热卸载自动回退原生 POI 导出 | **0** | **0** | **0** |
| **4. 多通道短信与验证码网关** | **模式 2** | 灵核门面 `POST /system/sms/sendCaptcha`<br>• 契约 `ISysSmsService`<br>• 灵元 `AliyunSmsServiceImpl`<br>• 灵核 `DefaultLocalSmsProvider` | • 灵核统一把控 60s 防刷与 Security 鉴权<br>• 控制台随时加权切流或热替换短信商<br>• 热卸载自动平滑回退本地控制台 Provider 兜底 | **0** | **0** | **新增薄门面** |
| **5. 敏感词合规检测与文本脱敏** | **模式 3** | 自包含端点 `POST /ling/filter/**`<br>• 灵元 `SensitiveFilterController`<br>• 内置 DFA 离线合规词库引擎 | • 灵核底座 0 契约、0 Controller<br>• 纯离线微秒级合规检测与脱敏<br>• 灵元加载动态挂载端点，热卸载干净注销 | **0** | **0** | **0** |

各场景的完整操作步骤与热插拔回滚见 [改造指南](docs/改造指南.md#一改造步骤)。

---

## 七、文档索引

| 文档 | 内容 |
|---|---|
| [改造指南](docs/改造指南.md) | 从若依原版到灵核化的完整路径：步骤、回滚预案、监控接入、踩坑说明、FAQ |
| [生产硬化清单](docs/production-hardening.md) | 生产环境配置硬化、密钥管理、上线前核验表、灵元上线流程 |

---

## 八、从零改造脚手架

若有自己的若依项目需要灵核化改造，可使用脚手架脚本快速生成底座结构：

```bash
./scripts/scaffold-lingcore.sh /path/to/RuoYi-Vue /path/to/output
```

生成的底座包含灵核模块骨架、灵元模板、配置占位与文档指引。灵元开发完整步骤（创建模块 → 实现启动类 → 编写 `ling.yml`）见 [改造指南·灵元开发](docs/改造指南.md#13-灵元开发3-步)。