设备离线与重连问题排查
什么是 unavailable / unknown
Home Assistant 实体有几个特殊的状态值：
| 状态 | 含义 |
|---|---|
unavailable | Home Assistant 知道这个设备曾经存在，但现在无法连通 |
unknown | 实体刚创建或刚重启，还没拿到有效状态 |
none | 实体被删除或状态清除 |
最常见的故障是实体变成 unavailable。
排查步骤（按概率排序）
第一步：确认物理层面
检查 1——设备是否通电
- 无线设备（Zigbee/Z-Wave）：换电池
- 有线设备：检查电源和网线
- 智能插座/开关：手动操作一下看能不能正常开关
检查 2——网络是否正常
- WiFi 设备：去路由器后台看设备是否还在列表里
- Zigbee 设备：去 ZHA 或 Z-Wave JS UI 看网络拓扑图，设备是否在线
- Z-Wave 设备：去 Z-Wave JS UI 看状态
检查 3——重新配对
设备经常显示 unavailable → 先尝试重新配对（移除设备 → 恢复出厂 → 重新配对）。很多"神秘消失"的设备重新配对后就好了。
第二步：检查 USB 适配器
Zigbee 和 Z-Wave 设备的可用性高度依赖 USB 适配器：
Zigbee/Z-Wave 适配器检查清单：
- 适配器是否插紧了？拔了重插
- Home Assistant 是否识别到适配器？Settings → System → Hardware → 应该能看到串口设备
- 驱动问题：Windows 上某些旧适配器需要手动装 CH340 或 CP210x 驱动
- USB 供电不足（树莓派尤其严重）——换官方电源
- USB 3.0 干扰 Zigbee 2.4GHz——用 USB 延长线把适配器拖远一点
第三步：检查集成配置
- Settings → Devices & services → 找到故障设备所属的集成
- 点进去 → 看集成状态是否显示 Connected / Disconnected / Error
- 如果显示 Error → 看详情页的错误信息
- 尝试 Remove + 重新 Add 集成
- 某些集成（如小米 MIoT、Zigbee2MQTT）有独立的 Web UI → 检查那个 UI 上设备是否显示在线
第四步：检查日志
最有用的排查手段——Home Assistant 日志会告诉你它为什么认为设备离线：
- Settings → System → Logs → 搜索实体 ID 或集成名
- 常见日志关键词：
Failed to call service→ 服务调用失败Connection refused/Connection timeout→ 网络不通Entity not available→ 集成已经断开Invalid response from device→ 设备返回了奇怪的数据
- 可以在 Developer Tools → Logs 里直接看
第五步：重启（万能但治标不治本）
如果上面都试过了还是不行：
- 先只重启 Home Assistant：Settings → System → Restart → Restart Home Assistant
- 不行 → 重启整个主机：断电重插
- 还不行 → 恢复备份快照（如果备份在出问题之前）
- 最后手段：重刷 Home Assistant OS（确保有备份！）
常见故障场景
场景一：Zigbee 设备批量掉线
如果多个 Zigbee 设备同时 unavailable：
- 很可能是 USB 适配器问题
- 先检查 USB 供电（树莓派 5V 3A 官方电源很重要）
- 再检查适配器是否松了
- 最后看 ZHA Diagnostics → Network topology → 设备是否在拓扑图上
场景二：单个设备间歇性 unavailable
- 信号差——设备离 USB 适配器太远
- 加路由节点（Zigbee 插电设备自动成为路由器）
- 用 USB 延长线把适配器拖远
- 换 Zigbee 频道
场景三：小米设备从 MIoT 集成消失
小米 MIoT 云集成有时 Token 会失效：
- HACS → Xiaomi MIoT 集成 → 重新配置
- 或在集成里更新 Token
- 如果是 LAN 模式（局域网直连），检查设备 IP 是否变了（小米设备有时会换 IP）
场景四：Companion App 显示 unavailable
- 手机上的 Home Assistant App 被杀掉了后台进程
- 重启手机上的 Home Assistant App
- iOS：确认后台刷新权限已开（设置 → 通用 → 后台 App 刷新 → Home Assistant → 开）
- Android：确认电池优化已关（设置 → 应用 → Home Assistant → 电池 → 不限制）
场景五：Matter 设备消失
- Matter Server Add-on 是否在运行
- Thread Border Router 是否在线
- 设备是否还在 Matter 控制器列表里（Settings → Devices & services → Matter → 检查设备）
场景六：设备恢复出厂设置后 Home Assistant 里还有"幽灵"实体
手动清理：Settings → Devices & services → 找到对应集成 → 移除那个幽灵设备。或重启 Home Assistant。
预防性措施
| 措施 | 说明 |
|---|---|
| 定期备份快照 | 每周一次 + 升级前一次 |
| USB 适配器用延长线 | 避开 USB 3.0 干扰 |
| 树莓派用官方电源 | 电压不稳是设备掉线的第一原因 |
| 避免频繁换路由器 | 每次换路由器设备 IP 可能变 |
| 加路由节点 | Zigbee 插电设备 = 自动路由节点 |