MQTT 认证

理解认证方式，配置设备签名或 WebHook，并用 MQTTX 区分认证判定与真实连接。

页面导读

适用场景适合需要为 MQTT 设备配置连接认证（设备签名、Redis 或 WebHook）并验证认证是否生效的实施人员。

前置条件具备 MQTT 认证配置权限，准备一个 MQTTX 客户端用于真实连接验证，预计 25 分钟。

验收点错误密码被拒绝、正确密码能建立会话，认证调试判定与 MQTTX 真实连接结果一致。

阅读方法

先确认入口、权限和目标对象，再按编号完成操作。每一步都包含预期结果；详细字段和选项收在可展开的参考表中。

截图说明

截图来自原始操作手册。公开版会隐藏真实节点地址、连接地址和凭据；示例中的状态、时间和数据不代表当前生产环境。

开始前准备

项目	说明
能做什么	配置 MQTT CONNECT 认证并用 MQTTX 验证。
从哪里进入	MQTT → 客户端认证
需要权限	MQTT 认证配置权限
预计时间	25 分钟

MQTT 认证是什么

MQTT 认证发生在客户端发送 CONNECT 时，决定这台客户端能不能建立会话。认证通过只表示可以连接，不表示已经订阅 Topic，也不表示业务数据已经上报。

认证列表与日常操作

配置项	用途与使用建议	生效与恢复
新建认证方式	同一种认证后端只能创建一条；已有配置应进入详情继续编辑；什么时候用：同一种认证后端只能创建一条；已有配置应进入详情继续编辑。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；失败时：恢复原配置或重新生成设备端登录信息后重连。
启用状态	启用后且过滤器匹配时参与新连接认证；停用用于维护或回退；怎么选：启用后且过滤器匹配时参与新连接认证；停用用于维护或回退；值从哪里来：来自当前接入方案和设备端实现；建议：保持当前值。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：直接启用未验证的全量策略可能影响现有设备；恢复：先用 Client{正则} 灰度，异常时立即停用或恢复原过滤器。
配置	进入详情修改参数、生成签名凭证并执行认证调试；什么时候用：进入详情修改参数、生成签名凭证并执行认证调试。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；失败时：恢复原配置或重新生成设备端登录信息后重连。
删除	只在确认不再使用时删除认证配置；什么时候用：只在确认不再使用时删除认证配置。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；失败时：删除前记录配置；误删后需重新创建并验证。
连通状态	设备签名认证不依赖外部连接；WebHook 状态只能说明 HTTP 客户端可用，不能替代 MQTTX 实际连接；怎么看：设备签名认证不依赖外部连接；WebHook 状态只能说明 HTTP 客户端可用，不能替代 MQTTX 实际连接。	数据来源：来自当前接入方案和设备端实现；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。

当前三类认证方式怎么选

设备能够安全保存盐值并本地计算摘要时，优先使用设备签名认证；已有兼容的 Redis 账号库时可以复用 Redis；必须查询 wumei-smart 中的设备状态、租户或业务权限时，使用 WebHook 认证。

设备签名：FMQ 本地计算，链路短，不依赖外部认证服务。
Redis：复用现有账号数据，先确认键值结构和网络可达性。
WebHook：由外部系统做最终判断，URL 和返回码契约必须先确认。

认证方式与匹配范围

配置项	用途与使用建议	生效与恢复
必填认证后端	设备可本地签名时选设备签名认证；已有兼容 Redis 账号库时选 Redis；必须让 wumei-smart 或统一身份服务判断时选 WebHook；怎么选：设备可本地签名时选设备签名认证；已有兼容 Redis 账号库时选 Redis；必须让 wumei-smart 或统一身份服务判断时选 WebHook；值从哪里来：来自当前接入方案和设备端实现；建议：保持当前值。设备签名认证：FMQ 本地计算期望密码；不依赖外部认证服务。Redis：按配置规则从现有 Redis 数据读取认证信息；依赖 Redis 可达性与键值结构。HTTP 服务（WebHook）：把连接信息 POST 给外部服务；HTTP 200 允许，其他状态拒绝。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
过滤器	限定哪些 clientId 或 username 使用当前策略。灰度演示优先使用 Client{^FastBee_auth_demo$}；怎么选：限定哪些 clientId 或 username 使用当前策略。灰度演示优先使用 Client{^{FastBee_auth_demo$}；值从哪里来：设备命名规范或灰度名单；建议：保持当前值；示例：Client{}device-.*}。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。

