Redis 流

SocketIO4J 使用 Redisson 客户端连接到 Redis 服务器。也可能支持 Valkey 和 DragonflyDB 等兼容 Redis 的替代后端。

该 RedisStreamEventStore 为 socketio4j 提供基于 Redis Streams (XADD / XREAD)的分布式流式事件存储。 它通过在多个服务器实例间同步事件实现横向扩展，从而使内部状态、房间成员关系和其他分布式操作在各节点间保持一致。

Redis 可靠发布/订阅在内部使用 Streams 来保证持久性，但不暴露偏移；而 Redis Streams 直接暴露偏移，支持可控的重放和连接状态恢复功能（计划开发中）。

主要特性

• 分布式流式 — 使用 Redis Streams 将事件传递给所有活动节点

• 事件重放连续性 — 在流历史中存储最近事件，允许可控重放

• 按事件类型跟踪偏移 — 每个事件类型维护其自身的最后已见 StreamMessageId

• 流式分发 — 事件异步处理，不阻塞 Netty 事件循环

• 重复预防 — 由同一节点产生的事件使用以下方式过滤 nodeId

工作原理

• 每次发布都会执行 XADD 到 Redis 流（根据模式为单个流或按类型的流）

• 每个事件类型使用自身的读偏移来维护状态，方法是 StreamMessageId

• 轮询在每个事件类型的专用计划执行线程中进行

• 对于每次读取（XREAD），仅处理偏移高于最后处理 id 的消息

• 只有当事件 来自其他节点时，才会将其传递给监听器

• 在错误或流超时时，会自动调度重试

模式

模式	行为	何时使用
MULTI_CHANNEL	每个事件类型使用独立的 Redis 流	默认；隔离事件流量并减少争用
SINGLE_CHANNEL	将所有事件汇入 ALL_SINGLE_CHANNEL	当需要在节点间对所有事件类型进行全局有序时

优点

👍 适用于多节点部署 👍 根据流的长度，消息可在订阅者短暂离线期间存活 👍 提供 基于偏移的投递 👍 支持在重启后对新事件的可控重放（连接状态恢复功能正在开发，目前你会得到消息的偏移） 👍 使用核心 Redis Streams 原语，无需外部代理

限制

ℹ️ 消费者独立处理消息——有序性是按流而非全局保证的 ℹ️ 在重启或偏移边界竞争时可能发生重复投递 ℹ️ 需要 Redis Streams 支持（与传统的 Redis Pub/Sub 模式不兼容）

投递保证： 至少一次语义——事件监听器必须是幂等的以处理可能的重复消息。