ThinkLink 与 EMQX TLS 证书配置
tkl-tls 2.0.0 仅用于已经通过 Docker 方式安装完成的 ThinkLink。 它使用 ThinkLink 容器内 Nginx 和 EMQX 原生 HTTPS，无需另装宿主机 Nginx。
配置、换证和回退会短暂重建 ThinkLink 与 EMQX 两个服务，请在维护时段操作。
1. 下载并启动
下载 tkl-tls 完整包，包含工具和中英文 Word/PDF 图文手册。只需要命令行工具时，可下载 tar.gz 工具包。
将包解压到服务器，进入 tkl-tls-2.0.0 目录，运行：
sudo bash tkl-tls.sh离线服务器可先在联网电脑下载，再传入服务器使用。
2. 按向导配置 HTTPS
将证书文件放到服务器，例如 /root/tls-input/，随后按提示填写：
- 域名：证书覆盖的域名，例如
iot.example.com。 - 证书路径：完整 PEM 证书链，例如
/root/tls-input/fullchain.pem。 - 私钥路径：匹配的未加密 PEM 私钥，例如
/root/tls-input/privkey.pem。 - 核对配置，输入 YES。
默认两个入口共用域名和证书。完成后访问：
- ThinkLink：
https://iot.example.com - EMQX 管理页面：
https://iot.example.com:18084
3. 端口与证书
| 端口 | 用途 | 配置方式 |
|---|---|---|
| 443 | ThinkLink 网页/API HTTPS | tkl-tls 自动配置 |
| 18084 | EMQX 管理页面 HTTPS | tkl-tls 自动配置 |
| 18083 | EMQX 原 HTTP 管理页面 | 保留原入口 |
| 8883 | 设备 MQTTS | 在 EMQX Web 配置 ssl 监听器 |
| 8084 | 设备 WSS，路径 /mqtt | 在 EMQX Web 配置 wss 监听器 |
管理页面 HTTPS 与设备 MQTTS/WSS 分别配置。 设备 WSS 地址为 wss://iot.example.com:8084/mqtt。工具保留原 HTTP/MQTT 入口，不会自动配置设备监听器或修改应用 MQTT 地址。
在安全组和防火墙放行所用端口，详见 安装端口表。
一套证书可以用于多个端口；不同域名共用证书时，证书 SAN 必须覆盖这些域名。内网 CA 需让浏览器和设备信任，并在下面的命令中使用 --ca-file。
4. 按需使用命令参数
需要独立域名、独立证书或自定义端口时，可使用命令配置：
sudo ./tkl-tls apply --thinklink-domain iot.example.com --cert /root/tls-input/fullchain.pem --key /root/tls-input/privkey.pem| 参数 | 用途 |
|---|---|
--emqx-domain emqx.example.com | EMQX 使用不同域名 |
--emqx-cert 与 --emqx-key | EMQX 使用独立证书和私钥，必须成对提供 |
--ca-file /root/tls-input/root-ca.pem | 使用内网 CA |
--thinklink-port 8443、--emqx-port 18443 | 修改宿主机 HTTPS 端口，并相应调整访问地址与端口放行 |
更多参数见包内 README。使用自定义 Compose 路径、服务名或 --root 时，后续操作保持相同参数。
5. 换证与回退
查看状态：
sudo ./tkl-tls status更换管理页面证书：
sudo ./tkl-tls apply --cert /root/tls-input/new-fullchain.pem --key /root/tls-input/new-privkey.pem域名和端口沿用上次配置。内网 CA 仍需传 --ca-file；独立 EMQX 证书仍需传 --emqx-cert 和 --emqx-key，否则默认共用本次 ThinkLink 证书。
需要撤销上一操作时执行：
sudo ./tkl-tls rollback换证和回退也会短暂重建两个服务。 通过 Web 上传的设备监听器证书需单独更新。
6. EMQX Web 配置设备 MQTTS/WSS
以下四张为 EMQX 5.8.8 真实中文界面截图。这里上传的是设备监听器证书，不是管理页面 HTTPS 18084 的配置步骤。
默认未发布 8883。使用设备 MQTTS 前，请由部署方配置端口映射和防火墙，并保护实际数据持久化。EMQX Web 不能修改 Docker 映射；TLS 配置后修改 Compose 须协调处理漂移保护。
6.1. 登录并选择 ssl 监听器
通过已配置的 https://iot.example.com:18084 登录 Dashboard，进入 管理 → 监听器。按类型 ssl、端口 8883 找到对应的 default，不要只按同名 default 选择。保留原 tcp 1883 和 ws 8083。
6.2. 核对监听地址与认证
保留监听地址 0.0.0.0:8883。普通单向 TLS 保持 双向认证关闭；这表示不要求客户端证书，客户端仍须验证服务端证书，并继续使用原用户名/密码认证与访问规则。
6.3. 上传证书与私钥
在 TLS Cert 和 TLS Key 处分别点击 重新设置，再点击 选择文件。从浏览器所在电脑分别上传 fullchain.pem 和 privkey.pem。这些是本地文件选择框，不是填写服务器 /root/tls-input/ 路径的地方。
第四张图展示私钥未填时的“请输入 TLS Key”校验提示，不代表配置成功。上传匹配的未加密 PEM 私钥，保留其他原有设置，再点击 更新；处理所有报错后重新打开监听器，核对保存后的持久化文件路径。
6.4. 验证与 WSS
使用设备或 MQTTX，连接证书覆盖的域名及 MQTTS 8883，开启 TLS 和服务端证书验证。内网 CA 需导入客户端信任；使用原认证信息，在授权测试主题完成连接、订阅、发布、消息接收和重连。维护重启或重建后再次核对证书、配置及消息收发，验证持久化。
WSS 选择 wss 类型的 default，通常使用 0.0.0.0:8084，路径 /mqtt；同样上传匹配域名的证书与私钥，确认端口映射，再测试 wss://iot.example.com:8084/mqtt。TLS 握手成功不等于 MQTT 认证或订阅发布成功。
设备端换证需重新上传并验证；管理 HTTPS 的 apply 不会自动替换这些文件。设备端恢复应使用此前备份的监听器配置和证书，并再次验证实际消息。
7. 常见问题
| 问题 | 处理 |
|---|---|
| 需要另装 Nginx 吗？ | 不需要，使用 ThinkLink 容器内 Nginx 和 EMQX 原生 HTTPS。 |
| 会升级 ThinkLink 吗？ | 不会，只配置 TLS，保留当前镜像和数据。 |
| 为什么 18083 仍是 HTTP？ | 新的管理 HTTPS 使用 18084，原 HTTP 入口保留。 |
| 设备仍返回旧证书？ | 管理页换证不会替换设备监听器证书，需通过 EMQX Web 单独更新。 |
| 证书报错？ | 核对域名、完整证书链、匹配私钥和有效期；内网 CA 需配置客户端信任。 |
| 外部无法访问？ | 检查域名解析、Docker 端口映射、安全组和防火墙。 |
恢复与配置文件
配置失败时工具会尝试回退。若断电或强制中断后提示 pending.json，先执行 sudo ./tkl-tls rollback。若提示 Compose 被外部修改，先核对变更。
保留 /opt/tkl-tls：其中包含私钥、配置备份和持久化数据，不要删除或作为日志上传。不要使用 docker compose down -v 或 docker volume prune 排查证书问题。Compose 保存为 JSON 格式属于正常行为。
已使用 1.0 旧网关
先按旧工具说明回退并释放端口，再使用 2.0.0；不要复用旧状态目录。旧版完整包和旧版工具包仅供历史恢复使用。
8. 配置完成后
打开两个 HTTPS 管理地址，确认浏览器证书、登录及文件上传下载正常。若使用设备 MQTTS/WSS，再验证设备或 MQTTX 的认证、订阅发布和重连。网页内的 MQTT 地址和文件链接仍需按实际部署配置。