【免费下载链接】home-assistant-matter-hub
Publish your Home-Assistant Instance using Matter.
Home-Assistant-Matter-Hub（HAMH）是一个开源的 Matter 桥接项目，它把 Home Assistant 中的灯光、传感器、门锁、扫地机器人等实体发布为 Matter 设备，让 Apple Home、Google Home、Alexa、SmartThings 等 Matter 控制器通过局域网直接控制它们。很多用户遇到过设备过一会儿就显示"No Response"、重启后才恢复的情况——问题通常出在 Matter 会话（Session）、mDNS 广播和多 Fabric（多控制器）连接这三处。本文带你快速看懂 HAMH 背后维护这些连接的 5 大关键机制：会话生命周期监督、死会话清理、会话轮换与卡死看门狗、mDNS 地址自动刷新，以及多 Fabric 并存管理。
上图是 HAMH 的桥接总览页：一张桥（Bridge）上运行着 161 个设备，连接了 2 个 Fabric，使用标准端口 5540。"2 fabrics" 就意味着这张桥同时被两个控制器（例如 Apple Home + Alexa）管理——这正是后文多 Fabric 机制要处理的场景。
什么是 Matter 会话？为什么需要"监督"
Matter 设备与控制器配对后，双方之间会建立一个加密会话（CASE session）。控制器通过这条会话订阅设备状态变化，并下发控制命令。会话是"活的"，但也可能：
- 悄悄断掉：控制器重启、网络抖动后，旧会话残留在服务器端；
- 卡住不刷新：会话还"活着"（还在应答），但控制器实际已停止消费数据；
- 越积越多：控制器反复重连，旧会话不被清理，数量无限增长。
HAMH 用一个专门的"会话监督器"统一管理这些问题，核心实现在 session-supervisor.ts。它挂载到 matter.js 的SessionManager上，监听会话的打开、关闭和订阅变化事件，并在此之上运行多条清理与自愈规则。
机制一：死会话与僵尸会话的自动清理
监督器时刻统计"活跃订阅数"。当所有订阅都丢失但会话还在时，说明控制器与桥之间的数据通路已断，HAMH 会等待 60 秒后强制关闭这些死会话；开启fastSessionRecovery特性的桥则只需等 5 秒。这些参数定义在 session-rotation.ts：
| 参数 | 默认值 | 说明 |
|---|---|---|
DEAD_SESSION_TIMEOUT_MS | 60 s | 订阅全部丢失后，多久关闭死会话 |
FAST_DEAD_SESSION_TIMEOUT_MS | 5 s | 开启快速恢复时的等待时间 |
STALE_SESSION_QUIET_WINDOW_MS | 5 min | 0 订阅会话必须"完全安静"多久才算死 |
注意那个 5 分钟的"安静窗口"：控制器有时只是短暂安静（比如 Apple Home 在做内部整理），如果立刻关闭会话，设备就会反复掉线。HAMH 只在确认对端真正停止通信后才动手，关闭后还会立即触发一次 mDNS 重新广播，提醒控制器"该重连了"。
另外，当同一个控制器（同 peer、同 Fabric）建立新会话时，它的旧会话会被标记为"被取代"（superseded），安静 5 分钟后自动清理——这解决了反复闪断的控制器（比如某些 Echo 设备）让会话堆积到上百个的问题。
机制二：会话轮换（Session Rotation）
有些卡死是无法"探测"出来的：会话一切正常，但控制器内部状态坏了，设备在 App 里永远转圈。HAMH 的解法是定期轮换——主动关闭超过最大年龄的会话，迫使控制器重新建立 CASE 会话并重新订阅，一次"无感重启"就能救回卡死的设备。
- 默认最大会话年龄为4 小时，可在桥设置中调整为 1～168 小时，设为
0则禁用轮换（Docker 部署可用环境变量HAMH_MATTER_SESSION_MAX_AGE_HOURS）； - 检查每5 分钟执行一次，日志中会出现
Rotating session字样； - 该配置热生效，无需重启插件。
相关逻辑见 session-rotation.ts 中的DEFAULT_SESSION_MAX_AGE_HOURS与ROTATION_CHECK_INTERVAL_MS。
机制三：卡死看门狗（Wedge Watchdog）
轮换是"按年龄"处理，而看门狗是"按症状"处理，更精准。典型症状是 Apple Home 设备卡在"Updating…"：控制器仍在应答报文（所以常规活性检测认为它活着），却已经 45 分钟没发过任何交互请求了。
HAMH 的看门狗规则（wedge-watchdog.ts）是：会话有订阅、年龄超过 15 分钟、入站交互请求静默超过 45 分钟，且距上次轮换超过 1 小时，就只旋转这一个"卡死"的会话——其他健康会话不受影响。
💡 使用方法：在桥设置中打开Wedge Watchdog（默认关闭），下次设备卡住时观察日志里的
Wedge watchdog: rotating session行，即可确认它生效了。
机制四：mDNS 地址自动刷新，修复 IPv6 漂移
mDNS（多播 DNS）是 Matter 设备被发现的"门牌号"，也是局域网通信的基石。HAMH 在 mDNS 上做了三层加固：
1. 过滤不可达地址。matter.js 默认会把所有网络接口的 IPv6 地址都广播出去，其中"全局 IPv6"（GUA）地址在局域网内往往不可达，控制器一旦锁定它，设备就会集体显示 No Response。HAMH 提供mdns-strip-global-ipv6选项，通过 filtered-network.ts 只保留链路本地和 ULA 地址；mdns-network-interface则可以把广播绑定到指定网卡（Docker 用户尤其需要，避免广播到docker0这类内部接口）。配置入口在 mdns.ts。
2. 每分钟巡检地址变化。这是针对一个经典坑的修复：ISP 更换 IPv6 前缀后，机器接口的全局地址变了，但 matter.js 缓存的 mDNS 记录里还是旧地址，于是 Google Home 等设备"永远在线"却又连不上。HAMH 的 mdns-address-watch.ts 每 60 秒重新计算一次"当前应该广播的地址集合"，一旦发现变化（日志：Advertised address set changed … re-announcing operational mDNS），就对每个 Fabric 重新生成并广播 mDNS 记录——整个过程自动完成，无需重启。
3. 会话清理后主动补广播。matter.js 只在"对端取消订阅"时才重新广播；而服务器端因超时取消订阅时不会。HAMH 在关闭死会话、完成轮换之后都会调用restartAdvertisement()补一次广播，确保控制器知道该重连。
mDNS 相关的完整排障思路（路由器组播过滤、IGMP Snooping、接口绑定等）可参考官方文档 connectivity-issues.md。
机制五：多 Fabric 并存与会话维护
一个桥最多可以同时被 5 个控制器（每个控制器对应一条 Fabric）管理，这让"Apple Home 看状态、Alexa 发命令"成为可能。HAMH 对多 Fabric 场景的维护包括：
- 健康视图按 Fabric 拆分：桥详情页面的健康卡片会列出每条 Fabric 的会话数与订阅数（实现见 subscription-summary.ts），并能区分"整节点通配订阅"和"指定端点订阅"，一眼看出哪个控制器在"全量监听"；
- 新控制器接入流程：同一张桥的二维码只能用一次。接第二个控制器时，先用第一个控制器的"配对模式"生成本机配对码（manual pairing code），再到第二个控制器中输入该数字码。Apple Home + Alexa 的完整图文步骤见 connect-multiple-fabrics.md。
- Alexa 端口保护：Alexa 只有在端口 5540 上才能可靠完成配对。HAMH 在检测到 Amazon 厂商 ID 的 Fabric 添加到非 5540 端口的桥时，会在日志中发出明确警告，提示约 20 秒后该 Fabric 会因 failsafe 超时回滚（代码见 session-supervisor.ts 的
wireFabricWarnings）； - 优雅关闭：桥停止（更新配置、删除桥）时，HAMH 会先向所有会话发送关闭通知（最多等 2.5 秒），让控制器立刻丢弃旧 CASE 会话，避免重启后控制器拿着"僵尸会话"长时间显示设备无响应。
上图的设备总览页展示了桥下所有 Matter 端点（设备卡片上的绿色/红色图标即端点健康状态）。当某个控制器掉线时，这里能直观看到哪些设备受影响，配合 Health 页面按 Fabric 的会话统计，可以快速定位是"整个控制器掉线"还是"个别端点异常"。
小结：5 大机制如何协同工作
| 机制 | 触发条件 | 频率 | 用户可见日志 |
|---|---|---|---|
| 死会话清理 | 订阅全部丢失 | 60 s / 5 s（快速恢复） | Closing dead session |
| 被取代会话清理 | 同控制器重建会话 | 安静 5 min | Closing superseded session |
| 会话轮换 | 会话超过最大年龄（默认 4 h） | 每 5 min 检查 | Rotating session |
| 卡死看门狗 | IM 请求静默 >45 min（可选开启） | 每 5 min 检查 | Wedge watchdog: rotating session |
| mDNS 地址刷新 | 接口地址集合变化 | 每 60 s 巡检 | Advertised address set changed |
这些机制共同的目标只有一个：让控制器与桥之间的连接"断了自己能接上"，而不是等用户重启插件。作为普通用户，你平时只需要知道三件事——保持桥使用 5540 端口（Alexa 场景）、网络里别过滤组播流量、遇到设备集体失联先看 Health 页面的 Fabric 会话统计；作为进阶用户，可以再打开fastSessionRecovery和wedgeWatchdog两个特性，并把Session Rotation Max Age调到更小的值，让自愈更快。
更多细节可参考官方文档站点中的 bridge-configuration.md（桥配置项全集）与 api-reference.md（健康 API 返回的 Fabric 级会话信息）。
【免费下载链接】home-assistant-matter-hub
Publish your Home-Assistant Instance using Matter.
相关推荐
Home-Assistant-Matter-Hub 使用教程
Home Assistant Matter Hub 使用教程 1. 项目介绍 Home Assistant Matter Hub 是一个开源项目，旨在帮助用户将
Home Assistant Matter Hub 终极配置指南
Home Assistant Matter Hub 终极配置指南 Home Assistant Matter Hub 是一个强大的开源工具，它能够将您的 Hom
Home-Assistant-Matter-Hub 安装与配置完整指南
Home Assistant Matter Hub 安装与配置完整指南 项目介绍 Home Assistant Matter Hub 是一个开源项目，它能够帮助
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
