Home Assistant homekit.unpair 深度解析强制解除 HomeKit 配件配对并重新配对【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iohomekit.unpair是 Home Assistant 官方文档home-assistant.io中 HomeKit Bridge 集成提供的一个动作action用于强制移除某个配件或桥接器上的全部配对关系以便重新配对。当你不想删除并重建整个 HomeKit 集成条目而只是想让某个失联的配件重新可用时它就是首选工具。读完本文你将掌握该动作的 UI 与 YAML 两种调用方式、device_id参数的含义、执行后必须完成的恢复步骤以及重新配对失败时的排查路径。动作定位强制解配而非删除集成根据动作文档 homekit.unpair 的定义Unpair an accessory or bridge动作的核心行为是从指定配件accessory或桥接器bridge上强制移除所有配对让你可以重新配对典型使用场景某个配件不再响应而你希望避免删除集成条目再重新添加这一更重的操作当 HomeKit 以 UI 方式配置时该动作可以避免删除并新建集成实例这一有时相当耗时的流程。它和另一个常见需求——重置配件配置homekit.reset_accessory——是两回事reset 处理的是配件在 HomeKit 中的属性结构过期unpair 处理的是客户端与配件之间的配对凭据损坏。为什么会出现配对失效公钥丢失机制HomeKit 集成的工作机制值得先弄清楚。HomeKit Bridge 集成文档的 Unpairing and Re-pairing 小节第 720–724 行说明了根本原因HomeKit 集成会为每个已配对的设备记住一把公钥public key。配对失败偶尔会导致某台设备配对应的公钥丢失。此时一台或多台设备会把配件显示为不可用unavailable。在这种情况下可能需要解除并重新配对以确保集成持有每个已配对客户端的公钥。也就是说homekit.unpair解决的不是网络问题而是配对凭据状态损坏问题。执行该动作后集成重新回到未配对状态所有客户端需要重新走一遍配对流程从而让集成重新记录每个客户端的公钥。集成文档还记录了一个相关的已知现象Bridge spontaneously unpairs 小节iOS 12 及更早版本设备会自发地移除配对。官方建议确保所有具有家庭管理员权限的 iOS 设备运行 iOS 13 或更高版本无法升级时可在该设备的 iCloud 设置中禁用 Home。这类莫名解配的场景下homekit.unpair同样是快速恢复的入口。从 UI 执行解配如果你习惯可视化编辑Home Assistant 会一步步引导你完成该动作的配置选择目标、调整选项后保存即可无需 YAML 知识。步骤如下源自动作文档 homekit.unpair进入SettingsAutomations scenes打开一个已有的自动化或脚本或选择Create新建新建自动化时在When部分添加触发器脚本不需要触发器在Then do部分选择Add action在搜索框中搜索并选择HomeKit Bridge: Unpair an accessory or bridge选择要解配的Device选择Save。UI 选项说明选项说明必填Device要解配对的设备配件或桥接器是注意 UI 中的选择对象是设备Device它会映射到 YAML 中的device_id参数而不是实体 ID。这与homekit.reset_accessory以entity_id为参数形成对比选择错误的参数会直接导致动作无法命中目标。在 YAML 中调用 homekit.unpair在 YAML 中该动作的名称为homekit.unpair。官方文档给出的调用示例action: | action: homekit.unpair data: device_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4执行后所选设备上的所有配对关系会被移除你可以再次发起配对。YAML 选项说明选项说明类型必填device_id要解配的配件或桥接器的设备 IDstring是device_id可以从设备注册表中获取在 UI 中进入对应设备页面即可看到其标识也可以在 Developer tools 中查看设备注册信息。该参数是动作唯一的入参没有默认值省略时动作无法定位目标设备。与 homekit.reload、homekit.reset_accessory 的协作HomeKit 域的三个动作各有分工组合使用可以覆盖绝大多数恢复场景动作参数作用典型触发时机homekit.unpairdevice_id强制移除配件的全部配对配件显示不可用、公钥丢失、配对状态损坏homekit.reload无重新加载 YAML 定义的 HomeKit 实例并重处理 YAML 配置修改了 YAML 中 HomeKit 相关配置后不想重启homekit.reset_accessoryentity_id重置一个或多个配件使其回到首次设置状态媒体播放器 device class 改为tv、关联电池传感器、实体支持新 HomeKit 特性后其中homekit.reload有两个值得注意的限制来自其文档它只重新加载 YAML 定义的实例通过 UI 创建的实例不受影响且只有管理员账户可以执行。如果你的 HomeKit 是 UI 实例修改后并不存在reload YAML这条路径unpair 重新配对往往是更实际的恢复手段。动手试验不写 YAML 直接执行按照动作文档的 Try it yourself 引导打开SettingsToolsActions即 Developer tools 的 Actions 面板搜索homekit.unpair在字段中填入目标device_id点击Perform action。你可以在不编写任何 YAML 的情况下直接在真实实例上观察动作效果——这是验证设备 ID 是否正确、以及观察解配后客户端表现的最快方式。解配之后恢复与重新配对执行homekit.unpair后动作文档的 Good to know 部分给出了两条必须记住的事项解配之后配件的表现与首次设置时完全一致。你需要重新恢复它的名称name、分组group、房间room、场景scene和自动化automation设置——这些是客户端在 HomeKit 侧保存的解配会一并清空当 HomeKit 通过 UI 配置时这个动作避免了有时相当耗时的删除并重建集成实例流程是更轻量的恢复路径。重新配对的流程重新配对遵循 HomeKit Bridge 集成文档 Setup 小节的标准流程打开 Home Assistant 前端会出现一张展示配对二维码和PIN 码的新卡片若 PIN 未显示检查界面左下角通知铃铛图标打开 Apple 的HomeApp点击Add Accessory扫描二维码或选择Dont Have a Code or Cant Scan?后选择Home Assistant Bridge点击Add Anyway确认添加Uncertified Accessory输入 PIN 码扫描二维码时可跳过点击Next最后点击右上角DoneHome Assistant Bridge与各配件应出现在 Home App 中之后即可通过 Home 与 Siri 控制 Home Assistant 实体。重新配对失败时的排查手段如果解配后重新配对卡住集成文档的 Errors during pairing 一节提供了一套标准化的排查组合拳1. 打开调试日志定位问题在configuration.yaml中加入logger: default: warning logs: homeassistant.components.homekit: debug pyhap: debug2. 仍失败时改用最小配置先只暴露一个演示实体确认桥本身可以完成配对homekit: filter: include_entities: - demo.demo3. 清理旧的配对状态文件。集成文档指出如果之前配对过即使是不成功的配对可能需要删除配置目录中的.homekit.state文件才能再次成功配对。执行前建议先停止 Home Assistant 实例。4. 检查网络前提iOS 设备必须与 Home Assistant 设备处于同一局域网Docker 部署需要network_mode: host遇到NonUniqueNameException时可尝试在zeroconf集成中启用default_interface: true并设置唯一名称如name: MyHASS42。适用前提与限制homekit.unpair面向HomeKit Bridgehomekit域参数为device_id不接受实体 ID若目标是以实体维度操作的场景如重置某实体的配件结构应改用 homekit.reset_accessory解配是有状态操作客户端侧的名称、房间、场景与自动化配置都会丢失执行前请确认已记录这些设置或在 Home App 中截图留存本文内容以当前仓库中的文档为准对应 Home Assistant 官方用户文档中 HomeKit Bridge 集成的动作参考具体 UI 文案可能随版本更新而变化。小结homekit.unpair是 Home Assistant 中处理配件失联、公钥丢失类配对问题的轻量级工具一条action: homekit.unpair加一个device_id即可强制清空某配件的全部配对关系跳过删除并重建集成条目的重操作代价是需要重新配对并恢复 Home App 侧的名称、房间与场景配置。配合 homekit.reloadYAML 实例重载与 homekit.reset_accessory实体维度重置以及集成文档中的调试日志与最小配置排查法可以覆盖 HomeKit Bridge 从配置变更到配对修复的完整运维闭环。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考