集成（Integration）的概念与用法

集成是 HA 的万能插头

把 HA 想成一台多功能主机，集成就是它后面那些形状各异的接口：米家设备需要一个集成，HomeKit 设备需要另一个，每一类协议、每一个云服务都对应一个集成。集成是 HA 与外部世界对接的标准模块，你不需要懂每个集成的内部实现，只要知道它装上之后能让你看到什么、控制什么。这也是 HA 区别于其它平台的关键——它把接入这件事标准化了，新增一个品牌对用户来说只是多走一遍同样的流程，而不是学习一套全新的操作。

集成与设备的关系是包含关系：装一个集成，它负责管理一类设备；装好之后，设备以实体（Entity）的形式出现在 HA 里，自动化和仪表盘围绕实体工作。这个层级关系贯穿全书，第一次接触多花两分钟消化一下，后面所有操作都会顺很多。

举个具体的例子：你装了米家集成，它的身份像是一个桥梁，登录你的账号之后把家里绑定的设备列表拉过来。你家那盏客厅灯在 HA 里就是一个设备，它可能同时有好几个实体——开关、亮度、色温，每个实体都能单独被自动化引用。所以同样一盏灯，能写出关灯、调亮度、调色温三种不同的规则。

理解了这三层，看 HA 的任何界面都不会再迷失：设备页面按集成来源分组，实体页面是可被引用的全部控制点，仪表盘上摆的是实体的卡片。三个层次三种用途，各管各的。

装一个集成的基本流程

图形界面里装集成的流程高度一致，学会了第一个就会第一百个：

1. 进入设备与服务页面，点添加集成。
2. 搜索品牌或协议名称（支持中文搜索，英文原名也行，手生的时候两种都试一遍）。
3. 按提示输入账号密码或确认配对。
4. 等待发现和初始化完成。
5. 完成后设备自动出现在设备列表里。

绝大部分集成的交互都遵循这五步。差别只在第三步：云类集成要你登录账号，局域网协议类要你按设备配对键，网关类要你填 IP 地址。社区里每个热门集成都有图文教程，遇到卡壳的步骤现查即可。

配对失败的常见原因也就那几个，背下来排查特别快：设备不在配对模式、HA 和设备不在同一网段、账号开了二次验证需要用专用密码、设备被别的平台占着没释放。照着四条排查，比自己瞎猜快得多。

第一次添加集成时还有个温馨提示：部分集成会请求账号数据的读取权限，授权之前大概扫一眼它要干什么。正规集成的权限都有限，但养成看一眼的习惯总比闭眼点确认好。

集成的配置项

装好集成不等于结束，大多数集成还有可调的配置项，点集成条目的配置按钮就能看到。常见可调内容：

• 轮询频率：云类集成多久向服务器拉取一次数据。调快点状态更新及时，调慢点省流量省服务器压力，按设备重要性折中。
• 区域分配：新设备默认归到哪个区域，也可以装完后单独改。
• 轮询范围：选择拉取哪些设备，家里云设备多的时候，只同步需要的那部分能明显减轻负担。
• 调试日志：排查疑难杂症时临时打开，平时关着省磁盘。

一个老手才知道的经验：集成卡住不动时，别急着整个重启 HA。先重载集成，无效再删除重新装（账号登录信息一般还在，不用重输），最后才考虑重启。九成的问题在前两步就解决了。

集成的四种工作方式

理解集成的工作方式，能帮你预判它的稳定性和速度。同样一盏灯，走不同的链路体验天差地别。按通信路径可以分四类：

每种方式的体感差异非常直观：直连局域网的设备，按下开关到灯亮几乎无感；云端轮询的设备，打开 App 要转圈，自动化触发后还要等几秒。所以在接入新设备时，先问一句它走哪条链路，再决定要不要花精力优化。

一个直觉判断：能直连的就别走云，不能直连的就近找网关。家里那些语音喊一声要等两秒才有反应的灯，多半就是云端轮询的受害者。