配置设备签名认证

1. 确认认证列表与当前状态

操作位置： MQTT→客户端认证

先看已有认证方式、启用状态和连通状态，再决定新建还是配置现有策略。

认证列表总览

图：先确认已有方式、启用状态和连通状态。

2. 选择设备签名认证并限定范围

操作位置： 客户端认证→新建认证方式

选择设备签名认证；首次验证用过滤器限定测试 clientId，避免影响其他设备。

选择设备签名认证

图：设备本地可计算摘要时选择设备签名认证。

字段说明

字段 / 控件	说明
认证后端	设备可本地签名时选设备签名认证；已有兼容 Redis 账号库时选 Redis；必须让 wumei-smart 或统一身份服务判断时选 WebHook；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：来自当前接入方案和设备端实现。选择：设备可本地签名时选设备签名认证；已有兼容 Redis 账号库时选 Redis；必须让 wumei-smart 或统一身份服务判断时选 WebHook。推荐：按实施方案填写 · 示例：按实际环境填写
过滤器	限定哪些 clientId 或 username 使用当前策略。灰度演示优先使用 Client{^FastBee_auth_demo$}；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。选填 · 来源：设备命名规范或灰度名单。选择：限定哪些 clientId 或 username 使用当前策略。灰度演示优先使用 Client{^FastBee_auth_demo$}。推荐：按实施方案填写 · 示例：Client

字段 / 控件

说明

认证后端

设备可本地签名时选设备签名认证；已有兼容 Redis 账号库时选 Redis；必须让 wumei-smart 或统一身份服务判断时选 WebHook；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：来自当前接入方案和设备端实现。选择：设备可本地签名时选设备签名认证；已有兼容 Redis 账号库时选 Redis；必须让 wumei-smart 或统一身份服务判断时选 WebHook。推荐：按实施方案填写 · 示例：按实际环境填写

过滤器

限定哪些 clientId 或 username 使用当前策略。灰度演示优先使用 Client{^FastBee_auth_demo$}；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。选填 · 来源：设备命名规范或灰度名单。选择：限定哪些 clientId 或 username 使用当前策略。灰度演示优先使用 Client{^FastBee_auth_demo$}。推荐：按实施方案填写 · 示例：Client

3. 核对算法、盐值位置和固定盐值

操作位置： 客户端认证→配置

确认三项与设备端实现一致；截图和手册不展示真实盐值。

签名参数

图：算法、盐值位置和设备端必须一致；真实盐值不进入截图。

字段说明

字段 / 控件	说明
加密算法	设备端和 FMQ 必须一致。新项目优先 SHA-256；内置签名支持 plain、MD5、SHA-1、SHA-256、SHA-512；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：来自当前接入方案和设备端实现。选择：设备端和 FMQ 必须一致。新项目优先 SHA-256；内置签名支持 plain、MD5、SHA-1、SHA-256、SHA-512。推荐：sha256 · 示例：按实际环境填写
盐值位置	决定固定盐值放在 clientId+username 的前面、后面或不参与计算；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：来自当前接入方案和设备端实现。选择：决定固定盐值放在 clientId+username 的前面、后面或不参与计算。推荐：suffix · 示例：按实际环境填写
固定盐值	非 plain 算法必须填写，并通过安全渠道下发到设备安全区；不得进入日志、截图和客户手册；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。选填 · 来源：安全配置中心或设备安全存储。选择：非 plain 算法必须填写，并通过安全渠道下发到设备安全区；不得进入日志、截图和客户手册。推荐：按对接资料填写 · 示例：敏感值不展示

4. 保存并只对测试身份启用

操作位置： 客户端认证→配置

先保存带测试过滤器的规则，再启用；验证结束后恢复原状态。

保存并灰度启用

图：过滤器只匹配本次测试 Client ID，验证后恢复原状态。

