chore: 更新文档

Author: Cyaim

Cyaim.WebSocketServer/Cluster/Cyaim.WebSocketServer.Cluster.Hybrid/README.md

@@ -765,6 +765,24 @@ await clusterTransport.StartAsync();
 app.Run();
 ```
 
+## Message Deduplication / 消息去重机制
+
+### Automatic Duplicate Prevention / 自动防止重复处理
+
+`HybridClusterTransport` has built-in message deduplication to ensure messages are not processed multiple times:
+
+`HybridClusterTransport` 内置了消息去重机制，确保消息不会被重复处理：
+
+1. **Target Node Check** - Only the target node processes messages intended for it / **目标节点检查** - 只有目标节点会处理指定目标的消息
+2. **Message ID Deduplication** - Uses message ID to prevent processing the same message twice / **消息ID去重** - 使用消息ID防止重复处理同一消息
+3. **Automatic Cleanup** - Periodically cleans up expired message ID records / **自动清理** - 定期清理过期的消息ID记录
+
+### How It Works / 工作原理
+
+- **Target Node Check / 目标节点检查**: If `ToNodeId` is set and not equal to current node, message is ignored / 如果 `ToNodeId` 已设置且不等于当前节点，消息会被忽略
+- **Message ID Deduplication / 消息ID去重**: Each message has unique `MessageId`, duplicate messages are automatically ignored / 每个消息都有唯一的 `MessageId`，重复消息会被自动忽略
+- **Automatic Cleanup / 自动清理**: Message ID cache is cleaned every 5 minutes (retains last 10 minutes) / 消息ID缓存每5分钟清理一次（保留最近10分钟）
+
 ## Troubleshooting / 故障排除
 
 ### Nodes Not Discovering Each Other / 节点无法相互发现
@@ -786,6 +804,14 @@ app.Run();
 - Verify node status is `Active` / 验证节点状态为 `Active`
 - If using custom `nodeInfoProvider`, ensure it returns valid data / 如果使用自定义 `nodeInfoProvider`，确保它返回有效数据
 
+### Messages Being Processed Multiple Times / 消息被重复处理
+
+- ✅ **Fixed / 已修复**: `HybridClusterTransport` has built-in message deduplication / `HybridClusterTransport` 内置消息去重机制
+- If still experiencing duplicates, check / 如果仍然出现重复，请检查:
+  - Message `MessageId` is unique / 消息的 `MessageId` 是否唯一
+  - Message `ToNodeId` is correctly set / 消息的 `ToNodeId` 是否正确设置
+  - Logs for deduplication messages / 日志中的去重消息提示
+
 ## License / 许可证
 
 See LICENSE file for details.

Cyaim.WebSocketServer/docs/en/HYBRID_CLUSTER.md

@@ -932,6 +932,82 @@ timer.Start();
 app.Run();
 ```
 
+## Message Deduplication Mechanism
+
+### Automatic Duplicate Prevention
+
+`HybridClusterTransport` has built-in message deduplication to ensure messages are not processed multiple times:
+
+1. **Target Node Check** - Only the target node processes messages intended for it
+2. **Message ID Deduplication** - Uses message ID to prevent processing the same message twice
+3. **Automatic Cleanup** - Periodically cleans up expired message ID records (every 5 minutes, keeps records from last 10 minutes)
+
+### How It Works
+
+```text
+Message Arrives → Check if from self → Check target node → Check if processed → Process message
+```
+
+#### Target Node Check
+
+- If message's `ToNodeId` is not empty and not equal to current node ID, message is ignored
+- If `ToNodeId` is `null` (broadcast message), all nodes process it (but deduplicated by message ID)
+- If `ToNodeId` equals current node ID, message is processed
+
+#### Message ID Deduplication
+
+- Each message has a unique `MessageId`
+- Before processing, checks if this `MessageId` has been processed
+- If already processed, message is ignored to prevent duplicate processing
+
+### Example Scenarios
+
+**Scenario 1: Unicast Message (Specific Target Node)**
+
+```csharp
+// Node 1 sends message to Node 2
+await clusterTransport.SendAsync("node2", new ClusterMessage { ... });
+
+// Result:
+// - Node 2: Processes message ✅
+// - Node 1, Node 3: Ignore message (because ToNodeId != own node ID) ✅
+```
+
+**Scenario 2: Broadcast Message**
+
+```csharp
+// Node 1 broadcasts message
+await clusterTransport.BroadcastAsync(new ClusterMessage { ... });
+
+// Result:
+// - All nodes: Receive message
+// - But deduplicated by message ID, ensuring each node processes only once ✅
+```
+
+**Scenario 3: Duplicate Message Arrival (Network Retransmission, etc.)**
+
+```csharp
+// If same message arrives multiple times due to network issues
+// Result:
+// - First time: Processed normally ✅
+// - Subsequent duplicates: Automatically ignored via message ID check ✅
+```
+
+### Configuration
+
+The message deduplication mechanism is **automatically enabled**, no configuration needed. The system will:
+
+- Automatically check target node
+- Automatically use message ID for deduplication
+- Automatically clean up expired message ID records (every 5 minutes)
+
+### Performance Considerations
+
+- Message ID cache uses in-memory storage, periodically cleaned to prevent memory leaks
+- Cleanup interval: Every 5 minutes
+- Retention time: Message IDs from last 10 minutes
+- For high-concurrency scenarios, memory usage is minimal (each message ID uses about tens of bytes)
+
 ## Troubleshooting
 
 ### Nodes Not Discovering Each Other