这张表还有个隐藏用法：判断某个设备值得花多少精力。比如一个十块钱的云插座，花一小时研究怎么本地化显然不划算；而每天开关几十次的主灯，就值得认真把它挪到本地链路上。精力分配跟着使用频率走，是接设备阶段的重要心法。

集成市场：官方与社区

HA 自带的集成库条目众多，涵盖主流品牌和协议，这些由官方维护，版本升级时跟着核心一起更新，兼容性由官方兜底。官方没有的，去 HACS 找社区版本——前一篇提过，HACS 是第三方的集成市场，很多前沿或小众设备靠它支持。

安装来源不同，但装好之后用起来没区别，都出现在同一个集成列表里。需要注意的两点：

• 官方集成随系统升级自动兼容，HACS 集成偶尔需要等作者跟进。
• 出问题时排查范围不同：官方集成看核心仓库的动态，HACS 集成看对应组件的仓库。

一个常见的迷惑行为是装太多重复功能的集成：米家官方集成、Miot 社区集成、各种米家桥接同时开。重复集成会导致同一个设备出现好几遍，实体 ID 撞车，自动化也不知道该引用哪个。选一个最合用的留着，其它的坚决关掉。

已装集成的日常管理

用了一段时间之后，你的集成列表会越来越长。几条管理经验：

• 重载代替重启：改了某个集成的配置，可以用重载功能单独生效，不用整个系统重启，家人完全无感。
• 禁用而不是删除：暂时不用的集成可以先禁用，留着配置不占运行资源，想用随时开。
• 定期清理：设备已经卖了的、服务已经不用的集成，删掉免得日志里一直报错。
• 留意日志：集成列表里每个条目的状态就是健康指示灯，黄色红色点进去就能看到原因。
• 凭据集中放：集成的账号密码写进 secrets.yaml，别散在配置里，换机器时少操一份心。

集成装好之后

集成把设备带进 HA，但这只是起点。设备进来之后通常还有三件事要做：给实体起新名字（默认名字往往很机器味儿）、分配到区域（客厅卧室）、确认关键实体。这些组织工作在第 4 章详细讲，现在只要记住一条：刚接入的设备先别急着写自动化，先把名字和区域理顺，否则一周后你自己都不知道 sensor.living_room_3 是什么。

实体命名有个实用技巧：用「位置加功能」的格式，比如客厅主灯、卧室温度传感器，全家通用的语义比厂商起的名字好认。这件事现在花十分钟，以后每写一条自动化都受益。

另一个值得养成的习惯是给集成分层：把高频使用的集成排在列表顶部（新版界面支持排序或常用标记），找起来不用每次翻长列表。设备一多，这种小优化每天能帮你省下不少点击。安装顺序也有学问——先装协议类（Zigbee、Matter），再装平台类（米家、涂鸦），最后装服务类（天气、推送），这样后续配置有需要时基础已经打好。

延伸阅读

常见集成名词对照

帮你对上中文名字，搜索集成时用得上。这些名字在界面里大多是英文，第一次找会觉得眼花，对照几次就熟了：

• 小米（Xiaomi）：官方小米集成，走账号云端
• Xiaomi Miot Auto：社区维护的米家深度集成，功能更全
• 涂鸦（Tuya）：官方涂鸦云集成
• HomeKit Bridge / HomeKit Controller：HomeKit 双向支持
• Zigbee Home Automation（ZHA）：官方 Zigbee 协议栈
• Zigbee2MQTT：社区 Zigbee 方案，覆盖设备更广
• Matter：官方 Matter 协议栈（近年版本已原生支持）
• MQTT：通用消息协议，接自制硬件和各种桥接

表里的前两兄弟（ZHA 与 Zigbee2MQTT）下篇就要详细讲，米家和涂鸦的桥接方案在米家那篇展开。先记住它们各自的大致分工，读到具体章节时你会回来感谢这份对照表。

延伸阅读

• 群晖 DSM 实用指南：NAS 上同时运行 HA 与桥接服务的资源分配
• 软路由入门指南：局域网发现与组播对集成配对的影响
• OpenWrt 从入门到精通：网段与组播设置，决定集成能否发现设备