Home Assistant Home Connect 设备离线、状态不更新：5类典型故障一次修好

Home Assistant Home Connect 设备离线、状态不更新：5类典型故障一次修好

【免费下载链接】core:house_with_garden: Open source home automation that puts local control and privacy first.项目地址: https://gitcode.com/GitHub_Trending/co/core

凌晨两点，洗碗机面板显示"运行中"，HA 面板里那台设备却已经灰了40分钟，点"启动"毫无反应。Home Assistant Home Connect 设备离线、状态异常，断点往往落在认证、网络、事件流、限流、设备五层之一，而不是笼统的"网络问题"。本文先定位断在哪一层，再给出逐层修复动作，完整分诊约需10到20分钟。

🔍 症状分诊：Home Assistant Home Connect 设备离线断在哪一层

先按表格定位层，再跳到修复手册对应小节，分诊阶段不需要执行任何修复操作。

机制透视：集成内部到底在跑什么

条目 setup 时，Home Assistant 先从 OAuth2 配置条目取访问令牌；刷新令牌失效直接抛ConfigEntryAuthFailed，网络不通则抛ConfigEntryNotReady，这是"认证层"与"网络层"的分界点。逻辑在 homeassistant/components/home_connect/init.py 的async_setup_entry中完成。

状态更新依赖双通道：一条常驻的服务器推送事件流，加每台设备一个 DataUpdateCoordinator 轮询。事件流断线后的重试策略是 10 秒起步、每次失败翻倍、上限 1 小时，见 homeassistant/components/home_connect/coordinator.py 的_event_listener。流长时间中断，设备状态就停更，这正是 Bosch 家电 HA 状态不同步的常见根源。

轮询遇到 429 时不会立刻报错，而是按retry_after休眠后重试，默认回退 60 秒，定义在 homeassistant/components/home_connect/const.py。实体发起的服务调用还经过constraint_fetcher装饰器，捕获 TooManyRequestsError 后改期重发，见 homeassistant/components/home_connect/entity.py。

每台设备的数据组织成一组按 BSH 键索引的字典，与诊断最相关的字段：

{ "BSH.Common.Status.OperationState": "Run", "BSH.Common.Status.DoorState": "Closed", "BSH.Common.Status.RemoteControlActive": "true", "BSH.Common.Status.RemainingTime": 1200, }

🔧 根因修复手册：逐层处理 Home Connect 设备离线

修复认证层：OAuth 令牌失效

确认信号

grep -E "Unauthorized|ConfigEntryAuthFailed" /var/log/home-assistant.log

预期输出包含UnauthorizedError或条目在界面显示"需重新授权"。若 grep 为空且全部设备同时变灰，转网络层。

修复动作

1. 在 设置 → 设备与服务 → Home Connect 卡片上完成重新授权，浏览器走完 OAuth 流程。
2. 授权完成后重载条目，重启事件流与全部协调器：

重载 Home Connect 配置条目

service: homeassistant.reload_config_entry data: entry_id: "替换为你的条目 ID"

验证闭环：条目状态回到已加载，各设备实体由灰变可用，日志不再新增 Unauthorized 行。

修复网络层：服务器到 API 不通

确认信号

curl -sI https://api.home-connect.com/api/homeappliances | head -n1

预期输出HTTP/2 401或HTTP/1.1 401 Unauthorized。返回 401 说明连接通但令牌未验证，网络层正常；超时或 DNS 解析失败才是网络层故障。

修复动作

1. 检查服务器 DNS 与 443 出站策略；容器部署时确认网桥网络与默认路由。
2. 走代理的环境为容器配置代理后重启 Home Assistant。
3. 重测上述 curl，直到返回 401。

验证闭环：curl 返回 401 后，条目停止ConfigEntryNotReady重试并自动完成加载。

修复事件流层：流中断或连接抖动

确认信号

grep -E "Non-breaking error|Too many connected/paired" /var/log/home-assistant.log | tail -n 20

预期输出两种之一：Non-breaking error (...) while listening for events, continuing in N seconds，N 从 10 秒起按倍增加；或Too many connected/paired events，表示设备在反复连接断开，协调器已主动停用更新，每小时 8 次即触发。

修复动作

1. N 持续增大时，拔除设备电源 30 秒再通电，强制设备侧重建连接。
2. 出现 too many 警告时，优先排查路由器到设备的信号，再断电软复位设备。
3. 重载配置条目，重启事件流监听。

这一步卡住的话，多数情况不是 Home Assistant 的问题，设备侧网络模块才是源头。

验证闭环：日志出现新的事件流活动，continuing in的间隔回到 10 秒，设备状态恢复实时刷新。

修复限流层与设备层：429 节流和真离线

确认信号：终端执行grep -c "Rate limit exceeded" /var/log/home-assistant.log，非零返回说明存在 429 限流，日志同时记录了每次重试等待的秒数；无 429 且仅单台设备离线，则属设备层，用 Home Connect APP 确认该设备是否在线。

修复动作

1. 限流层：降低自动化查询频率，同一设备两次控制间隔留足 30 秒，避免并发下发指令。
2. 设备层：断电 30 秒重上电，在 APP 中确认设备在线。
3. 控制报 Remote control disabled 时，在设备面板开启远程控制，对应remote_control传感器应变为 on。

验证闭环：状态更新延迟从分钟级回到秒级，日志中 429 计数停止增长。

如果以上都试过仍然不行：四层逐一排除后条目依旧加载失败或单台设备不恢复，属于设备侧协议异常这类少数情况。把 home_connect 组件日志级别调到 DEBUG 跑一轮，连同 设置 → 设备与服务 → Home Connect 条目菜单里的诊断数据一并导出，提交到 Home Assistant 社区论坛，并附上复现步骤与固件版本。

🛡️ 主动防御：让问题不再静默发生

当设备远程控制状态变为 off 时，立即推送到已配置的 notify 服务，避免故障静默累积：

# 设备远程控制失效时推送通知 alias: Home Connect 远程控制失效告警 trigger: - platform: state entity_id: binary_sensor.dishwasher_remote_control to: "off" action: - service: notify.mobile_app_phone data: message: "{{ trigger.to_state.entity_id }} 远程控制已关闭，检查设备网络"

配置后在状态视图里观察触发与推送链路是否闭环：

低频维护建议：

• 每月对每台设备断电复位一次，清除临时性网络故障。
• 在 Home Connect APP 中检查固件版本，保持更新。
• 关注 Home Assistant 版本发布说明，及时获知 Home Connect API 变更与集成行为调整。

下次洗碗机深夜变灰，先查断在哪一层，再动手。更多实现细节见 homeassistant/components/home_connect/ 源码目录。

【免费下载链接】core:house_with_garden: Open source home automation that puts local control and privacy first.项目地址: https://gitcode.com/GitHub_Trending/co/core