ThingsBoard支持在MQTT服务器上启用SSL，包括单向和双向SSL。
大多数ThingsBoard环境中，负载均衡器作为设备与平台之间SSL连接的终端。 即：MQTT流量在设备与负载均衡器之间加密，在负载均衡器与平台服务之间解密。 这种方式配置简单。 多数云负载均衡器（如AWS、Google Cloud等）提供内置证书生成工具和完善的SSL over TCP配置文档。 缺点是无法使用双向SSL，客户端证书信息不会从负载均衡器传递到平台服务。
仍可配置ThingsBoard使用MQTT双向SSL，并避免在Load Balancer上做SSL终结。 建议使用受信任CA签发的有效SSL证书，以节省在 自签名证书 相关问题上的排查时间。 以下说明如何在PEM文件格式或Java Keystore中配置SSL。
使用PEM证书文件的SSL配置
| 3.3.2及以上版本 |
通过 configuration 文件、docker-compose或kubernetes脚本配置以下环境变量。 示例以 thingsboard.conf 为例：
1
2
3
4
5
6
7
...
export MQTT_SSL_ENABLED=true
export MQTT_SSL_CREDENTIALS_TYPE=PEM
export MQTT_SSL_PEM_CERT=server.pem
export MQTT_SSL_PEM_KEY=server_key.pem
export MQTT_SSL_PEM_KEY_PASSWORD=secret
...
说明：
- MQTT_SSL_ENABLED — 启用/禁用SSL；
- MQTT_SSL_CREDENTIALS_TYPE — 服务器凭证类型。PEM表示PEM证书文件；KEYSTORE表示Java keystore；
- MQTT_SSL_PEM_CERT — 服务器证书文件路径。可包含服务器证书或证书链，也可包含服务器私钥；
- MQTT_SSL_PEM_KEY — 服务器证书私钥文件路径。默认可选。若服务器证书文件中不含私钥则必须指定；
- MQTT_SSL_PEM_KEY_PASSWORD — 可选，服务器证书私钥密码。
配置完成后，启动或重启ThingsBoard服务。
确保证书文件可被 ThingsBoard 进程访问：
- Linux：使用 /etc/thingsboard/conf 目录。确保文件权限与 thingsboard.conf 一致；使用相对路径，如 server.pem；
- Docker Compose：将卷挂载或使用现有卷至容器的 /config 目录；使用完整路径，如 /config/server.pem；
- K8S：将独立卷挂载至 /https-config 或类似目录；使用完整路径，如 /https-config/server.pem；
- Windows：使用 C:\Program Files (x86)\thingsboard\conf\ 目录。确保文件权限与 thingsboard.conf 一致；使用相对路径，如 server.pem；
其他配置属性
可通过 configuration 文件、docker-compose或kubernetes脚本配置以下环境变量：
- MQTT_SSL_BIND_ADDRESS — MQTT服务器绑定地址。默认 0.0.0.0 表示所有接口；
- MQTT_SSL_BIND_PORT — MQTT服务器绑定端口。默认 8883；
- MQTT_SSL_PROTOCOL — SSL协议名。默认 TLSv1.2。详见 java doc；
- MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT — 跳过客户端证书有效期校验。默认 false。
自签名证书生成
以下说明用于生成自有证书文件，适用于测试环境，耗时且不推荐用于生产环境。
注意： 需在已安装openssl的Linux类系统上执行以下步骤。
可选择为服务器创建自签名证书，或按进阶步骤创建CA签名的服务器证书。 两种方式都能实现同一目标：用有效证书保护服务器。
自签名证书PEM文件
这是更简单的方式，由服务器自行生成并签署证书，适用于基础测试或无需证书颁发机构（CA）的小型部署。 生成服务器自签名PEM证书及私钥可使用以下命令：
1
2
openssl ecparam -out server_key.pem -name secp256r1 -genkey
openssl req -new -key server_key.pem -x509 -nodes -days 365 -out server.pem
如不想用密码保护私钥，可加 -nodes（no DES的缩写），否则会要求输入”至少4个字符”的密码。
days 参数（365）可改为任意数字以影响有效期。随后会提示输入”Country Name”等，可直接按Enter使用默认值。
添加 -subj '/CN=localhost' 可跳过证书内容相关提问（将localhost替换为你的域名）。
自签名证书不经第三方校验，除非事先导入浏览器。如需更高安全性，应使用由证书颁发机构（CA）签名的证书。
由证书颁发机构（CA）签名的证书PEM文件
本方法通过创建证书颁发机构（CA）来签署服务器证书，适合需要更高安全性的场景， 尤其是计划管理多张证书或需要专用CA进行签名时。
生成CA私钥：
1
openssl ecparam -out ca_key.pem -name secp256r1 -genkey
生成自签名CA证书：
1
openssl req -new -x509 -key ca_key.pem -days 365 -out ca.pem
将生成有效期为365天的自签名CA证书”ca.pem“。按提示填写证书信息（如Common Name：My Root CA）。
生成服务器私钥：
1
openssl ecparam -out server_key.pem -name secp256r1 -genkey
将生成 EC私钥server_key.pem。
创建证书签名请求（CSR）：
1
openssl req -new -key server_key.pem -out server.csr
“server.csr“包含待CA签名的服务器信息。
最后，使用CA签署服务器证书：
1
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca_key.pem -CAcreateserial -out server.pem -days 365
该命令将生成由CA签名的服务器证书”server.pem“。
-req：表示输入为证书签名请求（CSR）。
-CA 与 -CAkey：指定用于签署服务器证书的CA证书“ca.pem”及其私钥“ca_key.pem”。
-CAcreateserial 会自动生成序列号文件”ca.srl“以记录该CA的证书序列号。
签署多张证书时很有用。若不希望生成”ca.srl“，可将 -CAcreateserial 换成 -set_serial <serial_number> 手动指定序列号。
Client示例
参见以下文档：
- 设备认证选项 — 认证方式概览
- 基于Access Token的认证 — 单向SSL 连接示例
- 基于X.509 Certificate的认证 — 双向SSL 连接示例