Mosquitto WebSocket 配置完全指南

WebSocket 配置让 MQTT Broker 能够接受来自浏览器的连接，是实现前端实时数据展示的关键。下面详细讲解配置方法、安全增强和常见问题。

一、为什么需要 WebSocket？

核心问题：浏览器中的 JavaScript 无法直接创建原始的 TCP 连接，而 MQTT 原生基于 TCP。WebSocket 作为"桥梁"，让网页可以订阅 MQTT 主题、接收实时推送。

架构示意：

浏览器 (JavaScript) 
    ↓ WebSocket (ws:// 或 wss://)
Mosquitto Broker (WebSocket 监听器)
    ↓ 转换为 MQTT
其他 MQTT 客户端 (设备、后端服务)

适用场景：

  • 实时监控仪表盘

  • 设备数据可视化

  • 无需后端参与的纯前端 MQTT 应用

二、基础 WebSocket 配置

2.1 最小配置示例

在 /etc/mosquitto/mosquitto.conf 中添加：

# ========== 标准 MQTT 端口（设备连接用）==========
listener 1883 0.0.0.0
protocol mqtt
​
# ========== WebSocket 端口（浏览器连接用）==========
listener 8080 0.0.0.0
protocol websockets
​
# 测试环境可临时允许匿名访问（生产环境务必关闭）
allow_anonymous true

配置说明：

配置项值含义
listener 8080 0.0.0.0 监听端口 8080，绑定所有网络接口
protocol websockets 关键：指定该监听器使用 WebSocket 协议

2.2 验证配置是否生效

# 重启服务
sudo systemctl restart mosquitto
​
# 查看日志，确认 WebSocket 监听器已启动
sudo journalctl -u mosquitto -f

成功标志（日志中应看到）：

Opening websockets listen socket on port 8080.

2.3 浏览器端连接测试

<!DOCTYPE html>
<html>
<head>
    <script src="https://unpkg.com/mqtt/dist/mqtt.min.js"></script>
</head>
<body>
    <script>
        // 连接地址格式：ws://服务器IP:端口
        const client = mqtt.connect('ws://192.168.1.100:8080');
        
        client.on('connect', () => {
            console.log('WebSocket 连接成功！');
            client.subscribe('test/topic');
            client.publish('test/topic', 'Hello from Browser');
        });
        
        client.on('message', (topic, message) => {
            console.log(`收到消息 [${topic}]: ${message.toString()}`);
        });
    </script>
</body>
</html>

三、安全增强：WSS (WebSocket Secure)

生产环境必须使用 WSS（加密 WebSocket），防止数据被窃听。

3.1 前置条件：准备 SSL 证书

# 创建证书目录
sudo mkdir -p /etc/mosquitto/certs
​
# 生成自签名证书（测试用）
cd /etc/mosquitto/certs
sudo openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key \
  -subj "/CN=localhost"
​
# 设置权限（重要）
sudo chmod 600 server.key
sudo chown mosquitto:mosquitto server.key server.crt

3.2 WSS 配置

在 mosquitto.conf 中添加：

# ========== WSS 加密端口 ==========
listener 8083 0.0.0.0
protocol websockets
cafile /etc/mosquitto/certs/ca.crt      # CA 证书（如有）
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false                # 不强制客户端证书
​
# ========== 强制认证（生产环境必须）==========
allow_anonymous false
password_file /etc/mosquitto/passwd

3.3 浏览器连接 WSS

// 注意：使用 wss:// 协议，端口 8083
const client = mqtt.connect('wss://your-domain.com:8083/mqtt', {
    username: 'frontend_user',
    password: 'secure_password'
});

⚠️ 坑点提醒：某些 MQTT.js 版本需要在 URL 后加 /mqtt 路径，如 wss://host:8083/mqtt。如连接失败可尝试添加。

四、端口选择建议

端口协议用途建议
1883 MQTT (TCP) 设备/后端连接 内网使用，不暴露公网
8883 MQTT over TLS 设备加密连接 外网设备连接
8080 WebSocket (ws) 浏览器明文连接 仅内网测试
8083 WebSocket (wss) 浏览器加密连接 生产环境推荐
9001 WebSocket 替代端口 Docker 镜像常用

非官方标准：WebSocket 端口没有官方标准，8083 和 9001 是最常见的两种选择。

五、完整生产级配置示例

# ========== /etc/mosquitto/mosquitto.conf ==========
​
# 基础配置
pid_file /var/run/mosquitto.pid
user mosquitto
persistence true
persistence_location /var/lib/mosquitto/
​
# ========== 监听器 1：内网 MQTT（设备用）==========
listener 1883 192.168.1.100    # 只监听内网 IP，不对外
protocol mqtt
max_connections 10000
​
# ========== 监听器 2：外网 MQTT over TLS（设备加密）==========
listener 8883 0.0.0.0
protocol mqtt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false
​
# ========== 监听器 3：WebSocket 明文（仅内网测试）==========
listener 8080 127.0.0.1        # 只监听本地，不对外
protocol websockets
​
# ========== 监听器 4：WSS 加密（浏览器生产环境）==========
listener 8083 0.0.0.0
protocol websockets
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
​
# ========== 安全认证（统一配置）==========
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/acl
​
# ========== 日志 ==========
log_dest file /var/log/mosquitto/mosquitto.log
log_type error
log_type warning
connection_messages true

六、常见问题排查

问题 1：配置 protocol websockets 后服务启动失败

现象：Mosquitto 无法启动，日志无明显错误。

原因：安装的 Mosquitto 版本未编译 WebSocket 支持。

解决方案：

# 检查版本是否支持 WebSocket
mosquitto -h | grep websockets
​
# 如果不支持，需要从源码重新编译（启用 libwebsockets）
sudo apt remove mosquitto
sudo apt install libwebsockets-dev
# 从 https://mosquitto.org/download/ 下载源码编译

问题 2：浏览器连接失败，报 ERR_CONNECTION_REFUSED

原因：防火墙未开放端口，或 Mosquitto 绑定了 127.0.0.1。

解决方案：

# 检查监听地址
sudo netstat -tlnp | grep mosquitto
​
# 确保监听 0.0.0.0 而非 127.0.0.1
# 配置应为：listener 8083 0.0.0.0
​
# 开放防火墙
sudo firewall-cmd --permanent --add-port=8083/tcp
sudo firewall-cmd --reload

问题 3：WSS 连接报证书错误

原因：自签名证书不被浏览器信任。

解决方案：

  • 测试环境：在浏览器中先访问 https://你的IP:8083，点击"继续访问"

  • 生产环境：使用 Let's Encrypt 等正规 CA 签发的证书

问题 4：WebSocket 连接成功但收不到消息

原因：认证或 ACL 权限不足。

解决方案：

# 检查 Mosquitto 日志
sudo tail -f /var/log/mosquitto/mosquitto.log
​
# 确认用户有订阅主题的权限
# 在 acl 文件中添加：
user frontend_user
topic read sensors/#

七、与 Nginx 配合使用（可选）

如果需要将 Mosquitto 放在 Nginx 后面（便于统一管理证书和域名），可以配置 Nginx 反向代理：

# /etc/nginx/sites-available/mqtt-proxy
server {
    listen 443 ssl;
    server_name mqtt.yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/yourdomain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain/privkey.pem;
    
    location /mqtt {
        proxy_pass http://127.0.0.1:8083;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
    }
}

此时浏览器连接地址为：wss://mqtt.yourdomain.com/mqtt

八、配置速查表

需求配置代码端口
基础 WebSocket listener 8080 protocol websockets 8080
安全 WSS listener 8083 protocol websockets certfile /path/cert.pem keyfile /path/key.pem 8083
带认证 加上 allow_anonymous false password_file /path/pwfile -
限制来源 IP listener 8080 192.168.1.0/24 -
 

 

posted @ 2026-05-25 23:52  星火撩原  阅读(17)  评论(0)    收藏  举报