版本支持：v2.16.1+

限制与已知边界

下面这些v1的限制，用之前请先看一眼，免得误用。

1、和rule-source互斥。同时配置liteflow.rule-source和liteflow.rule-db.*会直接启动报错，Rule-DB和旧插件模式不能混用。

2、七个Rule-DB插件同一时刻classpath里只能有一个。liteflow-rule-db-sql、-postgresql、-mongodb、-redis、-zk、-etcd、-nacos七选一，同时存在多个会启动报错。

3、Redis Cluster必须配key-hash-tag。发布用的Lua脚本会触碰4个键，分别是chain:{id}、chain-ids、seq、changelog，多键EVAL要求它们落在同一个slot，否则Cluster会报CROSSSLOT错误。

• cluster模式，也就是多地址且没配master-name的情况：key-hash-tag是必填的，不配的话建连时直接抛ConfigErrorException，不会带病启动。
• 单机和哨兵模式：没有slot约束，可以不配；配了也会生效，但它会改变键布局，所以已经有数据的实例上不要随意增删这个配置。

4、MongoDB必须支持多文档事务。运行时的Manifest快照读取和Publisher都用到事务，所以只支持副本集或分片集群，standalone不支持。

5、Nacos需要Server 2.x，而且受单配置容量约束。1.x没有本模块要用的CAS发布能力。一个applicationName的全部正文、元数据和最后变更记录都在同一份Catalog里，实际可用上限同时受Nacos服务端nacos.core.config.max-size、数据库字段以及代理网关的限制。模块不会自动分片，接近上限就会发布失败。

6、一致性语义是最终收敛、秒级窗口，不是原子切换，也不是线性一致。详见一致性与收敛模型。

7、v1还没提供的实现，SPI都已经就位，留作后续：

• Apollo的Rule-DB实现。core里的RuleRepository SPI已经定义好了，后续可以按同一套契约扩展。
• enableChain和enableScript这两个API。停用目前靠直写存储。
• 节点实例ID的持久化，也就是旧sql插件里NodeInstanceIdManageSpi那部分能力。
• 管理UI和控制台。v1只提供Publisher API和写入规范。

8、并发发布语义。不传expectedVersion时是无条件UPSERT；传0表示仅当不存在时才创建；传正数表示按版本做CAS。七个后端都保证同一条存续记录的成功发布版本单调递增，而删除后用相同id重建时，版本从1开始。

9、应用元数据和Rule-DB的id冲突会导致启动失败。通过LiteFlowChainELBuilder手动build、且id不在存储清单里的chain可以共存。但如果手写的chain和存储里的chain同id，或者应用注册的script node和存储里的script同id，Rule-DB初始化时会抛ConfigErrorException，它不会去覆盖应用对象。所以请保证两边的id集合不相交。

发布参数与后端限制矩阵

统一请求对象会校验必填字段，各后端还会按自身的表结构或键布局做额外校验。下面是最容易踩到的硬边界。长度都按Unicode code point计，只有SQL的正文限制是按UTF-8字节数算的：

后端	id和字段限制	正文与键限制
SQL（MySQL DDL）	application-name 64，chain和node id 128，namespace 64，脚本名128，type和language 32，table-prefix最长54且只能用ASCII字母、数字、下划线	el、route、script分别不能超过65,535个UTF-8字节，对齐TEXT类型
PostgreSQL	application-name 64，chain和node id 128，namespace 64，脚本名128，type和language 32，table-prefix最长52	正文用的是PostgreSQL的TEXT，仍然受数据库、驱动和运维设置的限制
MongoDB	application-name和id 128，namespace 128，脚本名256，type和language 64，database只允许ASCII字母、数字、下划线、连字符，collection prefix最长64	单文档和事务大小受MongoDB服务端限制
Redis	id最长128，且不能包含:或空白，namespace 64，脚本名128，type和language 32	Cluster必须配key-hash-tag，正文还受Redis单值、Lua和客户端的限制
ZooKeeper	applicationName和rootPath的每个segment都不能包含/、..或控制字符，rule id不能为空或包含/	单个编码后的meta或content znode上限960 KiB
Etcd	rule id不能为空或包含/，applicationName和rootPath会直接参与key前缀	受etcd请求大小、配额和历史压缩设置的限制
Nacos	data-id-prefix、application-name、group只能包含字母、数字、_、-、.、:	一个应用的全部规则在同一份Catalog里，受Nacos单配置容量限制

