LiteFlow
  • whats new
铂赛东
2026-07-25
目录

🚀whats new in v2.16.1

# 前言

2.16.0 发布时，我们把 AI Agent 做成了可以参与编排的 LiteFlow 组件。2.16.1 则重做了 LiteFlow 已经使用多年的外置规则架构。

这次最直观的变化，是配置少了。

过去接入 SQL 规则配置源，需要配置连接信息、轮询参数，再逐个填写 chain 表、script 表以及每一个字段的映射，完整配下来有二十多项。换成 2.16.1 的 Rule-DB 后，单数据源的 Spring Boot 项目通常只需要增加一个依赖，Rule-DB 专属配置可以一行都不写。

配置从二十多项缩到接近 0 项，是最容易看见的变化。更大的变化发生在运行时：存储成为权威源，规则按需加载，多节点有统一的对账机制，规则发布也有了正式 API。这些能力放在一起，才是我们重做这套架构的原因。

这一版同时新增了 liteflow-metrics，chain、node 和 slot 的运行数据可以直接接入 Micrometer、Prometheus 和 Grafana。

# Rule-DB：让存储成为规则的权威源

# 先看配置：二十多项，现在几乎是 0

拿原来的 SQL 插件来说，一份包含规则刷新和脚本支持的配置大致是这样：

liteflow:
  rule-source-ext-data-map:
    url: jdbc:mysql://localhost:3306/liteflow
    driverClassName: com.mysql.cj.jdbc.Driver
    username: root
    password: 123456
    applicationName: order-service
    sqlLogEnabled: true
    pollingEnabled: true
    pollingIntervalSeconds: 60
    pollingStartSeconds: 60
    chainTableName: chain
    chainApplicationNameField: application_name
    chainNameField: chain_name
    elDataField: el_data
    routeField: route
    namespaceField: namespace
    chainEnableField: enable
    scriptTableName: script
    scriptApplicationNameField: application_name
    scriptIdField: script_id
    scriptNameField: script_name
    scriptDataField: script_data
    scriptTypeField: script_type
    scriptLanguageField: script_language
    scriptEnableField: enable

这些配置有它当时的价值：旧插件可以适配任意已有表结构。但大多数项目并不需要如此自由，只是想把规则放进数据库，然后稳定地跑起来。

Rule-DB 直接提供固定的存储结构和写入协议。它会复用容器中已有的 DataSource，连接池、账号、超时都沿用项目原来的配置；规则隔离名默认复用 spring.application.name。对于单数据源的 Spring Boot 项目，接入代码是下面这样：

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>liteflow-rule-db-sql</artifactId>
    <version>2.16.1</version>
</dependency>

然后就没有 Rule-DB 专属配置了。项目里原本的这一行会直接作为规则隔离名：

spring.application.name=order-service

如果项目本来就配置了 spring.application.name，新增的 Rule-DB 配置数量就是 0。

开发环境想让框架自动建表，再加一个可选开关：

liteflow.rule-db.sql.auto-init-table=true

生产环境建议由 DBA 按文档中的 DDL 建表，执行节点使用只读账号。无论哪种方式，都不再需要配置表名和二十多个字段映射。

配置少了，能力反而多了。新旧两套模式的差别可以直接放在一起看：

维度 原规则配置源 Rule-DB
规则以哪里为准 启动后主要依赖各节点 JVM 内的规则 存储始终是权威源，JVM 是运行缓存
接入配置 连接、轮询、表名和字段映射，SQL 插件完整配置二十多项 单数据源 Spring Boot 项目通常无需新增配置
规则加载 规则正文和脚本源码全量进入 JVM 启动只建索引和影子对象，正文首次执行时加载
多节点同步 各插件分别实现轮询或通知 变更感知加周期对账，统一维护版本水位
规则发布 使用方直接改存储，自行处理刷新 统一 RulePublisher，负责版本、指纹和变更记录
运行状态 需要业务自己补监控 /actuator/liteflow/ruledb 直接查看同步和加载状态

# 规则越多，Rule-DB 的优势越明显

在 Rule-DB 模式下，存储始终是规则的权威源。JVM 启动时先读取规则清单，为 chain 和 node 建立轻量的影子对象；真正的 EL、脚本源码和编译产物，等到第一次执行时再从存储加载。

加载后的内容放进 Caffeine 有界缓存，默认容量是 500 条 chain。缓存按访问热度淘汰，某条规则被淘汰后会退回影子状态，下次执行再重新加载。

原来的模式下，库里有多少规则，每个节点就要持有多少规则正文和脚本源码。Rule-DB 把常驻内存的重点从“全部规则”改成了“当前热点”。规则只有几百条时，这个差别可能不明显；规则达到几千、几万条，并且部署了很多执行节点以后，内存占用和启动加载的差距会越来越明显。

