灵珑 · LingFrame

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

中文 | English

系统运行久了，业务不停迭代，代码越来越庞大，结果谁也不敢轻易改动。

灵珑是一个面向长期运行系统的 JVM 运行时治理框架。它让你在系统运行期间，把新功能或老模块隔离成独立的灵元（Ling——可独立加载、运行、治理与卸载的业务单元），而不必为了每一次演进重新打包部署整个系统。

它不决定你的系统拆成几个服务，它解决的是每个 JVM 进程内部如何持续演进。它可以在系统生命周期的任何阶段介入——不需要立刻推翻重构，也不用急着拆微服务。

定位示意图（灵珑在系统架构中的层级）：

               系统架构维度（进程间划分）
     单体         模块化单体        微服务
       │               │              │
       └───────────────┼──────────────┘
                       ▼
               任何 JVM 进程内部
                       │
                 灵珑运行时治理
                       │
             ┌─────────┼─────────┐
             ▼         ▼         ▼
           灵元 A    灵元 B    灵元 C
             │         │         │
           路由 · 灰度 · 隔离 · 卸载

在实际业务中，最怕上线后出事故。灵珑推荐一种渐进式的改造方式：

老实现（留在灵核——即你的主应用进程 / 或已有灵元 v1）  ──继续扛流量──►
                                                                  │
           新功能写成 灵元 v2（尽量不动老代码）  ──权重/灰度切入──►  观察
                                                                  │
                           数据/体验/故障面 OK？ ──┬─ 否 → 收回权重 / 卸载 v2
                                                 └─ 是 → 再决定老路径瘦身或下线

要点：

• 发布更独立：快节奏和慢节奏的功能不用硬绑在一起发布。新版本可以单独安装、单独切流、单独卸载。
• 上线不靠赌：不必在信息不全时做“全量替换”的大爆炸迁移。先并存、多观察，用证据说话，退路随时都在。
• 收敛更从容：老路径是否下线，不需要在发布当天决定，而是在验证充分之后自然完成。

在灵珑微内核架构体系中，业务落地与开发分为三大标准模式：

┌────────────────────────────── 灵核（你的主应用进程） ──────────────────────────┐
│  Shared API（进程级公共契约 — 加载后冻结；已进入共享边界的契约不支持热更新/热卸载）    │
│                                                                              │
│   ┌──────────┐   治理主链：路由 · 守卫 · 灰度 · 韧性 · 权限 · …             │
│   │ Dashboard│ ─────────────────────────────────────────────────────────────►│
│   └──────────┘                         │                                     │
│                                        ▼                                     │
│              ┌──────── 灵元 A v1 ──────┐   ┌──── 灵元 A v1.1-canary ────┐    │
│              │  LingClassLoader（子）  │   │  LingClassLoader（子）     │    │
│              └─────────────────────────┘   └────────────────────────────┘    │
│                                                                              │
│   实例层 = 某个版本的真实生命周期                                            │
│   运行时层 = 某个灵元 id 的宏观呈现                                          │
└──────────────────────────────────────────────────────────────────────────────┘

设计立场：WHY · MANIFESTO

上图是静态分层。不停机替换灵元版本是灵珑的核心卖点——它是一条完整时序：部署新版本 → 权重切流 → 旧实例排空卸载。完整时序图见 docs/images/hot-deploy-sequence.svg。

• 方式一：在线体验（零门槛） 直接访问 灵珑 Live Demo，即可在线操作 Dashboard 体验灵元治理与切流，无需本地环境。 访问令牌：lingframe。

• 方式二：本地跑通（开发评估） 需要 JDK（示例默认 8；支持线可用 17）与 Maven。

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：http://localhost:8888/dashboard.html

curl http://localhost:8888/lingframe/dashboard/lings
curl http://localhost:8888/user-ling/user/listUsers

命令细节：最短上手

跑起来后建议：

1. 打开 Dashboard，确认示例灵元已加载
2. 再打一笔业务请求，确认链路可达
3. 看监控 / 治理页是否有真实信号
4. 多版本时用流量权重放量，不要用运行时状态代替切流

点击截图即可进入在线体验；线上环境已内置示例灵元，支持实时查看生命周期、路由切流与模拟演练。

示例两条路径（总览见 lingframe-examples/zh-CN/README.md）：

lingframe-seatunnel-agent 是基于 LingFrame 构建的独立开源 Java Agent，为 SeaTunnel 提供 ClassLoader 生命周期清理和可观测治理能力。业务代码无需修改，但需要挂载 Java Agent 并配置 SeaTunnel。

在 classloader-cache-mode=false 的测试前提下，CI 使用 Fake / MySQL / Kafka × Console / MySQL / Kafka 的 3×3 矩阵，并发交错运行 144 个 Job。Agent 组 Metaspace 增长 14.06 MB，观测到的 SeaTunnelChildFirstClassLoader 残留为 0，Class 元数据卸载率为 96.3%；无 Agent 对照组分别为 391.16 MB、384 个残留和 0.14%。完整复现流程与原始数据见验证报告。

