Firefly v1.0.2

发布日期：2026-07-31

v1.0.2 聚焦边界清晰度和故障恢复。它没有引入大型 Web 框架，也没有改变 Netty 作为 Executor 主要通信通道的定位；本次工作主要把原本隐含在 HTTP 路径、Gateway 实现、插件加载和 JDBC 更新语句中的规则变成可验证的策略、状态机与维护流程。

Maven Central 状态

源码、版本元数据和发布检查已准备为 1.0.2。Maven Central 构件由 tag 驱动的发布流程上传；升级前请先在 Central Portal 确认 1.0.2 已完成索引。

主要变更

Admin HTTP 安全边界

AdminHttpPlugin 只负责装配和生命周期，路由、授权、请求读取、响应、审计和领域 Controller 已拆开。
RBAC 在路由注册时绑定声明式策略，不再由授权层用业务路径字符串推断权限。
请求体、分页和批量操作都有统一上限；非法 JSON、超限请求和未知路由返回稳定错误。
Admin HTTP 继续使用 JDK HttpServer，没有引入 Spring MVC、WebFlux 或其他大型 Web 运行时。

Netty 协议与背压

新增独立的 netty-protocol 发布模块，Gateway 与 Executor Client 共用明确的 wire model。
传输帧使用 Jackson JSON 编解码，不使用 JDK native serialization。
Gateway 协调逻辑从连接生命周期中拆出，结果持久化进入独立的有界队列。
队列饱和后在非 EventLoop 线程上执行有限延迟重试；重试容量或次数耗尽时产生可观察的最终拒绝。

调度与插件兼容

ScheduleType 明确区分可执行类型，当前只允许 CRON 和 FIXED_RATE 进入任务定义；未知实现会在保存前被拒绝。
Plugin API 增加 API level 范围声明。当前 level 仍为 1，旧 1.x 插件通过默认方法保持兼容。
所有启用插件会在任一插件启动前统一完成兼容检查，避免节点以部分能力启动。

JDBC 一致性与故障验证

Executor 业务幂等实现拆成状态机、DAO 和事务模板。
claim 使用数据库时间、行锁、递增 generation 和条件更新 fencing；过期 owner 被接管后不能完成或释放新 claim。
PostgreSQL/MySQL 测试覆盖连接故障与恢复路径；无法提供外部数据库时，本地构建可跳过真实数据库测试，但 CI 仍执行对应门禁。
删除未使用的 admin-model 和不可执行的 process-fault benchmark scaffold；保留 CI 实际使用的 compatibility/spring-boot-consumer。

受控分片扩容

v1.0.2 提供在线扩容维护动作，但它不是通用零停机双路由 reshard：

只允许增加 shard count，不支持在线缩容。
Scheduler、Standby 和 API 节点必须先 drain 并下线。
纯 Gateway/Executor 数据面可以保持在线。
执行前要求显式确认，并检查没有活跃 execution 或未完成 outbox。
维护事务持有迁移锁，重算 job shard、更新集群元数据 revision，并清理旧 lease。

完整操作步骤见 JDBC 与 HA。

升级检查

将 Maven 或 Gradle 依赖升级到 1.0.2；如果 Central 尚未完成索引，先保持 1.0.1。
自定义插件确认 compatibility() 覆盖 Plugin API level 1。旧插件无需仅因补丁版本重新编译。
直接依赖底层 Netty 模块的项目检查新的 netty-protocol 传递依赖；Starter 用户无需单独声明。
使用 JDBC 业务幂等表的项目对照 clients/executor-netty 中对应方言的初始化 SQL。
修改 shard count 前先备份数据库，并按受控扩容检查表完成 drain、空闲状态验证和回滚准备。

非目标

本版本没有实现语义尚未定义的“失败注册表”。
不承诺 exactly-once；业务副作用仍需使用业务唯一键或事务实现幂等。
不支持在线缩容，也不允许 Scheduler/API 在 shard 映射变化期间继续服务。

完整源码变更可查看 Firefly v1.0.2 Tag。