影子对象、版本号和状态索引仍然会随规则总量增长，所以 Rule-DB 并没有让规则清单本身变成零成本。大规模上线前，仍然要按真实规则数量测试启动耗时和堆内存。

# 多节点终于有了一套统一的收敛机制

规则变更的同步分成两层：

  • SQL、PostgreSQL、MongoDB、Redis 通过 seq 序号轮询感知变更，默认每 3 秒一次。
  • ZooKeeper、etcd 使用 watch，Nacos 使用 Listener，变更可以直接推送到执行节点。

无论使用哪种后端，Rule-DB 都会默认每 60 秒做一次全量清单对账。通知遗漏、序号不连续或增量应用失败时，只要存储仍然可用，对账就能重新校准节点状态。Rule-DB 提供最终一致性，不能让全集群在同一时刻切换规则。

这套机制还带来了统一的观察入口。/actuator/liteflow/ruledb 会给出同步水位、shadow、ready、stale、failed 等状态数量和加载失败明细。发布一条规则后，不需要再靠猜测判断某个节点有没有跟上。

# 发布规则也不用再手写 SQL

旧 SQL 插件允许适配已有表，规则怎么写入、版本怎么管理、什么时候通知执行节点，都是使用方自己的事情。Rule-DB 把写入也纳入了协议。

七个后端共用 RulePublisher 发布接口。管理后台可以单独依赖对应的 Rule-DB 模块，不需要启动 FlowExecutor，也不依赖全局 LiteflowConfig。

try (RulePublisher publisher = RulePublisherFactory.create(
        SqlPublisherConfig.builder()
                .applicationName("order-service")
                .dataSource(ruleDataSource)
                .build())) {
    PublishResult result = publisher.publishChain(PublishChainRequest.builder()
            .chainId("orderChain")
            .el("THEN(a, b)")
            .expectedVersion(0L)
            .build());
}

expectedVersion 用于乐观锁。传 0 表示只允许新建；传正数表示当前版本匹配时才允许更新；不传则执行 UPSERT。版本自增、内容写入和变更记录由各后端在自己的原子操作里完成。

一次 API 调用只发布一条 chain 或一条 script。目前还没有把多条规则作为一个整体同时切换的事务接口。

# 首批支持七个后端

2.16.1 首批提供七个 Rule-DB 后端：

模块 存储 变更感知方式
liteflow-rule-db-sql MySQL / MariaDB seq 轮询 + 周期对账
liteflow-rule-db-postgresql PostgreSQL seq 轮询 + 周期对账
liteflow-rule-db-mongodb MongoDB seq 轮询 + 周期对账
liteflow-rule-db-redis Redis seq 轮询 + 周期对账
liteflow-rule-db-zk ZooKeeper watch + 周期对账
liteflow-rule-db-etcd etcd watch + 周期对账
liteflow-rule-db-nacos Nacos 2.x 及以上 Listener + 周期对账

其中 PostgreSQL 和 MongoDB 是这次新增支持的存储，原来的规则插件里没有对应实现。

不论选择哪个后端，执行侧的代码都不需要改变：

LiteflowResponse response = flowExecutor.execute2Resp("orderChain", null);

规则第一次执行时回源加载，之后命中本地缓存。变更到达节点后，旧缓存会被标记为失效，下一次执行加载新版本；正常的缓存命中不会增加远程读取。

完整接入步骤见 Rule-DB 文档。

# 新项目，我们明确推荐 Rule-DB

如果新项目需要把规则放在数据库、Redis、ZooKeeper、etcd 或 Nacos 中，建议直接使用 Rule-DB。它的配置更少，规则发布方式统一，多节点同步和可观测性也完整得多。旧插件会继续维护，主要用于保障已有项目稳定运行。

已经在用旧插件的项目，需要把迁移当成一次架构迁移来评估。两套模式使用完全不同的规则存储和运行协议，修改配置前缀并不能完成迁移：

  • 旧插件适配业务已有的表、键和配置结构；Rule-DB 使用自己定义的表、版本号、变更日志和序号协议。
  • 旧管理后台通常直接写数据库或配置中心；迁移后必须改为调用 RulePublisher。
  • 旧模式启动时全量加载；Rule-DB 启动建清单，执行时按需加载，压测和容量评估方式也会变化。
  • 两套模式不能在同一个 FlowExecutor 中同时运行。切换时要移除旧插件和 liteflow.rule-source，只保留一个 Rule-DB 后端。

对已经深度使用旧插件的项目，这次迁移成本不会低。旧表定制得越多、管理后台和原存储耦合得越深，改造量就越大。

2.16.1 没有提供自动迁移器。规则数据需要经过受控程序读出，再通过 RulePublisher 写入新存储；切换前还要核对规则数量、正文、脚本类型、namespace 和 route，完成关键 chain 回归、灰度和回滚预案。

