emqtt-bench Docker镜像文档

镜像概述和主要用途

emqtt-bench 是一个用 Erlang 编写的轻量级 MQTT v5.0 基准测试工具，用于评估 MQTT 服务器的性能。该工具支持模拟大量并发 MQTT 客户端，进行连接、订阅、发布等操作的性能测试，帮助用户评估 MQTT 服务器在不同场景下的处理能力，如最大并发连接数、消息吞吐量、延迟等关键指标。

注意：以下示例中，"Usage" 指的是镜像内的脚本 emqtt_bench，而 Docker 镜像名称为 emqx/emqtt-bench。

核心功能和特性

• 支持 MQTT v3、v4、v5 协议版本
• 提供三种基准测试类型：
  • 连接测试（Connect Benchmark）：测试服务器处理并发连接的能力
  • 订阅测试（Sub Benchmark）：测试服务器处理订阅操作的能力
  • 发布测试（Pub Benchmark）：测试服务器处理消息发布的吞吐量和延迟
• 支持 SSL/TLS 加密连接（单向和双向认证）
• 支持 WebSocket 传输协议
• 支持主题变量（%u、%c、%i），可生成动态主题
• 可配置并发客户端数量、连接间隔、消息发送间隔、消息大小等参数
• 支持指定本地网络接口地址

使用场景和适用范围

• MQTT 服务器（如 EMQX、Mosquitto 等）的性能评估和压力测试
• 验证服务器在高并发连接场景下的稳定性
• 测试不同 QoS 级别（0、1、2）下的消息传输性能
• 评估 SSL/TLS 加密对 MQTT 服务器性能的影响
• 测试 WebSocket 传输模式下的 MQTT 消息处理能力
• 验证服务器对大量订阅和发布消息的处理能力

详细使用方法和配置说明

连接基准测试（Connect Benchmark）

用于测试 MQTT 服务器处理并发连接的能力。

命令选项

sh
docker run -it emqx/emqtt-bench conn --help

选项说明：

示例

以 100 个/秒的速率创建 50,000 个并发连接：

sh
docker run -it emqx/emqtt-bench conn -c 50000 -i 10

订阅基准测试（Sub Benchmark）

用于测试 MQTT 服务器处理订阅操作的能力。

命令选项

sh
docker run -it emqx/emqtt-bench sub --help

选项说明：

示例

以 100 个/秒的速率创建 50,000 个并发订阅客户端，订阅主题 bench/%i（%i 为客户端编号），QoS 级别 2：

sh
docker run -it emqx/emqtt-bench sub -c 50000 -i 10 -t bench/%i -q 2

发布基准测试（Pub Benchmark）

用于测试 MQTT 服务器处理消息发布的吞吐量和延迟。

命令选项

sh
docker run -it emqx/emqtt-bench pub --help

选项说明：

示例

创建 100 个并发客户端，每个客户端以 100 条/秒的速率发布消息，主题 bench/%i（%i 为客户端编号），消息大小 256 字节：

sh
docker run -it emqx/emqtt-bench pub -c 100 -I 10 -t bench/%i -s 256

高级使用示例

指定本地接口

通过 --ifaddr 选项指定客户端使用的本地 IP 地址：

sh
docker run -it emqx/emqtt-bench pub --ifaddr 192.168.1.10
docker run -it emqx/emqtt-bench sub --ifaddr 192.168.2.10

单向 SSL 连接

连接使用 SSL/TLS 加密的 MQTT 服务器（端口通常为 8883）：

sh
# 订阅测试
docker run -it emqx/emqtt-bench sub -c 100 -i 10 -t bench/%i -p 8883 -S

# 发布测试
docker run -it emqx/emqtt-bench pub -c 100 -I 10 -t bench/%i -p 8883 -s 256 -S

双向 SSL 连接

使用客户端证书和私钥进行双向 SSL 认证：

sh
# 订阅测试（需挂载证书文件到容器内，假设本地证书路径为 /local/certs/）
docker run -it -v /local/certs:/certs emqx/emqtt-bench sub -c 100 -i 10 -t bench/%i -p 8883 --certfile /certs/client-cert.pem --keyfile /certs/client-key.pem

# 发布测试
docker run -it -v /local/certs:/certs emqx/emqtt-bench pub -c 100 -i 10 -t bench/%i -s 256 -p 8883 --certfile /certs/client-cert.pem --keyfile /certs/client-key.pem

注意：双向 SSL 连接需将本地证书文件挂载到容器内，使用 -v 参数指定挂载路径。

注意事项

• 由于单网络接口的 TCP 端口限制，-c（客户端数量）选项不应设置超过 60,000。
• 高并发测试可能需要调整主机的系统参数（如文件描述符限制、TCP 连接参数等）以获得准确结果。
• 使用 SSL/TLS 或 WebSocket 时，性能测试结果可能受加密和协议开销影响。

作者

EMQX 团队