EMQX接入与证书维护
EMQX只做MQTT Broker，使用后端HTTP回调认证授权。不要配置Broker直连PostgreSQL，不使用匿名放行、超级用户设备或公共通配ACL。
配置认证授权
前提：后端可从Broker访问、设备/产品记录存在、服务用户名密码与独立回调密钥已安全配置。以下在EMQX控制台或其受保护管理API配置，实际菜单随安装版本变化，本轮未连接控制台验证。
| 项目 | 值/要求 |
|---|---|
| 认证POST URL | https://yunstack-s.duruofu.cn/api/v1/mqtt/access/authenticate |
| 认证JSON | {"username":" |
| 授权POST URL | https://yunstack-s.duruofu.cn/api/v1/mqtt/access/authorize |
| 授权JSON | {"username":" |
| HTTP头 | Content-Type: application/json；x-mqtt-auth-token为独立随机密钥，与后端MQTT_AUTH_HTTP_TOKEN一致且至少32字符 |
| 响应 | 认证{"result":"allow","is_superuser":false}或deny；授权{"result":"allow"}或deny |
| 失配/服务异常 | 拒绝；不在回调失败后降级匿名 |
设备认证按productId+physicalId查Device.secret，支持版本化摘要验证；服务身份用MQTT_USERNAME、MQTT_PASSWORD和MQTT_CLIENT_ID_PREFIX，保留用户名不可降级成设备。授权再按精确Topic白名单判断，见MQTT。认证缓存启用与缓存期限需在实际Broker核实，撤销密钥后也要考虑已有连接，不假设数据库改密钥会立即断开所有会话。
TLS与监听
公开设备连接使用8883，服务域名证书须匹配yunstack-s.duruofu.cn；客户端验证可信根与主机名。既有迁移记录表明1883与8083明文监听已停止且持久化；Docker映射残留不等于监听仍启用。本次文档审核未重新扫描端口。
在可访问环境验证，不发送设备凭据：
openssl s_client -connect yunstack-s.duruofu.cn:8883 -servername yunstack-s.duruofu.cn -verify_return_error </dev/null应验证链与域名无错误；证书时间、SAN和完整中间链都要检查。ESP-IDF下载OSS交叉签名链须启用CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY=y，不关闭校验绕过。
1Panel续期与EMQX同步
1Panel负责申请/续期网站证书，但EMQX使用的复制文件不会因此天然更新。既有服务器另设yunstack-mqtt-cert-sync脚本和systemd path/timer监听/定时同步并热重载，私钥只留服务器。本机local-tools工具不随仓库分发；新部署需管理员提供证书源、Broker实际挂载目录、权限和同步单元配置，不能照搬未知路径。
运维在服务器检查：
systemctl status yunstack-mqtt-cert-sync.path yunstack-mqtt-cert-sync.timer
journalctl -u yunstack-mqtt-cert-sync.service --since '1 day ago'对比1Panel源证书和EMQX副本的有效期/公钥摘要，确认8883实际对外证书已更换。只检查磁盘文件不够。此前验证过同证书同步与目录触发，尚不能据此证明未来一次真实自动签发周期成功。
修改EMQX配置前导出完整listeners配置并妥善保护。局部conf load可能将未带入的监听恢复默认，重新开放明文；热重载后必须检查8883证书、1883/8083关闭、现有认证与订阅。失败恢复完整旧配置和证书副本，再验证，不重建数据库或禁用TLS。
常见故障
- 8883连不上：查监听、代理是否为TCP透传、防火墙、DNS与容器端口，不把HTTPS反代当MQTT TCP代理。
- 证书过期：区分1Panel续期失败、复制失败、权限失败和热重载失败。
- Broker连接成功但无消息：查SUBACK是否拒绝；后端重启时回调短暂失败会触发订阅重试，单看Connected日志不足。
- 认证401：先检查回调头和独立密钥，不将MQTT服务密码填到回调密钥。
- 设备被踢：检查是否有模拟器复用了真实ClientId；模拟测试必须用独立随机身份。