字段说明

字段 / 控件	说明
过滤器	限定哪些 clientId 或 username 使用当前策略。灰度演示优先使用 Client{^FastBee_auth_demo$}；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。选填 · 来源：设备命名规范或灰度名单。选择：限定哪些 clientId 或 username 使用当前策略。灰度演示优先使用 Client{^FastBee_auth_demo$}。推荐：按实施方案填写 · 示例：Client
启用状态	启用后且过滤器匹配时参与新连接认证；停用用于维护或回退；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。选填 · 来源：来自当前接入方案和设备端实现。选择：启用后且过滤器匹配时参与新连接认证；停用用于维护或回退。推荐：按实施方案填写 · 示例：按实际环境填写

字段 / 控件

说明

过滤器

启用状态

启用后且过滤器匹配时参与新连接认证；停用用于维护或回退；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。选填 · 来源：来自当前接入方案和设备端实现。选择：启用后且过滤器匹配时参与新连接认证；停用用于维护或回退。推荐：按实施方案填写 · 示例：按实际环境填写

5. 生成本次 MQTT 登录信息

操作位置： 客户端认证→配置→生成设备接入参数

输入测试 clientId，username 留空时默认同 clientId；生成后只复制使用，不在截图中展示 password。

生成接入参数

图：输入设备编号后生成登录参数；截图不显示 password 和签名原文。

6. 先用调试验证认证判定

操作位置： 客户端认证→配置→调试

输入同一测试设备编号执行调试；通过只表示认证判定成功，不表示 MQTT 会话已建立。

认证调试通过

图：调试只验证认证判定，不建立 MQTT 会话。

设备签名认证参数

配置项	用途与使用建议	生效与恢复
必填加密算法	设备端和 FMQ 必须一致。新项目优先 SHA-256；内置签名支持 plain、MD5、SHA-1、SHA-256、SHA-512；怎么选：设备端和 FMQ 必须一致。新项目优先 SHA-256；内置签名支持 plain、MD5、SHA-1、SHA-256、SHA-512；值从哪里来：来自当前接入方案和设备端实现；建议：sha256。PLAIN：使用 plain 生成 MQTT password；修改后原 password 立即失效。MD5：使用 md5 生成 MQTT password；修改后原 password 立即失效。SHA1：使用 sha1 生成 MQTT password；修改后原 password 立即失效。SHA256：使用 sha256 生成 MQTT password；修改后原 password 立即失效。SHA512：使用 sha512 生成 MQTT password；修改后原 password 立即失效。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
必填盐值位置	决定固定盐值放在 clientId+username 的前面、后面或不参与计算；怎么选：决定固定盐值放在 clientId+username 的前面、后面或不参与计算；值从哪里来：来自当前接入方案和设备端实现；建议：suffix。前缀：salt + clientId + username；设备端必须同序拼接。后缀：clientId + username + salt；设备端必须同序拼接。不使用：clientId + username；固定盐值不参与计算。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
固定盐值	非 plain 算法必须填写，并通过安全渠道下发到设备安全区；不得进入日志、截图和客户手册；怎么选：非 plain 算法必须填写，并通过安全渠道下发到设备安全区；不得进入日志、截图和客户手册；值从哪里来：安全配置中心或设备安全存储；建议：以部署或对接资料为准；示例：敏感值不展示。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
生成设备接入参数	按当前算法、盐值位置和盐值生成 clientId、username、password；username 留空时默认同 clientId；什么时候用：按当前算法、盐值位置和盐值生成 clientId、username、password；username 留空时默认同 clientId。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；失败时：恢复原配置或重新生成设备端登录信息后重连。
调试	用当前页面草稿参数做一次认证判定；通过不建立 MQTT 会话；什么时候用：用当前页面草稿参数做一次认证判定；通过不建立 MQTT 会话。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；失败时：恢复原配置或重新生成设备端登录信息后重连。
保存	保存当前草稿参数；灰度验证时先保留只匹配测试 Client ID 的过滤器，再启用；什么时候用：保存当前草稿参数；灰度验证时先保留只匹配测试 Client ID 的过滤器，再启用。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；失败时：恢复原过滤器和启用状态。

