在 Nginx Stream 层“改写”MQTT ngx_stream_mqtt_filter_module

Hello.Reader

932人浏览 · 2025-06-09 12:37:46

Hello.Reader · 2025-06-09 12:37:46 发布

1、为什么要修改 CONNECT 报文？

多租户隔离：自动为接入设备追加租户前缀，后端按 ClientID 拆分队列。
零代码鉴权：将入站用户名替换为 OAuth Access-Token，后端 Broker 统一校验。
灰度发布：根据 IP/地理位写入不同后缀，让同一客户端同时连到测试与生产集群。
兼容旧设备：早期固件不支持密码，网关可注入随机密码并回传至 IAM。

2、指令速查

指令	作用	典型配置
`mqtt on;`	在虚拟主机启用 MQTT 过滤	`server { mqtt on; … }`
`mqtt_buffers N S;` (1.25.1)	单连接缓存 N × S 字节处理 PUBLISH/ACK	`mqtt_buffers 256 2k;`
`mqtt_set_connect field value;`	重写 `CONNECT` 字段（clientid / username / password）	`mqtt_set_connect clientid "$geoip_city_$remote_addr";`

弃用：mqtt_rewrite_buffer_size ≤ 1.25.0；新版本统一用 mqtt_buffers。

3、最小示例：按照 IP 段自动打上租户前缀

# 自动映射租户
geo $remote_addr $tenant {
    default   default_;
    10.0.0.0/16  corpA_;
    172.16.0.0/12 corpB_;
}

stream {
    server {
        listen 18883;
        proxy_pass   10.0.0.20:1883;   # 后端 EMQX

        mqtt on;

        # ① 每连接缓存 256×2 KB，适配高并发发布
        mqtt_buffers 256 2k;

        # ② 重写 ClientID / Username
        mqtt_set_connect clientid  "$tenant${mqtt_preread_clientid}";
        mqtt_set_connect username  "$tenant${mqtt_preread_username}";
    }
}

效果
接入设备 sensor01 若来自 10.1.2.3，Gateway 转发的实际 ClientID 将变为 corpA_sensor01。后端可据此分配独立 ACL 与 Topic。

4、高级玩法

需求	配置要点
灰度：5 % 设备流向新集群	`map $mqtt_preread_clientid $bucket { … }` + 两条 `proxy_pass`
密码托管：IoT Hub 统一颁发	`mqtt_set_connect password "$secure_token";`
QoS 带宽保护	配合 `limit_conn_zone` / `limit_rate` 控制单租户并发与速率
TLS 终端	`ssl_preread on;` → Nginx 解 SNI，再走 MQTT 过滤

5、性能调优

场景	建议
大量小消息（<= 256 B）	`mqtt_buffers 512 512;` 减少 re-alloc
高并发长连接（≥ 50 K）	缩小 buffer，配合系统 `net.core.somaxconn`
频繁改写大字段	保持 `mqtt_buffers N S` ≥ 字段最大长度，防止 `rewrite too long` 错误
观测重写结果	`access_log` 增加 `$mqtt_preread_clientid $mqtt_preread_username`

6、安全注意事项

字段长度：MQTT 规范 ClientID ≤ 23 字节（3.1.1），> 23 会被后端拒绝；重写前需 if ($clientid ~ "^.{1,23}$") { … }。
密码明文：模块不自动加密；建议启用 TLS + Password Hash。
回环风险：若网关与 Broker 在同一台 Nginx，需要拆分端口或使用 proxy_bind。

7、结语

ngx_stream_mqtt_filter_module 把「MQTT 连接级改写」下沉到 L4，配合 Stream 生态（keyval / limit_conn / js 等）即可实现动态租户隔离、无感鉴权与流量灰度。对于千万级设备同时在线、高频推送的 IoT 平台，它既保证极低延迟，又提供丰富的运营 & 安全钩子 —— 只需几行配置，你的 Nginx 就能变身“智能 MQTT 接入网关”。