Home Assistant 从 HiveMQ Cloud 迁移

请结合 HiveMQ 迁移指南使用。本文是配置与验收指南，不代表已认证所有 Home Assistant 部署。2026 年 10 月 20 日的托管检查未通过保留消息一致性验证，包含预期值回放与包标志检查。依赖保留消息的应用，须通过具体 Home Assistant 负载的重启和状态恢复测试后才能验收。 保留消息需要 Growth 或 Scale，Starter 不包含该功能。

先规划自动发现与权限

盘点设备发现、状态、命令和可用状态 Topic。Home Assistant 可在设备收到 birth 消息后重新发送配置，也可使用保留发现消息恢复实体。两种恢复方式不同，须核对各设备实际实现；更换 Broker 并不会自动让设备重新发送配置。

为独立演示设备创建设备身份与 Home Assistant 身份，配置以下策略。实际部署只能扩展已审查的 Topic：

这些受限策略只覆盖演示传感器，并非所有集成。真实设备组还需要发现、命令和可用状态规则。验证允许和拒绝的操作，不要给每台设备开放全部 #。

重新配置 Broker

先备份 Home Assistant 与原连接配置。在“设置 → 设备与服务 → MQTT → 重新配置”中，填写 RunMQTT 安全域名、端口 8883 和新的 Home Assistant 设备凭据。在其他设置中开启 Broker 证书校验，证书受内置根证书信任时选择 Auto，保持主机名校验开启。确认当前 Home Assistant 版本要求的协议，现行官方文档要求 MQTT 5。

修改 Home Assistant 不会同步修改传感器、网关或后端应用，每个客户端都需要新地址和自己的凭据。协调切换，确保 Home Assistant 与设备在同一 Broker 上交换状态。各版本界面选项以官方 MQTT 集成文档为准。

验证自动发现与当前状态

Home Assistant 连接且演示权限已生效后，用已授权测试发布者向 homeassistant/sensor/migration_demo/temperature/config 以 QoS 1 发布以下合成 JSON：

{
  "name": "Migration demo temperature",
  "unique_id": "runmqtt_migration_demo_temperature",
  "state_topic": "migration-demo/temperature",
  "unit_of_measurement": "°C",
  "device_class": "temperature"
}

再向 migration-demo/temperature 发布 21.5，确认演示实体出现并显示该值。发布 22.0，确认状态更新。这只能证明在线发现与状态路径，不能证明离线恢复。只有在支持的套餐中刻意验证保留恢复路径时才开启 retain。

重启 Home Assistant。若设备通过 birth 触发发现，应确认其订阅 homeassistant/status，收到 online 后重新发送配置与当前状态。若依赖保留发现与状态，应验证新订阅时的回放，并与设备实际当前状态比较。单独验证可用状态与过期状态处理，不要将瞬时命令或触发事件作为保留状态重放。

验收或回退

要求重启后重新发现、当前状态正确、离线与在线变化符合预期、越权操作被拒绝，真实可控设备还须确认命令执行结果。断网和设备重启后重复测试，覆盖真实订阅数和启动突发，而非只测一个演示传感器。

任一必要行为失败即停止扩大批次，在 HiveMQ 仍可用时协调恢复旧连接配置。验收完成前保留源集群，并在退役前完成迁移。清理演示时发送空发现消息删除演示实体，清除可能存在的保留配置和状态，再撤销测试身份；必要时在 Home Assistant 中移除临时实体。

保留消息兼容性边界详见会话与投递。需要评估时联系 RunMQTT，提供版本、所需功能和去除隐私的复现步骤，不要发送密钥或家庭数据。