设备端生成登录信息

设备端需要与 FMQ 使用完全相同的 clientId、username、算法、盐值位置和固定盐值。Python 可使用 hashlib，C 示例使用 OpenSSL EVP；嵌入式项目替换密码库时不能改变 UTF-8 编码和拼接顺序。

prefix：HASH(salt + clientId + username)
suffix：HASH(clientId + username + salt)
disable：HASH(clientId + username)

python

"""按 FMQ 设备签名认证规则生成 MQTT CONNECT 密码。"""

from __future__ import annotations

import hashlib


def mqtt_password(
    client_id: str,
    username: str | None,
    salt: str,
    algorithm: str = "sha256",
    salt_position: str = "suffix",
) -> str:
    if not client_id:
        raise ValueError("client_id 不能为空")

    user = client_id if username is None else username
    raw = client_id + user
    if salt_position == "prefix":
        raw = salt + raw
    elif salt_position == "suffix":
        raw = raw + salt
    elif salt_position != "disable":
        raise ValueError("salt_position 只能是 prefix、suffix 或 disable")

    name = algorithm.lower()
    if name == "plain":
        return raw
    if name not in {"md5", "sha1", "sha256", "sha512"}:
        raise ValueError("FMQ 内置签名不支持该算法")
    return hashlib.new(name, raw.encode("utf-8")).hexdigest()


if __name__ == "__main__":
    # 固定盐值应从设备安全存储读取，不要写死在源码或日志中。
    client_id = "your-device-id"
    username = client_id
    salt = "read-from-secure-storage"
    mqtt_connect_credential = mqtt_password(client_id, username, salt, "sha256", "suffix")
    # 将 mqtt_connect_credential 直接交给 MQTT 客户端，不要输出到日志或控制台。

/* 按 FMQ 设备签名认证规则生成 MQTT CONNECT 密码，示例使用 OpenSSL EVP。 */
#include <openssl/evp.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static const EVP_MD *select_digest(const char *name) {
    if (strcmp(name, "md5") == 0) return EVP_md5();
    if (strcmp(name, "sha1") == 0) return EVP_sha1();
    if (strcmp(name, "sha256") == 0) return EVP_sha256();
    if (strcmp(name, "sha512") == 0) return EVP_sha512();
    return NULL;
}

int fmq_mqtt_password(char *out, size_t out_size,
                      const char *client_id, const char *username,
                      const char *salt, const char *algorithm,
                      const char *salt_position) {
    if (!out || !client_id || !*client_id || !salt || !algorithm || !salt_position) return 0;
    if (!username) username = client_id;

    size_t raw_size = strlen(client_id) + strlen(username) + strlen(salt) + 1;
    char *raw = calloc(raw_size, 1);
    if (!raw) return 0;
    if (strcmp(salt_position, "prefix") == 0)
        snprintf(raw, raw_size, "%s%s%s", salt, client_id, username);
    else if (strcmp(salt_position, "suffix") == 0)
        snprintf(raw, raw_size, "%s%s%s", client_id, username, salt);
    else if (strcmp(salt_position, "disable") == 0)
        snprintf(raw, raw_size, "%s%s", client_id, username);
    else { free(raw); return 0; }

    if (strcmp(algorithm, "plain") == 0) {
        int written = snprintf(out, out_size, "%s", raw);
        int ok = written >= 0 && (size_t)written < out_size;
        free(raw);
        return ok;
    }

    const EVP_MD *md = select_digest(algorithm);
    unsigned char digest[EVP_MAX_MD_SIZE];
    unsigned int digest_len = 0;
    int ok = md && EVP_Digest(raw, strlen(raw), digest, &digest_len, md, NULL) == 1;
    free(raw);
    if (!ok || out_size < (size_t)digest_len * 2 + 1) return 0;
    for (unsigned int i = 0; i < digest_len; ++i) sprintf(out + i * 2, "%02x", digest[i]);
    out[digest_len * 2] = '\0';
    return 1;
}

/* 固定盐值应从设备安全存储读取，不要写死在固件、日志或手册截图中。 */

设备端生成方案

