架构分层 灵元定义 演进路径 真实验证 控制面 接入指南 边界声明 GitHub 仓库
JVM 运行时微观治理 · 进程内演进基座

让长期运行的 JVM 系统安全地持续演进

外部平台管服务之间(K8s / 网关 / Service Mesh),灵珑管 JVM 进程内部。将模块加载、契约切流、在途排空与 Metaspace 彻底回收闭环在单进程中,与云原生架构协同互补,而非零和替代。

单 JVM 内治理 Spring Boot 2.7 (默认) / 3.5 JDK 8 (默认) / 17 Apache-2.0 Version 0.4.7 (Pre-1.0)
单进程 JVM 运行拓扑示意 ● 运行时状态受管
宿主应用 / 灵核 (LingCore) PID: 38402
Spring Boot 容器基座 · Shared API 契约门面 · Actuator / 控制面接入点
契约路由与权重分流 (Contract Routing)
灵元 v1 基线 85%
ClassLoader: 独立隔离
状态: RUNNING · 稳定承载
灵元 v2 金丝雀 15%
ClassLoader: Child-First
状态: 动态加载 · 信号观察中
排空与资源回收 (awaitIdle & Drain)
退出保障:Metaspace 可证回收 ClassLoader 归零
排空在途请求 → 卸载灵元 Context → 关闭 ClassLoader → GC 触发回收
K8s 治理进程之间 灵珑治理进程之内
384 → 0
SeaTunnel ClassLoader 残留
144 个批作业 3×3 矩阵实测清零
96.3%
类元数据 (Metaspace) 卸载率
彻底消除类加载器历史泄漏
0 行
RuoYi 原业务核心源码修改
6 个模块解耦拆分,透明接管
< 1s
在途请求平稳排空
毫秒级优雅切流,零停机抖动
架构生态位

灵珑补的是进程内部,不是分布式系统本身

不要在“不可变容器”和“单机热更”之间做零和博弈。分布式平台管宏观,灵珑管微观,两者是天然的纵深协同关系。

宏观层 · 进程之间

K8s / Spring Cloud / 网关

负责跨机器维度的部署调度、网络路由、服务发现与副本级滚动更新。

  • 最小粒度:整套 Pod / 完整容器实例
  • 更新代价:全量重启、冷启动预热、连接池重建
  • 适用场景:大版本发布、容量扩缩容、节点级故障容灾
微观层 · 进程之内

灵珑 LingFrame

负责单个 JVM 进程内的模块边界隔离、动态类加载、权重路由与零泄漏退出。

  • 最小粒度:单个业务灵元(JAR 级)
  • 更新代价:长连接不断、无冷启动抖动、毫秒级在途排空
  • 协同模式:先在进程内小流量验证,确认无泄漏再打入下代 Docker 镜像
工程实体

灵元:不是概念口号,是有物理边界的运行单元

一个灵元就是一个独立的业务 Jar 包,拥有专属的 `LingClassLoader` 与生命周期守卫,通过契约与主进程安全交互。

最小灵元的工程结构

灵元包含自身业务代码、独立 ClassLoader,以及根路径下的 ling.yml 描述清单:

# 1. 描述清单:src/main/resources/ling.yml
id: user-ling
version: 1.0.0
description: 用户领域业务灵元
mainClass: com.example.user.UserLingApplication

// 2. 灵元主入口:标准 Spring Boot,零接口侵入
@SpringBootApplication
public class UserLingApplication { }

// 3. 契约服务实现:通过 @LingService 暴露能力
@Component
@LingService(version = "1.0.0")
public class UserQueryServiceImpl implements UserQueryService {
    @Override
    public Optional<UserDTO> findById(String id) {
        return Optional.of(new UserDTO(id, "Alice"));
    }
}
1. 独立类型隔离 (LingClassLoader) 采用独立子 ClassLoader 模型,各灵元私有依赖版本互不冲突,彻底终结 Jar 包冲突。
2. 消费者驱动契约 (Consumer-Driven) 接口由消费者声明,灵元用 @LingService 暴露,宿主用 @LingReference 动态代理注入。
3. 可证生命周期 (Lifecycle) INSTALLING → RUNNING → STOPPING (排空) → UNLOADED → GC 可证回收。
演进路径

从接入到退出,步步可验证

旧代码先不动,新功能以灵元方式切入。切流、灰度、排空与回收全部有审计日志和指标跟踪。

01

基线保留

无需重构存量系统,保留现有实现作为安全保底。

02

隔离加载

新灵元以独立 ClassLoader 加载,依赖完全内聚。

03

权重切流

契约路由小步放量(如 5%),实时观察业务与 JVM 信号。

04

在途排空

若遇异常,1秒内收回流量并排空处理中请求,瞬间切回旧版。

05

安全回收

注销上下文,解除类加载器引用,监控 Metaspace 安全释放。

