server_cfg/nginx_emqx_cfg.md

# 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）

```nginx
# ===== 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 代码示例

```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）

```nginx
# ===== 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 微信小程序代码示例

```javascript
// 小程序中使用 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 挂载进容器：

```yaml
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 验证命令

```bash
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 配置保持一致。