Xiaomi Home 集成接入 Home Assistant：版本兼容、安装与实体规则的三套排障手册

Xiaomi Home 集成接入 Home Assistant版本兼容、安装与实体规则的三套排障手册【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home在 Home Assistant 上部署 Xiaomi Home 集成时最常见的三类失败是集成文件版本过旧、Home Assistant 核心版本不满足基线、更新集成后实体转换规则未刷新导致设备掉出仪表盘。本文面向首次安装该集成和从旧版本升级的用户按故障场景拆解版本门槛、安装路径与规则更新操作。安装前先核对版本门槛当前仓库 manifest.json 标记的版本是 v0.4.7hacs.json 声明 Home Assistant Core 不低于 2024.4.4、HACS 不低于 1.34.0README 同时要求 Operating System 镜像不低于 13.0。如果你的核心版本低于这个基线config flow 会在加载阶段直接失败正确做法是先升级 Home Assistant而不是回退该集成。依赖包由平台自动处理报错时再手动核对requirements 中的 construct2.10.56、paho-mqtt、numpy、cryptography、psutil 会在集成首次加载时由 Home Assistant 自动安装正常无需干预。只有日志报依赖缺失时才需要手动执行pip install construct2.10.56 paho-mqtt numpy cryptography psutil另外manifest 注册了 zeroconf 类型_miot-central._tcp.local.局域网发现中枢网关依赖同网段的 mDNS跨网段部署时本地模式不会生效。三条安装路径的取舍git、HACS 与手动拷贝git clone 加 install.sh便于回滚到指定版本把仓库放进 config 目录后执行仓库内的脚本cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home.git cd ha_xiaomi_home ./install.sh /config注意install.sh 会先删除旧的custom_components/xiaomi_home再拷贝新版执行完必须重启 Home Assistant。需要锁定旧版本时执行git fetch后git checkout v0.4.2再重跑脚本即可完成回滚这正是 README 推荐此方式的原因。HACS 一键安装与手动拷贝兜底HACS 中搜索 Xiaomi Home 并下载落点同样是config/custom_components手动路线则是把custom_components/xiaomi_home文件夹复制进 HA 的对应目录两者效果一致。只需装一次、不关心版本回滚的用户选这条路线即可。更新后设备掉出仪表盘实体转换规则问题设备规格到实体的映射在 miot/specs/ 中完成规则一旦变更就会影响存量实体两个历史版本必须了解。v0.3.0 改过 unique_id 生成规则勾选xiaomi_home 配置 更新实体转换规则后部分实体会换发新 unique_id引用旧 ID 的自动化和仪表盘卡片随即失效。提醒自动化数量多的用户先在配置中备份 automation 目录再执行该选项。v0.2.2 改过浴霸、空调、新风机的规则此版本调整了 climate 实体的转换规则更新后必须做两件事重启 Home Assistant然后进入集成配置页勾选“更新实体转换规则”并点下一步重新加载集成否则这三类设备不会正确显示。手改过 spec 文件必须手动刷新如果你编辑过miot/specs/下的spec_filter.yaml、spec_modify.yaml或multi_lang.json保存后 Home Assistant 不会热加载需要同样进入 CONFIGURE 页执行“更新实体转换规则”才生效。云端与本地控制路径的选择该集成的 iot_class 是 cloud_polling默认走云端链路。云端控制MQTT 订阅加 HTTP 指令集成通过 MIoT Cloud 的 MQTT Broker 订阅设备属性与事件消息指令经 HTTP 接口下发配置完成后全量拉取一次属性即转为推送模式对云端没有持续轮询压力。本地控制中枢网关是硬门槛本地模式要求小米中枢网关固件不低于 3.3.0_0023或内置中枢网关的设备软件不低于 0.8.9。网关自带 MQTT Broker集成在同网段直接订阅与发布状态更新不依赖外网这是它与云端方案的核心差别。LAN 控制是兜底项官方建议不开启没有中枢网关时可开启“更新 LAN 控制配置”直接控制同网段 IP 设备但它管不到 BLE Mesh 与 Zigbee 设备且官方明确提示可能引发异常非必要不启用。卡住时的两个排查入口先开 debug 日志定位在 configuration.yaml 中加入以下配置并重启该集成的日志级别会提到 debug登录失败、MQTT 订阅异常、规格解析报错都会显形logger: default: critical logs: custom_components.xiaomi_home: debug查变更日志再提 issue对照 CHANGELOG.md 确认当前版本是否已包含修复未解决的问题结合日志中的设备型号与网关固件版本提交 issue安装方式与版本要求以 README.md 为准贡献与开发细节见 CONTRIBUTING.md。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考