看懂并配置 MQTT TLS 证书

大多数公网或云 Broker 使用公开 CA 签发的服务器证书。默认从 System CA 开始，不上传任何文件；只有运营方明确提供私有 CA 或要求 mTLS 时，才配置额外材料。

本页完成的标准是：保持验证服务器身份开启，Test Connection 返回 Connection OK，创建的 Connection 达到 Connected，并完成一次获准的消息闭环。

选择 TLS 配置方式

以 Broker 运营方、云控制台或管理员提供的材料为准。不要根据文件名猜，也不要随意生成客户端证书；Broker 没有信任它时，这套证书无法通过认证。

域名和 TLS 端口

保持服务器验证开启，选择 System CA，关闭 mTLS。通常不需要上传证书。

一份 ca.crt、ca.pem 或 CA bundle

选择 Custom CA，把运营方提供的信任材料放入 CA Certificate。

明确要求 mTLS，并提供客户端证书和私钥

先为服务器选择 System CA 或 Custom CA，再开启 mTLS，同时配置 Client Certificate 和 Private Key。

只有用户名、密码或 Token

这是 MQTT Authentication，不是客户端证书。在创建 MQTT Connection 时配置。

不要索取或上传 server.key。服务器私钥只能留在 Broker 一侧。

配置 System CA

这是公网或云 Broker 的默认路径。

1. 打开 Connections → New Broker，选择 mqtts、wss 或 quic。
2. 填写运营方提供的 Host 和 Port；WSS 还需要 WebSocket Path。
3. 保持验证服务器身份开启。
4. 服务器证书信任选择系统 CA。
5. 客户端认证（mTLS）保持关闭。
6. SNI 保持自动，ALPN 留空，除非运营方提供明确值。

123

配置 Custom CA 或 mTLS

只有运营方明确提供所需材料时，才使用下面两条路径。

私有 CA 或自签名 Broker

1. 索取客户端应该信任的 CA Certificate 或 CA bundle。如果只拿到 server.crt ，先确认运营方是否要求客户端把它作为自签名信任材料。

2. 服务器证书信任选择 Custom CA。

3. 在 CA Certificate 中选择上传、粘贴剪贴板或受保护的已保存引用。

4. Broker 没有同时要求客户端证书时，保持 mTLS 关闭。

要求 mTLS 的 Broker

1. 先为服务器验证选择 System CA 或 Custom CA。

2. 开启客户端认证（mTLS）。

3. 分别配置运营方提供的 Client Certificate 和匹配的 Private Key。

4. 确认 Broker 信任客户端证书的签发方。普通用户名/密码连接不需要开启 mTLS。

123

测试并验证

1. 在 Broker 表单点击 Test Connection。
2. 预期每个获准的 MQTT 版本显示绿色 Connection OK；这证明当前地址和 TLS 设置完成了握手。
3. 点击 Create，再创建 MQTT Connection。用户名、密码、JWT 或 SCRAM 等 MQTT Authentication 在这里单独配置。
4. 点击连接，等待状态变为 Connected。
5. 按第一条 MQTT 消息教程完成一次非敏感的订阅、发布和 Trace 核对。

12

不要通过关闭服务器验证来修复证书错误。 生产或公网连接始终保持开启。

按错误信息排查

Unknown CA / unable to get local issuer

检查 System CA 与 Custom CA 是否选对，以及 CA bundle 是否完整。

Hostname mismatch

检查 Host 是否出现在服务器证书的 SAN 中。不要关闭验证。

Certificate expired / not yet valid

检查证书有效期与电脑时间。

缺少 Client Certificate 或 Private Key

检查是否误开 mTLS；若确实要求 mTLS，必须同时提供两项材料。

Certificate and key do not match

检查客户端证书与私钥是否来自同一套签发结果。

Unsupported or encrypted private key

使用分开的受支持未加密 Private Key，不要直接导入 .p12 或 .pfx。

Connection refused / timeout

检查 Host、Port、Listener、DNS、防火墙和网络；这通常发生在证书检查之前。

TLS 成功后仍 Not authorized

检查 Connection 的用户名/密码、客户端证书授权或 Topic ACL，不要继续修改 CA。

每次只改一项，再重新测试。这样能区分网络、TLS 握手、MQTT Authentication 与 Topic Authorization 问题。

证书与文件参考

展开查看证书角色、支持文件与参考资料

Mqttable 始终验证 Broker 证书；只有开启 mTLS 时，Broker 才反过来验证 Mqttable 的客户端证书。

1CA（上方盾牌）：签发与信任来源2Server Certificate：验证 Broker3Client Certificate：仅 mTLS4Client Private Key：留在本地5Server Key：留在 Broker

支持的文件与限制

• CA 与客户端证书：.pem、.crt、.der。
• 客户端私钥：.pem、.key、.der。
• 每份材料最大 5 MB。
• 可通过上传、粘贴 PEM 或受保护的已保存引用录入。

Mqttable 不能直接导入 .p12 / .pfx ，也不接受加密 Private Key。请让管理员提供分开的受支持证书与未加密私钥；不要为了转换格式把私钥发给第三方。

上传前确认：

• Host 使用证书覆盖的域名；用 IP 连接时，证书必须包含该 IP。
• 当前时间在证书有效期内。
• Custom CA 是运营方指定的 CA 或完整 CA bundle。
• Client Certificate 与 Private Key 互相匹配。
• SNI 与 ALPN 只在运营方明确要求时修改。

参考文章与范围

• SSL/TLS 证书（EMQX）

• 开启 SSL/TLS 连接（EMQX）

• Get Started（MQTTX）

本页不讲生产证书签发或 Broker 端部署。管理已保存材料、密码与轮换时，继续阅读 安全管理 Credentials、TLS 与认证材料。