配置项	用途与使用建议	生效与恢复
签名原文	先按盐值位置拼接 clientId、username 和 salt，再按配置算法输出十六进制摘要；怎么看：先按盐值位置拼接 clientId、username 和 salt，再按配置算法输出十六进制摘要。	数据来源：来自当前接入方案和设备端实现；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。
Python	使用标准库 hashlib：hashlib.new(algorithm, raw.encode('utf-8')).hexdigest()。完整示例随工作稿维护；怎么看：使用标准库 hashlib：hashlib.new(algorithm, raw.encode('utf-8')).hexdigest()。完整示例随工作稿维护。	数据来源：来自当前接入方案和设备端实现；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。
C 语言	先按相同顺序拼接 UTF-8 字节，再调用 OpenSSL EVP_Digest；嵌入式可替换为芯片 SDK 的 MD5/SHA 接口；怎么看：先按相同顺序拼接 UTF-8 字节，再调用 OpenSSL EVP_Digest；嵌入式可替换为芯片 SDK 的 MD5/SHA 接口。	数据来源：来自当前接入方案和设备端实现；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。
盐值保管	固定盐值放在设备安全存储或受控配置中，不硬编码到公开源码，不输出到日志；怎么看：固定盐值放在设备安全存储或受控配置中，不硬编码到公开源码，不输出到日志。	数据来源：来自当前接入方案和设备端实现；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。

MQTTX 完整认证演示

7. 用错误密码确认连接被拒绝

操作位置： MQTTX→新建连接

保持地址、clientId 和 username 不变，先输入错误密码连接，确认认证策略确实生效。

错误密码连接被拒绝

图：同一身份使用错误密码应被拒绝。

字段说明

字段 / 控件	说明
Client ID	必须与生成密码时使用的 clientId 完全一致；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：设备标识或本次隔离测试身份。选择：必须与生成密码时使用的 clientId 完全一致。推荐：按对接资料填写 · 示例：FastBee_auth_demo
Username	必须与生成密码时使用的 username 一致；本次演示与 Client ID 相同；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：设备登录约定。选择：必须与生成密码时使用的 username 一致；本次演示与 Client ID 相同。推荐：按对接资料填写 · 示例：FastBee_auth_demo
Password	由设备端或平台生成器按当前规则生成，MQTTX 中应保持掩码；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：设备端签名结果，不进入手册。选择：由设备端或平台生成器按当前规则生成，MQTTX 中应保持掩码。推荐：按对接资料填写 · 示例：敏感值不展示

8. 换回正确密码建立 MQTT 会话

操作位置： MQTTX→连接配置

把 password 换为设备端按同一规则生成的值，重新连接并确认状态为已连接。

正确密码建立会话

图：修正 password 后 MQTTX 显示已连接。

字段说明

字段 / 控件	说明
Client ID	必须与生成密码时使用的 clientId 完全一致；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：设备标识或本次隔离测试身份。选择：必须与生成密码时使用的 clientId 完全一致。推荐：按对接资料填写 · 示例：FastBee_auth_demo
Username	必须与生成密码时使用的 username 一致；本次演示与 Client ID 相同；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：设备登录约定。选择：必须与生成密码时使用的 username 一致；本次演示与 Client ID 相同。推荐：按对接资料填写 · 示例：FastBee_auth_demo
Password	由设备端或平台生成器按当前规则生成，MQTTX 中应保持掩码；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。必填 · 来源：设备端签名结果，不进入手册。选择：由设备端或平台生成器按当前规则生成，MQTTX 中应保持掩码。推荐：按对接资料填写 · 示例：敏感值不展示

MQTTX 连接参数

