EG/plugins/user/realtime_communication/README.md

# 实时通信插件

为EG引擎提供完整的实时通信功能，支持WebSocket双向通信、客户端管理、消息路由、房间系统等功能。

## 功能特性

### 1. WebSocket服务器
- 实时双向通信支持
- SSL/TLS加密连接
- 心跳检测和连接管理
- 消息压缩和优化

### 2. 客户端管理
- 客户端连接和断开管理
- 认证和授权系统
- 黑名单和速率限制
- 客户端状态跟踪

### 3. 消息路由
- 智能消息分发
- 房间内消息广播
- 点对点消息传递
- 消息过滤和验证

### 4. 房间系统
- 动态房间创建和销毁
- 房间密码保护
- 客户端加入/离开管理
- 房间状态同步

### 5. 协议处理
- 多协议支持（JSON、二进制等）
- 消息压缩和解压缩
- 数据序列化和反序列化
- 消息分片和重组

### 6. 安全认证
- Token认证机制
- 密码哈希和验证
- 会话管理
- IP过滤和阻止

### 7. 监控系统
- 实时性能监控
- 日志记录和分析
- 警报系统
- 指标收集和展示

### 8. 配置管理
- 灵活的配置系统
- 实时配置更新
- 配置导入导出
- 默认配置模板

### 9. 事件系统
- 事件驱动架构
- 异步事件处理
- 事件过滤和优先级
- 事件监听器系统

### 10. 可视化编辑器
- 实时数据监控
- 配置界面
- 统计信息展示
- 数据导出功能

## 系统架构

```
实时通信插件
├── 核心模块
│   └── WebSocket服务器 (core/websocket_server.py)
├── 客户端管理
│   └── 客户端管理器 (clients/client_manager.py)
├── 消息处理
│   ├── 消息路由器 (messaging/message_router.py)
│   ├── 协议处理器 (protocol/protocol_handler.py)
│   └── 数据序列化器 (serialization/data_serializer.py)
├── 房间系统
│   └── 房间管理器 (rooms/room_manager.py)
├── 安全系统
│   └── 认证管理器 (auth/auth_manager.py)
├── 监控系统
│   └── 通信监控器 (monitoring/communication_monitor.py)
├── 配置管理
│   └── 通信配置器 (config/comm_config.py)
├── 事件系统
│   └── 事件处理器 (events/event_handler.py)
├── 编辑器接口
│   └── 通信编辑器 (editor/comm_editor.py)
└── 工具模块
    └── 通信工具类 (utils/comm_utils.py)
```

## 安装和使用

### 安装依赖

```bash
# 安装必要的Python包
pip install psutil
```

### 配置插件

插件配置文件位于 `config/communication_config.json`，包含以下主要配置项：

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "enable_ssl": false
  },
  "client": {
    "max_clients": 1000,
    "enable_authentication": true
  },
  "message": {
    "max_message_size": 65536,
    "enable_message_compression": true
  }
}
```

### 启动插件

```python
# 初始化插件
plugin = RealtimeCommunicationPlugin(engine)
plugin.initialize()
plugin.enable()

# 启动WebSocket服务器
plugin.websocket_server.start_server()

# 插件会自动处理客户端连接、消息路由等操作
```

## API参考

### WebSocket服务器

```python
# 发送消息到客户端
plugin.websocket_server.send_message_to_client(client_id, message)

# 广播消息
plugin.websocket_server.broadcast_message(message)

# 断开客户端连接
plugin.websocket_server.disconnect_client(client_id, reason)
```

### 客户端管理

```python
# 添加客户端
plugin.client_manager.add_client(client_id, client_info)

# 认证客户端
plugin.client_manager.authenticate_client(client_id, auth_data)

# 禁止客户端
plugin.client_manager.ban_client(client_id, reason)
```

### 消息路由

```python
# 路由消息
plugin.message_router.route_message(client_id, message)

# 发送直接消息
plugin.message_router.send_direct_message(from_client_id, to_client_id, message)

# 房间广播
plugin.message_router.broadcast_to_room(room_id, message)
```

### 房间管理

```python
# 创建房间
room_id = plugin.room_manager.create_room(room_name, settings)

# 添加客户端到房间
plugin.room_manager.add_client_to_room(room_id, client_id)

# 从房间移除客户端
plugin.room_manager.remove_client_from_room(room_id, client_id)

# 销毁房间
plugin.room_manager.destroy_room(room_id)
```

## 消息格式

### 系统消息

```json
{
  "type": "ping",
  "timestamp": 1234567890.123
}
```

```json
{
  "type": "pong",
  "timestamp": 1234567890.123,
  "ping_timestamp": 1234567890.120
}
```

### 聊天消息

```json
{
  "type": "chat",
  "content": "Hello, world!",
  "sender": "user123"
}
```

### 房间消息

```json
{
  "type": "join_room",
  "room_id": "room123"
}
```

```json
{
  "type": "leave_room",
  "room_id": "room123"
}
```

## 性能优化

1. **连接管理**：使用连接池和复用机制减少资源消耗
2. **消息压缩**：对大数据消息进行自动压缩
3. **异步处理**：采用多线程和异步I/O提高并发性能
4. **缓存机制**：对频繁访问的数据进行缓存
5. **内存优化**：及时清理无用对象和连接

## 安全特性

1. **认证机制**：支持Token和密码认证
2. **权限控制**：基于角色的访问控制
3. **数据加密**：支持SSL/TLS传输加密
4. **防攻击**：IP过滤、速率限制、防DDoS
5. **审计日志**：完整操作日志记录

## 监控和调试

### 实时监控
- CPU和内存使用率
- 网络流量统计
- 连接数和消息数
- 错误率和响应时间

### 日志系统
- 详细的操作日志
- 错误和异常记录
- 性能指标日志
- 安全审计日志

## 扩展开发

### 添加新的消息类型

```python
# 在消息路由器中注册新的处理器
plugin.message_router.register_message_handler("custom_type", custom_handler)

def custom_handler(client_id, message):
    # 处理自定义消息
    pass
```

### 添加新的协议

```python
# 在协议处理器中注册新的协议
plugin.protocol_handler.add_protocol_handler("custom", encode_func, decode_func)
```

### 添加事件监听器

```python
# 注册事件监听器
plugin.event_handler.register_event_handler("client_connected", on_client_connected)

def on_client_connected(payload):
    # 处理客户端连接事件
    pass
```

## 故障排除

### 常见问题

1. **连接失败**：检查端口是否被占用，防火墙设置
2. **认证失败**：检查认证配置和凭证
3. **性能问题**：检查系统资源使用情况，优化配置
4. **消息丢失**：检查网络连接，调整消息队列大小

### 日志分析

查看日志文件以诊断问题：
```
logs/communication_monitor.log
```

## 版本信息

- 版本：1.0.0
- 作者：EG Plugin System
- 许可证：MIT

## 贡献指南

欢迎提交Issue和Pull Request来改进这个插件。

## 支持

如需技术支持，请联系插件维护团队或查看相关文档。