laidaixi
/
server_cfg
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'e09b81f009'
${ noResults }
server_cfg/nginx_emqx_cfg.md

11 KiB
Raw Blame History Escape

EMQX 服务接入配置说明书

MQTT / WS / WSS / MQTTS 全协议接入指南
服务器：emqx.laidaixi.com ｜ EMQX 5.x + Nginx 反向代理 ｜ 阿里云 ECS

1. 系统架构概述

本服务器在阿里云 ECS 上部署了 EMQX 5.x 消息代理，并通过 Nginx 反向代理对外暴露多种 MQTT 协议接入方式。客户端无需直接访问 EMQX 端口，统一通过 Nginx 进行流量分发。

客户端 → Nginx（80 / 443 / 8883）→ EMQX（1883 / 8083）
域名：emqx.laidaixi.com
证书：已配置 SSL 证书，支持 TLS 1.2 / 1.3

2. 接入方式总览

协议 连接地址 端口 路径 加密 适用场景
MQTT (TCP) emqx.laidaixi.com 1883 — ❌ 否 内网 / 测试工具直连
WS emqx.laidaixi.com 80 /mqtt ❌ 否 Web 浏览器 / 开发调试
WSS emqx.laidaixi.com 443 /mqtt ✅ 是 微信小程序 / Web 生产
MQTTS emqx.laidaixi.com 8883 — ✅ 是 IoT 设备 / 原生客户端

3. MQTT（TCP 明文）

3.1 协议说明

MQTT over TCP 是最基础的接入方式，客户端直连 EMQX 的 1883 端口，无 TLS 加密，适合内网环境或工具调试使用。

3.2 连接参数

协议 连接地址 端口 路径 加密 适用场景
MQTT emqx.laidaixi.com 1883 — ❌ 否 调试工具 / 内网设备

3.3 MQTTX 配置示例

协议：mqtt://
Host：mqtt://
地址：emqx.laidaixi.com
端口：1883
Client ID：mqttx_xxxxxxxx
Username：lai
Password：（对应密码）
注：直连 EMQX，不经过 Nginx

3.4 注意事项

  • 此连接方式不经过 Nginx，直接访问 EMQX 的 TCP 端口 1883。
  • 明文传输，不建议在生产环境传输敏感数据。
  • 阿里云安全组需放行 1883 端口（入方向），或仅内网使用。

4. WS（WebSocket 明文）

4.1 协议说明

MQTT over WebSocket，通过 Nginx 在 80 端口代理到 EMQX 的 8083 端口。适用于 Web 浏览器环境和开发调试。数据明文传输，不适合生产环境敏感业务。

4.2 连接参数

协议 连接地址 端口 路径 加密 适用场景
WS emqx.laidaixi.com 80 /mqtt ❌ 否 Web 浏览器 / 开发调试

4.3 Nginx 配置（laidaixi.conf）

# ===== ws:// 明文 WebSocket（80 端口）=====
server {
    listen 80;
    server_name emqx.laidaixi.com;

    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;
        proxy_set_header    X-Real-IP  $remote_addr;
        proxy_read_timeout  3600s;
    }

    # EMQX Dashboard（可选）
    location / {
        proxy_pass http://127.0.0.1:18083/;
        proxy_http_version  1.1;
        proxy_set_header    Upgrade    $http_upgrade;
        proxy_set_header    Connection "upgrade";
    }
}

4.4 MQTTX 配置示例

协议：ws://
Host：ws://
地址：emqx.laidaixi.com
端口：80
路径：/mqtt
Client ID：mqttx_88759893（或自定义）
Username：lai
Password：（对应密码）

4.5 JavaScript 代码示例

// 使用 mqtt.js 连接 ws://
import mqtt from 'mqtt';

const client = mqtt.connect('ws://emqx.laidaixi.com/mqtt', {
  port: 80,
  clientId: 'web_' + Math.random().toString(16).slice(2),
  username: 'lai',
  password: 'your_password',
  keepalive: 60,
  clean: true,
});