示例迁徙提示：原 lingframe-example-ling-mall 与 lingframe-example-saas-mall 示例已下线， 托管数据源与事务传播示例请参考 docs/zh-CN/managed-datasource-and-transaction.md， 非 Spring 灵元入口参考可用 lingframe-example-ling-native。

• 已经运行多年、不能轻易停机或重写的单体系统；
• 希望逐步引入隔离、灰度、限流、熔断、权限与审计的团队；
• 想在不彻底推翻现有系统的前提下，先在进程内建立运行秩序。

• 新项目：希望从第一天开始就按“灵元”划清业务边界，避免未来演变为无法维护的泥潭；
• 庞大的微服务内部：微服务内部代码膨胀为“分布式单体”时，在服务进程内部建立演进边界；
• 需要按不同迭代节奏独立发布和治理多模块的系统。

• 把它当成微服务替代品：灵珑管的是服务内部代码的演进，不管跨服务网络通信。两者是互补关系而非替代关系；
• 把它当成纯前端插件市场或低代码装配平台；
• 希望接入一个框架就自动消除业务复杂性。

• 当前公开能力集中在单进程内的灵元隔离与治理；
• Shared API 是进程公共契约：新包可以预加载，但已进入共享边界的契约不支持热更新或热卸载（这是保证类型安全的架构设计取舍，破坏性变更仍需重启进程）；
• 存储治理主要覆盖 Spring 注入的 DataSource，手写的原生 JDBC 连接无法拦截；
• 危险 API 扫描是加载阶段的提醒信号，并不是 JVM 级别的完整安全沙箱；
• 验证主路径为 Spring Boot 2.7 + JDK 8（示例默认）；Spring Boot 3 + JDK 17 为支持线；
• 0.4.7 版本仍处于 Pre-1.0 阶段：建议上线前先在测试环境充分评估，并对照 生产配置清单 进行核验。

LingFrame 已正式发布至 Maven Central 全球中央仓库，无需拉取或本地编译框架源码，在项目中直接声明 BOM 即可开箱即用：

Spring Boot 2.7 / JDK 8（默认路径）：

<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>

<dependencies>
  <dependency>
    <groupId>cn.lingframe</groupId>
    <artifactId>lingframe-spring-boot2-starter</artifactId>
  </dependency>
  <!-- 可选控制面 -->
  <dependency>
    <groupId>cn.lingframe</groupId>
    <artifactId>lingframe-dashboard</artifactId>
  </dependency>
</dependencies>

若走 Spring Boot 3 / JDK 17，改为 lingframe-spring-boot3-starter（本仓库构建请加 -Pspring-boot3）。

灵核 application.yml（骨架）：

lingframe:
  enabled: true
  dev-mode: true          # 仅本地；生产务必关闭
  ling-home: "lings"      # 已打包灵元目录
  # preload-api-jars: [ "path/to/shared-api" ]

引入 lingframe-dashboard 依赖后，必须显式设置 lingframe.dashboard.enabled: true 才会装配控制面。最小可运行配置：

lingframe:
  dashboard:
    enabled: true
    access-token:
      enabled: true
      token: "${LINGFRAME_DASHBOARD_TOKEN}"   # 生产必填，留空启动失败（fail-closed）
    storage:
      path: "/var/lib/lingframe/dashboard.db" # SQLite 持久化；生产指向独立可写目录

全量配置项与逐项说明：application-prod.yaml.example · 生产硬化清单：docs/zh-CN/production-hardening.md。

灵元 ling.yml（骨架）：

id: user-ling
version: 1.0.0
mainClass: "com.example.UserLing"

完整从零：docs/zh-CN/getting-started.md · 写灵元：docs/zh-CN/ling-development.md · 上线前：docs/zh-CN/production-hardening.md

大多数业务场景下，SQL、RPC、序列化等开销通常远高于治理链，因此框架本身一般不会成为主要瓶颈。

公开 JMH 样例（空业务体 / 反射终端；不是业务 SQL 或 RPC）：
benchmark-results-20260709-044113.txt

复现：lingframe-benchmark/README.md。上线请用自己的业务压测。

特别鸣谢 Gitee 官方与开源社区的推荐与支持！

感谢 Gitee 平台以及红薯老师为本土开源生态提供的优质土壤，让底层的轮子也能被看见。

本项目是 AtomGit G-Star 孵化项目。
感谢 AtomGit 平台对开源项目的支持与推广。

感谢技术社区 linux.do 社区的佬友们提供的宝贵讨论环境与技术反馈。 这里是目前国内最具极客精神的纯粹技术社区之一，非常推荐开发者朋友们加入交流。