mirror of
https://github.com/xinnan-tech/xiaozhi-esp32-server.git
synced 2026-07-31 03:43:57 +08:00
mqtt gateway project
This commit is contained in:
marlonz
@@ -0,0 +1,215 @@
|
||||
# MQTT+UDP 到 WebSocket 桥接服务
|
||||
|
||||
## 项目概述
|
||||
|
||||
这是一个用于物联网设备通信的桥接服务，实现了MQTT和UDP协议到WebSocket的转换。该服务允许设备通过MQTT协议进行控制消息传输，同时通过UDP协议高效传输音频数据，并将这些数据桥接到WebSocket服务。
|
||||
|
||||
## 功能特点
|
||||
|
||||
- **多协议支持**: 同时支持MQTT、UDP和WebSocket协议
|
||||
- **音频数据传输**: 专为音频数据流优化的传输机制
|
||||
- **加密通信**: 使用AES-128-CTR加密UDP数据传输
|
||||
- **会话管理**: 完整的设备会话生命周期管理
|
||||
- **自动重连**: 连接断开时自动重连机制
|
||||
- **心跳检测**: 定期检查连接活跃状态
|
||||
- **开发/生产环境配置**: 支持不同环境的配置切换
|
||||
|
||||
## 技术架构
|
||||
|
||||
- **MQTT服务器**: 处理设备控制消息
|
||||
- **UDP服务器**: 处理高效的音频数据传输
|
||||
- **WebSocket客户端**: 连接到聊天服务器
|
||||
- **桥接层**: 在不同协议间转换和路由消息
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
├── app.js # 主应用入口
|
||||
├── mqtt-protocol.js # MQTT协议实现
|
||||
├── ecosystem.config.js # PM2配置文件
|
||||
├── package.json # 项目依赖
|
||||
├── .env # 环境变量配置
|
||||
├── utils/
|
||||
│ ├── config-manager.js # 配置管理工具
|
||||
│ ├── mqtt_config_v2.js # MQTT配置验证工具
|
||||
│ └── weixinAlert.js # 微信告警工具
|
||||
└── config/ # 配置文件目录
|
||||
```
|
||||
|
||||
## 依赖项
|
||||
|
||||
- **debug**: 调试日志输出
|
||||
- **dotenv**: 环境变量管理
|
||||
- **ws**: WebSocket客户端
|
||||
- **events**: Node.js 事件模块
|
||||
|
||||
## 安装要求
|
||||
|
||||
- Node.js 14.x 或更高版本
|
||||
- npm 或 yarn 包管理器
|
||||
- PM2 (用于生产环境部署)
|
||||
|
||||
## 安装步骤
|
||||
|
||||
1. 克隆仓库
|
||||
```bash
|
||||
git clone <仓库地址>
|
||||
cd mqtt-websocket-bridge
|
||||
```
|
||||
|
||||
2. 安装依赖
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. 创建配置文件
|
||||
```bash
|
||||
mkdir -p config
|
||||
cp config/mqtt.json.example config/mqtt.json
|
||||
```
|
||||
|
||||
4. 编辑配置文件 `config/mqtt.json`，设置适当的参数
|
||||
|
||||
## 配置说明
|
||||
|
||||
配置文件 `config/mqtt.json` 需要包含以下内容:
|
||||
|
||||
```json
|
||||
{
|
||||
"debug": false,
|
||||
"development": {
|
||||
"mac_addresss": ["aa:bb:cc:dd:ee:ff"],
|
||||
"chat_servers": ["wss://dev-chat-server.example.com/ws"]
|
||||
},
|
||||
"production": {
|
||||
"chat_servers": ["wss://chat-server.example.com/ws"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
创建 `.env` 文件并设置以下环境变量:
|
||||
|
||||
```
|
||||
MQTT_PORT=1883 # MQTT服务器端口
|
||||
UDP_PORT=8884 # UDP服务器端口
|
||||
PUBLIC_IP=your-ip # 服务器公网IP
|
||||
```
|
||||
|
||||
## 运行服务
|
||||
|
||||
### 开发环境
|
||||
|
||||
```bash
|
||||
# 直接运行
|
||||
node app.js
|
||||
|
||||
# 调试模式运行
|
||||
DEBUG=mqtt-server node app.js
|
||||
```
|
||||
|
||||
### 生产环境 (使用PM2)
|
||||
|
||||
```bash
|
||||
# 安装PM2
|
||||
npm install -g pm2
|
||||
|
||||
# 启动服务
|
||||
pm2 start ecosystem.config.js
|
||||
|
||||
# 查看日志
|
||||
pm2 logs xz-mqtt
|
||||
|
||||
# 监控服务
|
||||
pm2 monit
|
||||
```
|
||||
|
||||
服务将在以下端口启动:
|
||||
- MQTT 服务器: 端口 1883 (可通过环境变量修改)
|
||||
- UDP 服务器: 端口 8884 (可通过环境变量修改)
|
||||
|
||||
## 协议说明
|
||||
|
||||
### 设备连接流程
|
||||
|
||||
1. 设备通过MQTT协议连接到服务器
|
||||
2. 设备发送 `hello` 消息，包含音频参数和特性
|
||||
3. 服务器创建WebSocket连接到聊天服务器
|
||||
4. 服务器返回UDP连接参数给设备
|
||||
5. 设备通过UDP发送音频数据
|
||||
6. 服务器将音频数据转发到WebSocket
|
||||
7. WebSocket返回的控制消息通过MQTT发送给设备
|
||||
|
||||
### 消息格式
|
||||
|
||||
#### Hello 消息 (设备 -> 服务器)
|
||||
```json
|
||||
{
|
||||
"type": "hello",
|
||||
"version": 3,
|
||||
"audio_params": { ... },
|
||||
"features": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
#### Hello 响应 (服务器 -> 设备)
|
||||
```json
|
||||
{
|
||||
"type": "hello",
|
||||
"version": 3,
|
||||
"session_id": "uuid",
|
||||
"transport": "udp",
|
||||
"udp": {
|
||||
"server": "server-ip",
|
||||
"port": 8884,
|
||||
"encryption": "aes-128-ctr",
|
||||
"key": "hex-encoded-key",
|
||||
"nonce": "hex-encoded-nonce"
|
||||
},
|
||||
"audio_params": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
## 安全说明
|
||||
|
||||
- UDP通信使用AES-128-CTR加密
|
||||
- 每个会话使用唯一的加密密钥
|
||||
- 使用序列号防止重放攻击
|
||||
- 设备通过MAC地址进行身份验证
|
||||
- 支持设备分组和UUID验证
|
||||
|
||||
## 性能优化
|
||||
|
||||
- 使用预分配的缓冲区减少内存分配
|
||||
- UDP协议用于高效传输音频数据
|
||||
- 定期清理不活跃的连接
|
||||
- 连接数和活跃连接数监控
|
||||
- 支持多聊天服务器负载均衡
|
||||
|
||||
## 故障排除
|
||||
|
||||
- 检查设备MAC地址格式是否正确
|
||||
- 确保UDP端口在防火墙中开放
|
||||
- 启用调试模式查看详细日志
|
||||
- 检查配置文件中的聊天服务器地址是否正确
|
||||
- 验证设备认证信息是否正确
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 添加新功能
|
||||
|
||||
1. 修改 `mqtt-protocol.js` 以支持新的MQTT功能
|
||||
2. 在 `MQTTConnection` 类中添加新的消息处理方法
|
||||
3. 更新配置管理器以支持新的配置选项
|
||||
4. 在 `WebSocketBridge` 类中添加新的WebSocket处理逻辑
|
||||
|
||||
### 调试技巧
|
||||
|
||||
```bash
|
||||
# 启用所有调试输出
|
||||
DEBUG=* node app.js
|
||||
|
||||
# 只启用MQTT服务器调试
|
||||
DEBUG=mqtt-server node app.js
|
||||
```
|
||||
Reference in New Issue
Block a user