EMQX 集群扩容节点登录失败排查指南
摘要：本文深入剖析 EMQX 4.3.3 集群扩容后新节点登录失败的典型故障现象——客户端报"用户名密码错误"，但后端 HTTP 鉴权接口却返回通过。文章提供从集群状态检查、节点通信验证、脑裂排查、防火墙端口检测到日志追踪的完整排障流程，并重点聚焦HTTP 鉴权插件配置同步问题这一核心根因。通过对比新旧节点
emqx_auth_http插件配置差异，给出具体修复方案，帮助运维人员快速定位并解决 EMQX 集群扩容中的认证配置不一致问题。## EMQX 集群扩容新节点登录失败排查指南：聚焦 HTTP 鉴权插件配置同步## 故障排查流程图
现象：3 节点扩容到 5 节点，新增节点 cluster status 为 running，无客户端连接；老节点业务正常；新节点日志报用户名密码错误，但后端 HTTP 鉴权接口返回鉴权通过1、排查节点状态状态
执行命令
./bin/emqx_ctl cluster status✅ 正常返回示例
Cluster status: #{running_nodes => ['emqx@10.5.11.209','emqx@10.5.11.228','emqx@10.5.15.127','emqx@10.5.15.129','emqx@10.5.11.230'], stopped_nodes => []}🔍 解读
running_nodes 必须包含全部 5 个节点；stopped_nodes 为空
只要节点出现在 stopped_nodes，代表 Erlang 集群链路异2、排查节点之间通信状态信状态
进入 EMQX 控制台
./bin/emqx console% 查看本节点可见的全部集群在线节点nodes().% ping 其他新增/老节点，测试 Erlang 分布式连通net_adm:ping('emqx@10.5.11.209').✅ 正常返回
['emqx@10.5.11.209','emqx@10.5.11.228','emqx@10.5.15.127','emqx@10.5.15.129'] pong❌ 异常返回
[] pang🔍 解读
pong：节点间 Erlang 通信正常
pang：节点间通信失败，防火墙拦截 Erlang 端口（4369 + rpc 动态3、排查是否脑裂是否脑裂
eshell 控制台执行
mnesia:system_info(is_running).mnesia:info().✅ 正常返回
yes % 输出一堆 tables，没有出现 *** WARNING *** brain split detected 脑裂告警❌ 异常
输出打印 *** WARNING *** brain split detected，代表脑裂。
脑裂现象：集群显示 running，但 Mnesia 数据库分片不一致，鉴权、路由数据各节点不4、排查防火墙、端口状态端口状态
4.1 MQTT 客户端接入端口监听（新节点执行）
netstat-tlnp|grep1883✅ 正常
tcp 0 0 0.0.0.0:1883 0.0.0.0:* LISTEN 12345/emqx❌ 异常：无 0.0.0.0:1883 LISTEN，只存在 127.0.0.1:11883，外部无法4.2 本地测试端口连通端口连通
telnet 本机IP1883telnet 其他集群节点IP43694.3 firewalld 查看放行规则
firewall-cmd --list-all🔍 重点检查：
客户端访问：1883/tcp 放行
集群内部通信：4369、rpc 固定端口全部放行
5、调整新节点日志级别，开启追踪日志
设置日志级别
./bin/emqx_ctl logsetdebug开启客户端全链路 trace（替换为你的测试 clientId）
./bin/emqx_ctl trace start client"你的clientId"trace_client.log debug实时查看日志
tail-Femqx.log trace_client.log|grep-E"auth_http|login failed|connect"⚠️ 4.3.3 版本：如果全局 log 等级是 info，trace 设置 debug 会报错；需要先把全局日志改成 debug。
6、故障现象：新节点日志记录用户名密码错误
日志关键字：login failed
[error] login failed: username xxx, clientid xxx, reason: auth_http_response_deny现象：业务后端 HTTP 鉴权接口返回鉴权通过，但是 EMQX 节点报登录失败
👉 根因大概率：新节点的 emqx_auth_http.conf 配置文件和老节点不一致！
核对 HTTP 鉴权插件是否加载（新节点执行）
./bin/emqx_ctl plugins list|grepemqx_auth_http✅ 必须输出：emqx_auth_http active=true
重点：插件不会集群同步！扩容节点不会自动继承老节点插件，新节点没有 load 插件，会走本地默认校验，直接报账号密码错误。
7、集群验证：HTTP 鉴权接口返回鉴权通过，但 EMQX 节点登录失败
老节点：相同账号密码，HTTP 鉴权调用接口返回成功，连接正常；
新节点：相同账号密码，调用同一个 HTTP 接口，日志报登录失败。
7.1 打印新节点 HTTP 鉴权完整配置
catetc/plugins/emqx_auth_http.conf重点比对老节点配置：
auth.http.auth_req.url 请求地址是否一致
auth.http.auth_req.method 请求方式 GET/POST
auth.http.auth_req.params 请求参数占位符，是否和老节点完全一致
HTTP 接口返回报文格式是否匹配 EMQX 预期。
高频坑：新节点 HTTP 鉴权请求参数写错，传给后端接口的 username/password 参数为空，后端接口收到空参数，返回拒绝；或者后端接口返回格式和 EMQX 预期不匹配。
7.2 抓包，查看新节点真实发给后端的 HTTP 请求
在新节点服务器抓包，观察 EMQX 发出的 HTTP 鉴权请求：
tcpdump-nn-ianyhost你的鉴权后端IP and port80观察：新节点发出的 HTTP 请求，参数是否和老节点完全一样。
很多场景：配置文件复制不全，新节点 HTTP 请求没有带上 %u %p 占位符，后端拿到空账号，返回拒绝。
7.3 eshell 查看运行时 HTTP 鉴权配置
application:get_env(emqx_auth_http,auth_req).对比老节点输出，确认运行时配置完全一致。
8、定位思路（迷茫时的排查顺序）
MQTTX 直接直连新节点 IP:1883，绕过负载均衡。
直连也报账号密码错误：问题在新节点 EMQX 本身（插件、auth_http.conf 配置）
直连正常，负载均衡过来失败：上层 LB 问题。
EMQX 4.3.3 集群只同步 Mnesia 路由 /session，插件、配置文件完全不同步。扩容只做 cluster join 远远不够。
同一个账号，老节点成功、新节点失败，90% 概率：新节点 emqx_auth_http.conf 配置不一致，或者插件未加载。
快速对比新旧节
# 老节点导出配置./bin/emqx_ctl plugins list>old_node.txt# 新节点导出配置./bin/emqx_ctl plugins list>new_node.txtdiffold_node.txt new_node.txt总结该故障最高概率根因
新节点 emqx_auth_http 插件没有 load 启用；
新节点 etc/plugins/emqx_auth_http.conf 配置文件和老节点不一致（请求 url、http method、参数占位符错误），向后端 HTTP 接口传参异常；
配置文件改完，没有重启 EMQX，配置未生效，4.3.3 该插件配置不支持热重载。
修复建议：直接把老节点完整的 emqx_auth_http.conf 拷贝到新节点，确认插件加载，重启新节点 EMQX，再测试连接。
。
连接。