client.on('connect', () => {
  console.log('Connected via WS');
  client.subscribe('test/topic');
});

client.on('message', (topic, payload) => {
  console.log(topic, payload.toString());
});

4.6 注意事项

  • Nginx 通过 Upgrade / Connection 头完成 WebSocket 握手升级。
  • proxy_read_timeout 设为 3600s，避免长连接被 Nginx 主动断开。
  • EMQX Dashboard 也通过 80 端口的 location / 代理访问。

5. WSS（WebSocket 加密，小程序专用）

5.1 协议说明

MQTT over WebSocket Secure，Nginx 在 443 端口终止 TLS，再以明文反向代理到 EMQX 8083 端口。微信小程序强制要求 wss:// 协议，本方案是小程序接入 MQTT 的标准配置。

⚡ 重要：微信小程序只允许 wss:// 协议，请务必使用此接入方式，不可使用 ws://。

5.2 连接参数

协议 连接地址 端口 路径 加密 适用场景
WSS emqx.laidaixi.com 443 /mqtt ✅ 是 微信小程序 / Web 生产环境

5.3 Nginx 配置（laidaixi.conf）

# ===== wss:// 加密 WebSocket（443 端口，小程序专用）=====
server {
    listen 443 ssl;
    server_name emqx.laidaixi.com;

    ssl_certificate     /etc/nginx/cert/emqx.laidaixi.com.pem;
    ssl_certificate_key /etc/nginx/cert/emqx.laidaixi.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    location /mqtt {
        proxy_pass          http://127.0.0.1:8083;   # 后端仍为明文 8083
        proxy_http_version  1.1;
        proxy_set_header    Upgrade    $http_upgrade;
        proxy_set_header    Connection "upgrade";
        proxy_set_header    Host       $host;
        proxy_set_header    X-Real-IP  $remote_addr;
        proxy_set_header    X-Forwarded-Proto $scheme;
        proxy_read_timeout  3600s;

        # 小程序跨域支持
        add_header Access-Control-Allow-Origin  *;
        add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
        add_header Access-Control-Allow-Headers content-type;
    }

    # EMQX Dashboard（生产推荐）
    location / {
        proxy_pass http://127.0.0.1:18083/;
        proxy_set_header Host       $host;
        proxy_set_header X-Real-IP  $remote_addr;
        proxy_http_version  1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

5.4 MQTTX 配置示例

协议：wss://
Host：wss://
地址：emqx.laidaixi.com
端口：443
路径：/mqtt
Client ID：mqttx_xxxxxxxx
Username：lai
Password：（对应密码）

5.5 微信小程序代码示例

// 小程序中使用 mqtt.js（需打包进小程序）
const mqtt = require('./mqtt.min.js');

const client = mqtt.connect('wxs://emqx.laidaixi.com/mqtt', {
  // 小程序使用 wxs:// (wx.connectSocket 底层)
  // 或根据 mqtt.js 版本写成：
  // protocol: 'wss',
  // hostname: 'emqx.laidaixi.com',
  // port: 443,
  // path: '/mqtt',
  clientId: 'mini_' + Math.random().toString(16).slice(2),
  username: 'lai',
  password: 'your_password',
  keepalive: 60,
  clean: true,
  reconnectPeriod: 5000,
});

5.6 注意事项

  • SSL 证书在 Nginx 层终止，EMQX 后端无需配置证书，保持简洁。
  • 已添加 CORS 头（Access-Control-Allow-Origin: *），支持跨域访问。
  • 证书路径：/etc/nginx/cert/emqx.laidaixi.com.pem 和 .key
  • 443 端口同时代理 EMQX Dashboard，通过 location / 转发至 18083 端口。

6. MQTTS（TCP 加密）

6.1 协议说明

MQTT over TLS，原生 MQTT TCP 连接加密版本。适用于 IoT 设备、嵌入式系统、Python/C 原生客户端等不支持 WebSocket 的场景。EMQX 直接在 8883 端口终止 TLS，不经过 Nginx。

6.2 连接参数

协议 连接地址 端口 路径 加密 适用场景
MQTTS emqx.laidaixi.com 8883 — ✅ 是 IoT 设备 / 嵌入式 / 原生客户端

6.3 EMQX 配置

证书通过 docker-compose.yml 挂载进容器：

volumes:
  - /etc/nginx/cert/emqx.laidaixi.com.pem:/opt/emqx/etc/certs/server.pem
  - /etc/nginx/cert/emqx.laidaixi.com.key:/opt/emqx/etc/certs/server.key

在 EMQX Dashboard → 管理 → 监听器 → ssl:default（8883）中配置：

  • TLS Cert: /opt/emqx/etc/certs/server.pem
  • TLS Key: /opt/emqx/etc/certs/server.key
  • 双向认证：关闭（单向 TLS，客户端无需证书）

6.4 MQTTX 配置示例

协议：mqtts://
地址：emqx.laidaixi.com
端口：8883
TLS：true
Client ID：mqttx_xxxxxxxx
Username：lai
Password：（对应密码）

6.5 验证命令

mosquitto_pub -h emqx.laidaixi.com -p 8883 --tls-use-os-certs \
  -u lai -P your_password -t test/topic -m "hello mqtts"

7. EMQX Dashboard 管理界面

7.1 访问地址

方式 地址 端口 加密 说明
HTTP http://emqx.laidaixi.com 80 ❌ 否 开发环境
HTTPS https://emqx.laidaixi.com 443 ✅ 是 生产环境（推荐）

7.2 默认账号

  • 默认用户名：admin
  • 默认密码：public（首次登录后请立即修改）

🔒 安全建议：生产环境请修改默认密码，并考虑将 Dashboard 访问限制为特定 IP。

8. 端口与服务汇总

端口 协议层 Nginx 监听 EMQX 后端 状态
1883 TCP —（直连） EMQX TCP ✅ 已开启
80 HTTP ws:// + Dashboard EMQX 8083 / 18083 ✅ 已开启
443 HTTPS wss:// + Dashboard EMQX 8083 / 18083 ✅ 已开启
8083 WS （内部端口） EMQX WS ✅ 已开启
8883 TLS —（直连） EMQX SSL ✅ 已开启
18083 HTTP （内部端口） EMQX Dashboard ✅ 已开启

9. 安全建议

  • 阿里云安全组：仅放行必要端口（80、443、1883、8883），关闭 8083 和 18083 公网访问。
  • EMQX 认证：已启用用户名/密码认证，避免使用匿名连接。
  • 生产环境：优先使用 WSS（443）或 MQTTS（8883）等加密协议。
  • Dashboard 密码：修改默认 admin / public 密码，并可配置 IP 白名单。
  • 证书续期：定期检查 SSL 证书有效期，可配置 certbot 自动续期。
  • 日志监控：定期查看 EMQX 日志（/var/log/emqx/）及 Nginx 日志，排查异常连接。

10. 常见问题排查

Q1：连接失败，提示 Connection Refused

  • 检查 EMQX 是否正常运行：systemctl status emqx
  • 检查 Nginx 是否正常运行：systemctl status nginx
  • 检查阿里云安全组是否放行对应端口。

Q2：WebSocket 连接 101 升级失败

  • 确认 Nginx 配置中包含 proxy_set_header Upgrade 和 Connection "upgrade"。
  • 确认连接路径为 /mqtt，不可遗漏。

Q3：微信小程序连接报错

  • 必须使用 wss:// 协议，不支持 ws:// 明文。
  • 确认域名 emqx.laidaixi.com 已在微信公众平台配置为合法域名（socket 合法域名）。
  • 证书链必须完整（含中间证书），不可使用自签名证书。

Q4：连接后频繁断线

  • 检查 proxy_read_timeout 是否设置为 3600s（Nginx 默认 60s 会断开长连接）。
  • 客户端 keepalive 建议设置 60 秒，与 MQTTX 配置保持一致。