配置项	用途与使用建议	生效与恢复
必填 Client ID	必须与生成密码时使用的 clientId 完全一致；怎么选：必须与生成密码时使用的 clientId 完全一致；值从哪里来：设备标识或本次隔离测试身份；建议：以部署或对接资料为准；示例：FastBee_auth_demo。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
必填 Username	必须与生成密码时使用的 username 一致；本次演示与 Client ID 相同；怎么选：必须与生成密码时使用的 username 一致；本次演示与 Client ID 相同；值从哪里来：设备登录约定；建议：以部署或对接资料为准；示例：FastBee_auth_demo。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
必填 Password	由设备端或平台生成器按当前规则生成，MQTTX 中应保持掩码；怎么选：由设备端或平台生成器按当前规则生成，MQTTX 中应保持掩码；值从哪里来：设备端签名结果，不进入手册；建议：以部署或对接资料为准；示例：敏感值不展示。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
连接	向 FMQ 发起真实 MQTT CONNECT；错误密码应被拒绝，正确密码应建立会话；什么时候用：向 FMQ 发起真实 MQTT CONNECT；错误密码应被拒绝，正确密码应建立会话。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；失败时：恢复原配置或重新生成设备端登录信息后重连。

WebHook 认证

WebHook 地址必须由 wumei-smart 负责人提供。FMQ 固定 POST JSON；允许返回 HTTP 200，拒绝返回 401/403。当前运行时不读取响应体中的 allow/deny。当前部署尚未取得兼容 URL，因此本节只说明配置方法和接口契约，不宣称已经完成 MQTTX 认证闭环。

界面参考

WebHook 地址与超时

WebHook 地址与超时

图：URL 由 wumei-smart 提供，必须能被 FMQ 运行节点访问。

WebHook 请求模板

WebHook 请求模板

图：FMQ 固定 POST JSON；200 允许，401/403 拒绝。

WebHook 认证参数

配置项	用途与使用建议	生效与恢复
必填 HTTP 服务地址	由 wumei-smart 负责人提供，必须能被 FMQ 运行节点访问；怎么选：由 wumei-smart 负责人提供，必须能被 FMQ 运行节点访问；值从哪里来：wumei-smart 实施或接口负责人；建议：以部署或对接资料为准；示例：https://wumei.example.com/iot/mqtt/auth。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
连接超时	建立 HTTP 连接允许等待的时间。先用 2000 ms，再根据真实网络时延调整；怎么选：建立 HTTP 连接允许等待的时间。先用 2000 ms，再根据真实网络时延调整；值从哪里来：来自当前接入方案和设备端实现；建议：2000 ms。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
请求超时	等待外部认证结果的最长时间；过大会拉长 MQTT CONNECT；怎么选：等待外部认证结果的最长时间；过大会拉长 MQTT CONNECT；值从哪里来：来自当前接入方案和设备端实现；建议：2000 ms。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
连接池大小	限制可复用 HTTP 连接数量，按峰值认证并发和压测结果调整；怎么选：限制可复用 HTTP 连接数量，按峰值认证并发和压测结果调整；值从哪里来：来自当前接入方案和设备端实现；建议：8。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
Pipeline	控制外部认证请求的并发处理参数，保持默认值后再压测；怎么选：控制外部认证请求的并发处理参数，保持默认值后再压测；值从哪里来：来自当前接入方案和设备端实现；建议：100。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
请求头	默认 Content-Type 为 application/json；认证头必须通过受控配置填写，不进入手册；怎么选：默认 Content-Type 为 application/json；认证头必须通过受控配置填写，不进入手册；值从哪里来：wumei-smart 接口契约；建议：以部署或对接资料为准；示例：Content-Type: application/json。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
必填请求体模板	可使用 clientId、username、password 等占位符；默认模板已覆盖三项 MQTT CONNECT 凭据；怎么选：可使用 clientId、username、password 等占位符；默认模板已覆盖三项 MQTT CONNECT 凭据；值从哪里来：来自当前接入方案和设备端实现；建议：保持当前值；示例：{ clientId, username, password }。	只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定；影响范围：当前 MQTT 认证策略；生效要求：需重新绑定或连接；填错时：平台与设备端取值不一致会导致连接被拒绝；恢复：恢复原配置或重新生成设备端登录信息后重连。
返回码约定	FMQ 固定使用 POST；HTTP 200 表示允许，401/403 表示拒绝。当前运行时不读取响应体中的 allow/deny；怎么看：FMQ 固定使用 POST；HTTP 200 表示允许，401/403 表示拒绝。当前运行时不读取响应体中的 allow/deny。	数据来源：来自当前接入方案和设备端实现；只在认证配置启用且过滤器匹配时参与 MQTT CONNECT 判定。