模式 1 · 存量业务透明接管模式 Controller 归属于灵核底座原样复用(0 源码修改),通过灵核 AOP / @LingReference 动态代理;灵核默认实现 100% 自动兜底。
模式 2 · 新业务契约门面模式 灵核提供轻量门面统一鉴权、限流与入参校验,通过 @LingReference 动态路由分发到下游灵元,统一熔断保底。
模式 3 · 新业务自包含独立端点模式 灵元内部自包含 Spring MVC 端点,灵珑微内核动态注册与注销端点,随装随用,卸载时即时注销零残留。
真实验证

用事实回答两个最严苛的拷问

一个案例回答“类加载器到底能不能回收干净”;另一个案例回答“在真实业务系统里侵入性到底有多大”。

SeaTunnel 实战

类元空间能否彻底卸载?

在 classloader-cache-mode=false 验证前提下,挂载 Java Agent 针对 144 个批作业持续观察 ClassLoader 清理与 Metaspace 变化。

ClassLoader 残留实例 384 → 0
类元数据卸载率 96.3% (0.14% → 96.3%)
验证规模 144 个作业 · 3×3 矩阵
查看 v0.3.1 验证说明 边界说明:SeaTunnel 默认 cache-mode=true 的全局共享连接器缓存常驻场景不在上述清理承诺范围内。
RuoYi-Vue 示范

存量业务接入是否足够低侵入?

以国民级若依单体应用为样本,将存储、导出、短信、通知等拆为 6 个灵元,验证业务解耦可行性。

原业务源码修改 0 行
拆分独立灵元 6 个功能包
胶水代码代价 仅声明薄门面与注解,业务零修改
查看 RuoYi 实践源码 实战说明:示范项目用于展示透明接管与契约门面的落地姿势,所有代码与测试在 GitHub 完全公开复现。
运行管控

状态、动作与证据同屏可见

灵珑提供轻量级控制面,既支持无 UI 的纯配置化与 Actuator 自动化管控,也支持开箱即用的可视化 Dashboard。

控制面能力

不只看状态,更看退出证据

控制面不替代企业已有的发布流水线,而是负责将灵元安装、切流权重、状态指标、SSE 实时事件与审计日志统一呈现。

动态切流:按版本百分比无损滑动切流
在途排空:awaitIdle 毫秒级请求 drain 观察
资源体检:Metaspace、线程池、GC 泄漏实时诊断
双入口管控方式 ● 生产就绪
方式 1:可视化 Dashboard(可选依赖) 开发与灰度测试阶段,一键打开 /dashboard.html 直观完成灵元拖拽安装与流量滑动。
方式 2:无 UI 纯生产模式 (Headless) 生产环境无需暴露 Web UI,直接通过 Spring Boot Actuator 端点或配置中心(Nacos/Apollo)推送规则。
安全守卫与权限 生产 Token 默认 fail-closed;灵元上传支持验签与二次密码确认,防误触。
快速开始

选择适合你的接入路径

先在本地验证运行路径,确认契约与边界后,再决定是否集成到自己的业务主干。

路径一 · 5 分钟上手

跑通本地 Minimal 示例

克隆官方主仓库,运行预置好的 Spring Boot 示例,打开本地控制台观察灵元切流全过程:

# 编译并运行官方示例
mvn -pl lingframe-examples/lingframe-example-lingcore-app -am package -DskipTests
cd lingframe-examples/lingframe-example-lingcore-app
mvn spring-boot:run

# 打开本地控制面
http://localhost:8888/dashboard.html
路径二 · 接自己的系统

Maven Central 引入 Starter

已正式发布至 Maven Central,无需本地编译框架,声明官方 BOM 即可开箱即用:

<!-- 1. 声明官方 BOM (版本 0.4.7) -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>cn.lingframe</groupId>
      <artifactId>lingframe-bom</artifactId>
      <version>0.4.7</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- 2. Spring Boot 2.7 / JDK 8(默认) -->
<dependency>
  <groupId>cn.lingframe</groupId>
  <artifactId>lingframe-spring-boot2-starter</artifactId>
</dependency>
<!-- 若为 Boot 3.5 / JDK 17 则引入 lingframe-spring-boot3-starter -->
阅读详细接入文档
接入前确认

把边界写在前面,信任才有落点

灵珑目前处于 Pre-1.0 阶段。请在测试环境充分验证自己的上下文与依赖,再决定生产推行范围。

它负责什么

单个 JVM 进程内的类加载隔离、版本并行运行、契约路由分发、在途排空与安全卸载回收。

它不替代什么

跨机器容器调度(K8s)、分布式链路追踪、服务网格路由。它不是完全隔绝系统调用的沙箱,不防恶意黑客攻击代码。

上线前务必验证(设计边界)

数据源双轨制:灵核托管连接池时微内核通过单连接穿透原生支持单机本地 ACID;灵元自建独立池需走 EventBus 最终一致。

已进入共享边界的 Shared API 契约不支持热卸载;未在生命周期中显式清理的自定义线程池与 ThreadLocal 不在自动回收承诺内。