@@ -952,6 +1028,14 @@ app.Run();
 - Check connection count values
 - Verify node status is `Active`
 
+### Messages Being Processed Multiple Times
+
+- ✅ **Fixed**: `HybridClusterTransport` has built-in message deduplication
+- If still experiencing duplicate processing, check:
+  - Whether message's `MessageId` is unique
+  - Whether message's `ToNodeId` is correctly set
+  - Logs for "Ignoring duplicate message" or "Ignoring message - target node is" messages
+
 ## Related Documentation
 
 - [Cluster Module Documentation](./CLUSTER.md)

Cyaim.WebSocketServer/docs/zh-cn/HYBRID_CLUSTER.md

@@ -932,6 +932,82 @@ timer.Start();
 app.Run();
 ```
 
+## 消息去重机制
+
+### 自动防止重复处理
+
+`HybridClusterTransport` 内置了消息去重机制，确保消息不会被重复处理：
+
+1. **目标节点检查** - 只有目标节点会处理指定目标的消息
+2. **消息ID去重** - 使用消息ID防止重复处理同一消息
+3. **自动清理** - 定期清理过期的消息ID记录（每5分钟清理一次，保留10分钟内的记录）
+
+### 工作原理
+
+```text
+消息到达 → 检查是否来自自己 → 检查目标节点 → 检查是否已处理 → 处理消息
+```
+
+#### 目标节点检查
+
+- 如果消息的 `ToNodeId` 不为空且不等于当前节点ID，消息会被忽略
+- 如果 `ToNodeId` 为 `null`（广播消息），所有节点都会处理（但会通过消息ID去重）
+- 如果 `ToNodeId` 等于当前节点ID，消息会被处理
+
+#### 消息ID去重
+
+- 每个消息都有唯一的 `MessageId`
+- 处理前会检查该 `MessageId` 是否已处理过
+- 如果已处理，消息会被忽略，避免重复处理
+
+### 示例场景
+
+**场景1：单播消息（指定目标节点）**
+
+```csharp
+// 节点1发送消息给节点2
+await clusterTransport.SendAsync("node2", new ClusterMessage { ... });
+
+// 结果：
+// - 节点2：处理消息 ✅
+// - 节点1、节点3：忽略消息（因为 ToNodeId != 自己的节点ID）✅
+```
+
+**场景2：广播消息**
+
+```csharp
+// 节点1广播消息
+await clusterTransport.BroadcastAsync(new ClusterMessage { ... });
+
+// 结果：
+// - 所有节点：都会收到消息
+// - 但通过消息ID去重，确保每个节点只处理一次 ✅
+```
+
+**场景3：消息重复到达（网络重传等）**
+
+```csharp
+// 如果同一消息因为网络问题重复到达
+// 结果：
+// - 第一次：正常处理 ✅
+// - 后续重复：通过消息ID检测，自动忽略 ✅
+```
+
+### 配置说明
+
+消息去重机制是**自动启用**的，无需任何配置。系统会：
+
+- 自动检查目标节点
+- 自动使用消息ID去重
+- 自动清理过期的消息ID记录（每5分钟清理一次）
+
+### 性能考虑
+
+- 消息ID缓存使用内存存储，定期清理避免内存泄漏
+- 清理间隔：每5分钟
+- 保留时间：10分钟内的消息ID
+- 对于高并发场景，内存占用很小（每个消息ID约占用几十字节）
+
 ## 故障排除
 
 ### 节点无法相互发现
@@ -952,6 +1028,14 @@ app.Run();
 - 检查连接数值
 - 验证节点状态为 `Active`
 
+### 消息被重复处理
+
+- ✅ **已修复**：`HybridClusterTransport` 内置消息去重机制
+- 如果仍然出现重复处理，请检查：
+  - 消息的 `MessageId` 是否唯一
+  - 消息的 `ToNodeId` 是否正确设置
+  - 日志中是否有 "Ignoring duplicate message" 或 "Ignoring message - target node is" 的提示
+
 ## 相关文档
 
 - [集群模块文档](./CLUSTER.md)