eurotech/mqtt-ws-proxy

镜像概述

mqtt-ws-proxy是一个用C++编写的轻量级代理，旨在解决WebSocket MQTT客户端与未暴露WebSocket端点的原生MQTT服务器之间的连接问题。通过该代理，WebSocket客户端可通过标准MQTT协议与后端MQTT服务器通信。

核心功能与特性

• 轻量级实现：基于C++开发，资源占用低，性能高效
• 协议支持：同时支持WebSocket (WS) 和WebSocket Secure (WSS) 协议
• 灵活配置：可自定义MQTT服务器地址、端口及WebSocket端点参数
• 端点控制：支持通过配置文件启用/禁用WS或WSS端点
• 安全通信：WSS协议支持需配置SSL证书和密钥文件
• 多线程处理：可通过配置文件设置线程数优化并发处理能力

使用场景与适用范围

• Kubernetes环境中作为sidecar容器，与MQTT服务器协同工作
• 需要为原生MQTT服务器（如Mosquitto、EMQX等）添加WebSocket访问支持的场景
• 需同时提供WS（非加密）和WSS（加密）连接选项的应用场景
• 资源受限环境下的轻量级代理需求

使用方法与配置说明

基本使用（默认配置）

默认配置下，代理监听容器内8080端口（WS协议），并转发流量到容器本地的MQTT服务器（127.0.0.1:1883）：

bash
docker run -p 8080:8080 --name mqtt-ws-proxy eurotech/mqtt-ws-proxy:tagname

说明：此方式适用于MQTT服务器与代理运行在同一容器或Kubernetes Pod内的场景（如sidecar模式）。

自定义配置（挂载配置文件）

对于复杂场景（如指定外部MQTT服务器、启用WSS等），需挂载自定义配置文件：

bash
docker run -p 8080:8080 -p 8443:8443 -v ${PWD}/conf:/etc/mqtt-ws-proxy --name mqtt-ws-proxy eurotech/mqtt-ws-proxy:tagname mqtt-ws-proxy /etc/mqtt-ws-proxy/proxy.conf

参数说明：

• -p 8080:8080：映射WS端口
• -p 8443:8443：映射WSS端口（若启用）
• -v ${PWD}/conf:/etc/mqtt-ws-proxy：挂载本地配置目录（包含配置文件、证书等）
• 容器启动参数需指定配置文件路径：mqtt-ws-proxy /etc/mqtt-ws-proxy/proxy.conf

配置文件结构

配置文件采用JSON格式，支持自定义MQTT服务器连接、WS/WSS端点及线程数：

json
{
    "mqtt": {
        "address": "127.0.0.1",  // MQTT服务器地址
        "port": 1883             // MQTT服务器端口（目前仅支持原生MQTT，非加密）
    },
    "ws": {                      // WS端点配置（省略则禁用WS）
        "address": "0.0.0.0",   // 监听地址（0.0.0.0表示所有网络接口）
        "port": 8080            // WS端口
    },
    "wss": {                     // WSS端点配置（省略则禁用WSS）
        "address": "0.0.0.0",   // 监听地址
        "port": 8443,           // WSS端口
        "crt_file": "/etc/mqtt-ws-proxy/cert.pem",  // SSL证书文件路径（需挂载）
        "key_file": "/etc/mqtt-ws-proxy/key.pem"    // SSL密钥文件路径（需挂载）
    },
    "threads": 1                 // 处理线程数（根据CPU核心数调整）
}

配置说明：

• 禁用WS或WSS端点：只需省略对应的ws或wss字段
• WSS协议依赖：必须同时挂载SSL证书（crt_file）和密钥文件（key_file）
• MQTT协议：目前仅支持原生MQTT（非加密），不支持MQTT over TLS（MQTTS）