所以我们的建议很直接：新项目优先用 Rule-DB；老项目如果规则不多、单节点运行、现有插件一直稳定，可以继续使用；已经遇到配置复杂、规则量大、JVM 内存高或多节点刷新难确认的问题，值得把 Rule-DB 迁移提上日程。

完整迁移步骤见 限制与迁移。

# 上生产前还要确认这些边界

上生产前要确认以下限制：

  1. 它提供最终一致性，不提供多节点原子切换。规则发布后的收敛窗口内，不同节点可能短暂执行不同版本；已经开始的流程会继续使用原来的条件树。
  2. 七个 Rule-DB 后端同一时刻只能选择一个，并且不能和 liteflow.rule-source 同时使用。配置冲突时应用会直接启动失败。
  3. MongoDB 必须使用副本集或分片集群，因为发布过程依赖多文档事务。Standalone 模式不支持。
  4. Redis Cluster 必须配置 key-hash-tag，确保 Lua 操作涉及的键落在同一个 slot。Nacos 则把单个应用的规则保存在同一份 Catalog 中，需要关注服务端单配置容量。
  5. 2.16.1 暂时没有 Apollo 后端和管理界面。使用 Apollo 的项目请继续使用原插件。

更完整的一致性和性能说明见 Rule-DB 文档。

# 指标监控：接入现有的可观测体系

2.16.1 新增 liteflow-metrics 模块，用 Micrometer 记录 LiteFlow 的运行数据。

LiteFlow 原有的简单监控会定期在日志中输出组件平均耗时，适合快速排查，但不方便看趋势或配置告警。新的指标模块把测量值交给 Micrometer，再由 Prometheus、Grafana 或项目里已有的监控后端处理，不单独维护一套历史统计。

目前提供三类指标：

  • chain 和 node 的执行次数、成功与失败次数、总耗时和最大耗时；
  • chain 和 node 的当前在途执行数、最长在途耗时，以及按异常类型统计的失败数；
  • 已注册的 chain 数、node 数、slot 池容量和当前占用量。

这些指标足够计算 QPS、平均耗时和错误率。P95、P99 需要额外开启直方图或客户端分位统计，默认的 count、sum、max 不能直接算出分位数。

# Spring Boot 快速接入

liteflow-metrics 已经是 liteflow-spring-boot-starter 和 liteflow-spring-boot4-starter 的传递依赖，Spring Boot 项目不用单独引入。要接 Prometheus，只需增加 Actuator 和 Prometheus Registry：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

再开放端点：

management.endpoints.web.exposure.include=liteflow,prometheus

启动应用后可以直接检查：

curl http://localhost:8080/actuator/prometheus | grep liteflow_

源码仓库的 docs/metrics-integration/ 目录还提供了一套 Prometheus + Grafana 示例配置，执行 docker compose up -d 即可启动，并自动导入一块包含六个面板的 LiteFlow 仪表盘。这套配置只用于本地演示，匿名访问和默认口令都不适合生产环境。

接入细节见 指标监控快速接入。

# /actuator/liteflow 结构端点

除了供 Prometheus 抓取的 /actuator/prometheus，这一版还提供了 LiteFlow 自己的 /actuator/liteflow 端点。

它直接读取 FlowBus，可以查看 chain 的 EL、node 的类型和实现类、node 被哪些 chain 引用，也能看到从未执行过的 chain 和 node。排查规则结构时，不用再从启动日志里找完整定义。

启用 Rule-DB 后，/actuator/liteflow/ruledb 还会返回当前同步水位、各状态目标数量以及加载失败明细。某个节点没有及时加载新版本时，可以先从这里确认它处于 shadow、ready、stale 还是 failed 状态。

指标默认只使用 chain、node、状态和异常类名等低基数标签，不包含 requestId 或完整异常信息。实际的时间序列数量仍然会随 chain 和 node 的数量增长，规则规模很大的项目应在上线前评估监控后端的容量。相关建议见 性能影响与基数控制。

# 采用建议

升级到 2.16.1 不会自动启用 Rule-DB，原有六个 liteflow-rule-* 插件继续可用，也会继续维护。已有项目可以先完成常规版本升级，再单独安排 Rule-DB 的迁移评估。

新项目只要需要外置规则存储，建议直接从 Rule-DB 开始，可以先跑一遍 SQL 快速开始。已经在生产使用旧插件的项目，如果正在承受规则配置复杂、JVM 内存增长或多节点刷新难确认的问题，请按 限制与迁移 做一次完整演练后再切换。

帮助我们改善此文档 (opens new window)
🚀What's New In LiteFlow v2.16.0?

🚀What's New In LiteFlow v2.16.0?→

Theme by Vdoing | Copyright © 2020-2026 铂赛东 | MIT License
沪ICP备18012955号-2