结果判断与排障

参考表

看到什么现象	可能原因	先检查哪里	如何恢复
调试通过但 MQTTX 连接失败	策略未启用、过滤器未匹配，或 MQTTX 三项凭据与生成时不一致。	核对启用状态、过滤器、clientId、username 和生成时间。	重新生成 password，保持输入一致后重连。
修改盐值或算法后设备失败	原 password 已失效。	比较设备端与 FMQ 当前规则。	先灰度更新设备，再扩大范围；必要时恢复原规则。
WebHook 返回 allow 但仍异常	外部接口只在响应体返回结果。	查看真实 HTTP 状态码。	允许返回 200，拒绝返回 401/403。
WebHook 超时	URL 不可达或外部服务不稳定。	从 FMQ 运行节点检查可达性与响应时间。	恢复外部服务后重试，不盲目放大超时。

常见问题

FastBee 的 MQTT 认证有哪几种方式？怎么选？

三类：设备签名认证由 FMQ 本地计算、链路短，设备能安全保存盐值并本地计算摘要时优先使用；已有兼容的 Redis 账号库时可复用 Redis；必须由 wumei-smart 等外部系统判断设备状态、租户或业务权限时使用 WebHook 认证。

MQTT 认证通过就代表设备数据已经上报了吗？

不代表。认证发生在客户端发送 CONNECT 时，只决定这台客户端能不能建立会话；认证通过不表示已经订阅 Topic，也不表示业务数据已经上报。

认证调试通过但 MQTTX 连接失败怎么办？

通常是策略未启用、过滤器未匹配，或 MQTTX 的 Client ID、Username、Password 与生成时不一致；核对启用状态和过滤器后重新生成 password，保持输入一致再重连。

WebHook 认证的返回码约定是什么？

FMQ 固定以 POST JSON 调用外部服务，HTTP 200 表示允许，401/403 表示拒绝；当前运行时不读取响应体中的 allow/deny 字段。

生产操作提示

截图和示例用于说明操作位置与判断方法，不代表当前生产状态。涉及发布、启停、重绑、重试或删除时，应先确认目标环境、影响范围和恢复方案，并由授权人员执行。

蜂信物联（FastBee） · FMQ 操作手册

MQTT 认证 ​

页面导读 ​

开始前准备 ​

MQTT 认证是什么 ​

当前三类认证方式怎么选 ​

配置设备签名认证 ​

1. 确认认证列表与当前状态 ​

2. 选择设备签名认证并限定范围 ​

3. 核对算法、盐值位置和固定盐值 ​

4. 保存并只对测试身份启用 ​

5. 生成本次 MQTT 登录信息 ​

6. 先用调试验证认证判定 ​

设备端生成登录信息 ​

MQTTX 完整认证演示 ​

7. 用错误密码确认连接被拒绝 ​

8. 换回正确密码建立 MQTT 会话 ​

WebHook 认证 ​

界面参考 ​

结果判断与排障 ​

常见问题 ​

FastBee 的 MQTT 认证有哪几种方式？怎么选？ ​

MQTT 认证通过就代表设备数据已经上报了吗？ ​

认证调试通过但 MQTTX 连接失败怎么办？ ​

WebHook 认证的返回码约定是什么？ ​

MQTT 认证

页面导读

开始前准备

MQTT 认证是什么

当前三类认证方式怎么选

配置设备签名认证

1. 确认认证列表与当前状态

2. 选择设备签名认证并限定范围

3. 核对算法、盐值位置和固定盐值

4. 保存并只对测试身份启用

5. 生成本次 MQTT 登录信息

6. 先用调试验证认证判定

设备端生成登录信息

MQTTX 完整认证演示

7. 用错误密码确认连接被拒绝

8. 换回正确密码建立 MQTT 会话

WebHook 认证

界面参考

结果判断与排障

常见问题

FastBee 的 MQTT 认证有哪几种方式？怎么选？

MQTT 认证通过就代表设备数据已经上报了吗？

认证调试通过但 MQTTX 连接失败怎么办？

WebHook 认证的返回码约定是什么？