在MQTT物联网场景中，服务器查询MQTT客户端是日常运维的核心操作，通过管理控制台、命令行工具或REST API均可实时获取客户端状态与连接详情。不同MQTT Broker的实现细节虽各有差异，但查询思路高度一致：要么借助Broker自带的Web界面，要么通过专用CLI命令，要么调用HTTP API，本文以EMQX、Mosquitto、VerneMQ三个主流Broker为例，拆解可验证的查询方法,并给出连接失败时的排查路径。
emqx查看客户端列表的三种方法
EMQX是目前国内使用最广的MQTT Broker之一，无论是开源版还是企业版,都提供了完整的多层查询接口。
通过Dashboard图形界面查看
EMQX Dashboard默认监听在18083端口，访问http://<服务器IP>:18083，使用默认管理员账户admin/public登录，进入“监控”或“客户端”页面，即可看到当前所有连接的客户端列表，每一行会显示Client ID、用户名、IP地址、协议版本、Keep Alive时长以及当前在线状态，Dashboard还支持按Client ID模糊搜索、按连接时间排序,适合非技术人员快速排查。
通过HTTP API获取客户端列表
EMQX开放了RESTful API，路径为/api/v5/clients，这是批量查询客户端的标准方式，尤其适合被自动化脚本或监控系统调用,例如使用curl命令：
curl -u admin:public "http://localhost:18083/api/v5/clients"
返回的JSON结构中包含data数组，每个元素代表一个客户端，字段包括clientid、username、connected、ip_address、port等，如果只需统计在线数量，可以过滤connected=true的条目，API还支持分页参数page和limit,不会因客户端过多而出现响应超时。
通过CLI命令emqx_ctl
对于没有图形界面或API投递工具的场景，SSH登录到服务器后直接使用emqx_ctl命令是最佳选择，在EMQX 5.x版本中，执行emqx_ctl clients list可列出所有客户端，输出格式为Client ID | Username | Protocol | Connected | IP:Port
，若只想查看某一位客户端的详细信息，使用emqx_ctl clients show <ClientID>，该命令的响应速度取决于集群规模，据EMQX官方文档,在几十万连接量级下仍可秒级返回。
mosquitto查询客户端数量的实用技巧
Mosquitto是轻量级MQTT Broker的代表，不存在内置的Web界面,查询客户端完全依赖命令行和系统主题。
使用mosquitto_sub订阅系统主题
Mosquitto从1.6版本开始支持$SYS系统主题，其中$SYS/broker/clients/connected会实时发布当前已连接客户端的数量,打开一个终端执行：
mosquitto_sub -t '$SYS/broker/clients/connected'
该命令会持续监听，每秒输出一条数字，表示当前在线客户端数量，如需一次性获取当前值，可配合-W 1选项等待1秒后退出，行业共识认为，这是Mosquitto当前最轻量、最准确的连接计数方法。
分析日志文件
Mosquitto默认将客户端连接、断开事件写入日志，启动时需指定-v参数（verbose模式），日志行包含New connection from和Client disconnected字样，通过grep和wc可以统计一段时间内的连接总数。
grep -c "New connection from" /var/log/mosquitto/mosquitto.log
但这种方法只能统计历史事件，不可反映当前实时在线数，且日志文件可能非常大,仅适合离线审计。
通过Unix信号强制输出
向Mosquitto进程发送SIGUSR1信号，会使其将当前连接列表输出到日志中，执行kill -SIGUSR1 <mosquitto_pid>，然后查看日志，会看到类似于Client <clientid> has connected的汇总信息，这种方法无需额外工具，但在客户端数量较多时日志内容会非常长,不推荐用于频繁查询。
如何诊断mqtt客户端连接服务器失败的问题
当客户端无法连接服务器时，需要从网络、协议、认证三个层面逐步排查，以下步骤同样适用于
mqtt客户端连接服务器失败怎么办这类场景。
网络层检查
- 使用
ping <服务器IP>确认基本网络连通性。 - 使用
telnet <服务器IP> 1883测试MQTT默认端口是否可达，若端口不通,检查防火墙规则或Broker绑定地址。 - 若使用WebSocket或SSL端口（如8083、8883），需确认证书配置是否正确，可通过
openssl s_client测试TLS握手。
协议版本与参数校验
MQTT V3.1.1和V5.0的报文格式略有差异，部分老服务器可能不支持V5.0，如果客户端设置了Clean Session、Will Message、Keep Alive等参数，需确保服务器端未对这些参数做限制，建议在客户端代码中开启调试日志，查看Broker返回的CONNACK报文中的返回码（Return Code），例如返回码0x05表示“未授权”，0x04表示“用户名或密码错误”,这些信息直接指向问题根源。
认证与授权验证
大多数生产环境启用了用户名/密码认证或ACL权限控制，检查客户端代码中填写的用户名和密码是否正确，以及该用户是否被允许连接当前主题，如果使用了TLS证书认证，还需确认客户端证书是否由服务器信任的CA签发，近年来，由于证书过期导致的连接失败案例明显增多,定期检查证书有效期是运维常识。
管理mqtt服务器查看订阅客户端状态
知道客户端已连接只是第一步，了解它订阅了哪些主题、是否正常接收消息，才是运维闭环的关键。mqtt服务器查看订阅客户端状态主要依赖Broker提供的监控接口。
通过官方查询接口查看订阅关系
- EMQX：在Dashboard的“订阅”页面可直接看到所有客户端的订阅记录，包括主题、QoS级别、是否含有通配符，API路径为
/api/v5/subscriptions，支持按Client ID过滤。 - VerneMQ：使用
vmq-admin命令，vmq-admin show subscriptions可以列出所有订阅关系，输出格式为ClientID | Topic | QoS，还可以通过--client_id参数指定查询某个用户。 - Mosquitto：原生不支持列出订阅关系，但可以通过
mosquitto_sub订阅$SYS/broker/subscriptions主题（如果Broker启用了该功能），该主题会发布一个JSON数组,其中包含当前所有订阅者及其主题。
使用保留消息测试交互
在客户端订阅某个主题后，如果立即发布一条保留消息到该主题，所有订阅者都能收到，这可以间接验证订阅是否生效，在订阅端执行mosquitto_sub -t "test/#"，然后在服务器端发布一条保留消息mosquitto_pub -t "test/hello" -m "ping" -r，若订阅端成功收到消息,则说明订阅关系正常。
服务器查询mqtt客户端常见问题
如何在EMQX中查看特定客户端的订阅列表？
通过EMQX API，使用GET /api/v5/clients/{clientid}/subscriptions，将{clientid}替换为实际Client ID，返回数据包含该客户端订阅的所有主题以及每个主题对应的QoS等级，如果客户端不在线,API会返回404错误。
Mosquitto是否支持查询某个客户端的订阅？
Mosquitto原生不支持按客户端ID查询订阅，但可以借助第三方插件（如mosquitto-go-auth）或通过$SYS/broker/subscriptions主题获取全量订阅列表，再通过客户端ID过滤，另一种变通方法是，在客户端订阅的主题上发布一条保留消息，并观察是否收到，但这种方法不够精确,且对通配符主题无效。
查询客户端连接时收到超时错误是什么原因？
超时错误通常由网络延迟、防火墙主动丢弃连接或Broker配置的max_inflight_messages耗尽引起，建议先检查客户端到服务器的网络延迟，若延迟超过500ms，需调整Keep Alive值，若网络正常，查看Broker日志中是否有“socket closed”或“connection timeout”记录,这往往指向Broker资源不足或ACL验证耗时过长。
无论使用哪种MQTT Broker，查询客户端状态的核心思路都是围绕Broker的管理接口展开，掌握Dashboard、CLI和API这三类工具，再结合日志分析,就能高效定位客户端连接与订阅问题。
首发原创文章，作者：王坚，如若转载，请注明出处：https://idctop.com/article/505778.html
