# mqtt-proxy

**Repository Path**: xmh3000/mqtt-proxy

## Basic Information

- **Project Name**: mqtt-proxy
- **Description**: mqtt代理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-06
- **Last Updated**: 2025-12-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MQTT Proxy

MQTT Proxy 是一个轻量级的 MQTT 代理服务器，可以作为中间件在 MQTT 客户端和 MQTT 代理之间进行消息转发和处理。该项目基于 Go 语言开发，支持连接认证、消息发布和订阅控制等功能。

## 功能特性

- MQTT 消息代理和转发
- 连接认证（CONNECT）
- 消息发布控制（PUBLISH）
- 订阅控制（SUBSCRIBE/UNSUBSCRIBE）
- 支持 JavaScript 脚本对消息进行预处理
- 日志记录功能
- TLS 加密支持

## 架构设计

MQTT Proxy 作为一个透明代理运行在 MQTT 客户端和真实 MQTT 代理（如 Mosquitto、EMQX 等）之间。它拦截客户端与代理之间的通信，并允许在转发前对消息进行验证和修改。

```
+----------------+         +--------------+         +---------------+
|  MQTT Client   |<------->| MQTT Proxy   |<------->|  MQTT Broker  |
+----------------+         +--------------+         +---------------+
```

## 快速开始

### 环境要求

- Go 1.17 或更高版本

### 构建项目

```bash
go build -o mqtt-proxy
```

或者使用提供的构建脚本：

```bash
./build.bat
```

### 运行代理

```bash
./mqtt-proxy
```

默认情况下，MQTT Proxy 监听在 `0.0.0.0:1884` 并转发到 `0.0.0.0:1883`。

### 配置参数

可以通过环境变量配置 MQTT Proxy：

| 环境变量 | 默认值 | 描述 |
|---------|--------|------|
| MPROXY_MQTT_HOST | 0.0.0.0 | MQTT Proxy 监听地址 |
| MPROXY_MQTT_PORT | 1884 | MQTT Proxy 监听端口 |
| MPROXY_MQTT_TARGET_HOST | 0.0.0.0 | 目标 MQTT 代理地址 |
| MPROXY_MQTT_TARGET_PORT | 1883 | 目标 MQTT 代理端口 |
| MPROXY_LOG_LEVEL | debug | 日志级别 |

例如：

```bash
MPROXY_MQTT_PORT=1885 ./mqtt-proxy
```

## 核心组件

### 会话管理 (Session)

负责管理客户端与代理之间的会话，包括消息流的处理和认证授权。

### 消息处理器 (Handler)

实现了对不同 MQTT 操作的处理逻辑：
- AuthConnect: 连接认证
- AuthPublish: 发布权限检查
- AuthSubscribe: 订阅权限检查
- Connect/Publish/Subscribe/Unsubscribe/Disconnect: 对应操作发生时的通知回调

### JavaScript 处理

支持通过 JavaScript 脚本对消息进行预处理。默认脚本位于 [scripts/convert.js](file:///C:/bxy/go/mqtt-proxy/scripts/convert.js)，可以在消息发布前对其进行转换。

示例脚本将 JSON 格式的消息从一种结构转换为另一种结构。

### 日志系统

使用结构化日志记录系统，支持不同级别的日志输出（Debug, Info, Warn, Error）。

## 使用场景

- 在 IoT 系统中作为消息网关，对设备消息进行预处理
- 实现自定义的认证和授权机制
- 消息格式转换和数据清洗
- 消息审计和监控

## 开发说明

项目结构如下：

```
.
├── errors          # 自定义错误类型
├── javascript      # JavaScript 引擎集成
├── logger          # 日志系统
├── mqtt            # MQTT 协议实现
├── scripts         # JavaScript 脚本文件
├── session         # 会话管理
├── simple          # 示例处理器实现
└── tls             # TLS 加密支持
```

## 扩展开发

要实现自定义的消息处理逻辑，可以实现 [session.Handler](file:///C:/bxy/go/mqtt-proxy/session/handler.go#L8-L30) 接口，并替换 [main.go](file:///C:/bxy/go/mqtt-proxy/main.go) 中的处理器。

## 许可证

本项目采用 MIT 许可证。