跨后端迁移的时候，请按目标后端里更严格的那个限制提前校验。不要假设在MongoDB或PostgreSQL能写进去的id和正文，原样搬到Redis、ZooKeeper或SQL也一定能写进去。

从旧规则插件迁移

2.16.1没有提供把liteflow-rule-*的数据自动转成Rule-DB存储的迁移器。推荐的做法是写一个受控的迁移程序，读出旧数据，再调用目标后端的统一RulePublisher。不要自己去拼Rule-DB的表、键或者Catalog。

具体步骤：

1. 定好唯一的application-name，在生产等价的环境里创建目标存储结构，并用Publisher完成必要的表、索引或路径初始化。
2. 冻结旧管理后台的写入，记录迁移基线。发布顺序上先脚本和叶子子chain，再发布引用它们的父chain。迁移程序用expectedVersion=0，遇到重复id就停下来，不要静默覆盖。
3. 对比chain和script的数量、id、正文MD5、namespace和route，然后用和生产相同的Java组件、脚本插件及配置，跑一遍冷启动和关键chain的回归测试。
4. 切换执行应用时，移除旧的liteflow-rule-*插件和liteflow.rule-source，classpath里只留一个Rule-DB后端。不要让新旧插件在同一个FlowExecutor里双读。
5. 保留旧存储的只读快照，直到观察期结束。需要回滚时，把应用依赖和配置回退到旧插件，不要在同一个应用里临时混用两套权威源。

如果迁移期间业务还需要改规则，那就在切换前再冻结一次并重做增量，或者由上层管理系统实现一套经过验证的双写。Rule-DB本身不提供跨旧插件的双写事务。

备份恢复

• 备份必须覆盖同一后端的完整协议状态：SQL和PostgreSQL的四张表（包括change_log和change_lock）、MongoDB的四个Collection、Redis的内容键、id集合、seq和changelog、ZooKeeper和etcd的meta与content，以及Nacos的整份Catalog。只恢复正文而不恢复版本和序号，会破坏收敛判据。
• 不要把version更低的备份在线覆盖到仍在运行的同一个application-name上，因为节点可能把它当成迟到的旧版本直接忽略。完整的灾备恢复应该先停掉这个应用的Publisher和执行节点，原子恢复协议状态之后再重启；另一种做法是恢复到一个新的application-name然后切流。
• 在线回滚单条规则时，请通过Publisher把旧正文发布成一个更高的新版本。不要直接把version改小，也不要只改正文而不更新MD5和变更日志。
• SQL和PostgreSQL恢复之后要确认change_lock里lock_id = 1这行还在；Redis和MongoDB要确认sequence不低于保留下来的changelog；Nacos的Catalog必须整体恢复，并通过正文MD5、sequence和lastChange的校验。
• 恢复完先启动一个执行节点，检查一下Rule-DB快照，冷加载关键chain，观察至少一个reconcile-seconds周期，再逐步恢复流量。

执行账号与发布账号

建议把只读的执行账号和可写的Publisher账号分开。精确的ACL语法随后端和部署方式而异，这里给出能力边界：

后端	执行账号	Publisher账号
SQL / PostgreSQL	对规则表、日志表和锁表有SELECT。如果开了auto-init-table，还需要DDL权限	SELECT、INSERT、UPDATE、DELETE，以及对change_lock加行锁的权限。初始化时需要建表权限
MongoDB	读取四个Collection，并允许事务和快照会话	读写四个Collection、执行事务。首次初始化还需要创建Collection和索引
Redis	读取内容、id集合、seq和changelog所需的命令	在相同key前缀上执行发布Lua及其读写命令
ZooKeeper	四棵meta和content路径及其子节点的递归读取和watch	创建、读取、更新、删除这些路径，以及执行multi-op
Etcd	规则前缀的Range和Watch	同一前缀的Range、Put、Delete和Txn
Nacos	读取Catalog和注册Listener的权限	读取Catalog，以及用CAS发布配置的权限

要注意执行侧一旦配了自动建表或自动初始化，它就不再是严格只读的账号了。生产环境如果要求最小权限，应该先用Publisher或者让DBA把结构初始化好，然后关掉自动初始化，改用只读的执行账号。