Files
vps/docs/matter-pairing-troubleshoot.md
T

216 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Matter 配网排障手册
> 基于 Matter 1.5.1 Core Spec §4.3.1 与本环境(EdgeRouter X + UniFi AP + Aqara M3 +
> Home Assistant2026-08-21 实测整理。配套 Linear W1N-207。
## 1. Matter 配网协议要点(发现即一切)
- **发现走 mDNSDNS-SD**UDP **5353**,组播 `224.0.0.251` / `ff02::fb`
**不经过单播 DNS(如 AdGuard .36)、不需要反向 DNS、不需要 DHCPv6**SLAAC 即满足 Matter
的 IPv6 要求)。
- 服务类型:
- `_matterc._udp` — 可配网设备(Commissionable),**配对模式才有效**
- `_matter._tcp` — 已配设备(Operational),TXT 里含 fabric 信息
- 子类型(配对方按此过滤):
- `_L<全12位 discriminator>`(如 `_L3266`)— 按二维码里的完整 discriminator 精确匹配
- `_S<高4位>`(如 `_S12`
- `_V<vendorId>``_T<deviceType>`(可选)
- `_CM`(仅真正处于配对模式时发布)
- TXT 关键键:`D=`discriminator,规范 **SHALL** 必填)、`VP=`vendor+product)、
**`CM=`**、`RI=`rotating id)、`PH=`/`PI=`(配对提示)。
- 配对端口:**TCP 5540**PASE/CASE)。部分生态(Aqara M3)为 Thread 中继节点用 **5552**
- 实例名:64 位随机 hex;**进入配对模式时更换**(可用作"是否重新进过配对"的信号)。
- 规范参考:[Matter 1.5.1 Core Spec §4.3.1](https://csa-iot.org/wp-content/uploads/2026/03/23-27349-010_Matter-1.5.1-Core-Specification.pdf)、
[Google Home: Commissionable and Operational Discovery](https://developers.home.google.com/matter/primer/commissionable-and-operational-discovery)、
[Matter Handbook: Discovery](https://handbook.buildwithmatter.com/how-it-works/discovery/)、
[connectedhomeip: IP commissioning](https://pigweed.googlesource.com/third_party/github/project-chip/connectedhomeip/+show/59edd2ff8506b1e3dabb7040d716f0e75a2312d1/docs/guides/ip_commissioning.md)。
## 2. 关键判据:CM=0 = 不在配对模式
规范 §4.3.1.2 / §4.3.1.7
- 设备可以长期宣告 `_matterc`**Extended Discovery**),但 **`CM=0` 表示"当前不接受配网"**。
- **已在 fabric 里的设备**(宣告里同时有 `_matter._tcp` + `_I<fabric>._sub` 运营记录)重配时
通常报 `CM=0` —— 它已配好,不是新设备。
- **配对方不能把已配设备当新设备加** → 重加/找回必须先**恢复出厂**(清 fabric,重启后以
`CM=1` 全新配对模式宣告),再用**它自己的二维码**添加。
- 常见误判:抓包看到 `_matterc` 宣告就以为"在配对模式"——**必须看 `CM=`**。
## 3. 本环境实测事实(2026-08-21W1N-207
| 事实 | 状态 |
|---|---|
| LAN55 IPv6/mDNS 链路 | ✅ 全正常(RA→交换机→AP→客户端;mDNS 双向通;igmp snooping off、mdns on、无客户端隔离、无组播增强、PMF off、WPA2、仅 2.4G |
| Matter 不依赖单播 DNS/.36、反向 DNS、DHCPv6 | ✅ 已排除(.36 健康且不在路径上) |
| HA matter-server 曾宣告两代前的旧 GUA | ✅ 已修复(重启 `core_matter_server`;宣告恢复当前前缀) |
| ISP PD /60 随重拨轮换 → Matter IPv6 缓存反复失效 | ⚠️ 环境性根因;对策 = 重拨后重启 matter-server + 重启 M3 |
| EdgeOS 上静态 ULA 不可行 | ✅ 已尝试并回滚(switch0 不支持静态 `ipv6 address`;显式 router-advert 会替换 PD-slaac RA |
| 在用的两盏 ESP32-C2 Matter 灯泡(VP `0x4891/0x4100`2026-08-23 复核) | 工作盏 MAC 已变为 `fc:e8:c0:25:a1:f0``.146`hostname `espressif`;原 `34:98:7a:25:a1:f0` 全网消失,疑固件更新后换 MAC——末 3 字节相同);新盏 `34:98:7a:27:10:bc``.148`hostname `matter`)。两盏各宣告 **3 个 fabric** 运营实例:Aqara `4DF2B1455D19402D``2F6E56020E1996E7`、HA `DCE86145C137AF0E`(见 §8 |
| 故障盏 `34:98:7a:27:7f:08`(曾 .145Aqara fabric`CM=0` 缺 GUA | 2026-08-23 复核:无租约、ARP incomplete、AP 无日志 = **已离网**(退役/退换) |
| **失败模式 C(2026-08-23 实测,两盏同时)**mDNS 活、5540 死 | 灯泡 ping 通(v4/v6)、DHCP 正常续租、mDNS 应答并宣告 `_matter._tcp`SRV :5540、TXT `T=1`、当前前缀 GUA),但 **TCP 5540 在 IPv4 与 IPv6fe80+GUA)均 RST 拒绝** → 配对方无法建立 CASEApp 显示离线;hass matter-server 侧无任何 established :5540 会话(详见 §8 |
| ISP PD 前缀再次轮换(2026-08-23 → `240e:3bd:238:4812::/64`08-22 为 `235:1fb2` | hass 与 `.148` 均持当前前缀 GUA;hass 残留 `.146` 旧前缀 GUA 的 **FAILED** 邻居项(旧地址缓存仍被某端尝试) |
| DHCP 保留 `matter`.45 → MAC `…10:bc` | ⚠️ 保留仍未生效:新灯泡(`…10:bc`)实际拿到动态 `.148` 而非保留的 `.45`(待修,见 hosts/gw.md |
| **新灯泡(2026-08-22 添加成功)**MAC `34:98:7a:27:10:bc`=DHCP 保留目标 MAC),hostname `matter`IP `.148`VP `4891/4100`D=`3377` | ✅ 已入 **Aqara fabric `4DF2B1455D19402D`****经 BLE 配网**Aqara Home App)——线上**无 TCP 5540** 属正常(BLE 会话对 AP/hass 抓包不可见) |
| ESP32-C2 灯泡 firmware 挂死模式(2026-08-22 实测) | 入网后宣告 `_matterc`CM=1、D=3377)约 **3 秒后网络栈完全静默**:STA 收发计数冻结、不掉线不重启、配对方(手机/M3 `_L3377` 查询)无应答 → 加不上。**对策=断电 10 秒重启**重新进配网模式(实例名更换:`3F4E2C66F2DA85CD``E5BA8E28E4DE23A0`),随即 App 添加即成功 |
| 遗留 SSIDelement/vwire/vport | ✅ 已清理 |
## 4. 抓包方法(BusyBox 兼容)
> 完整指令集(实时 / 落盘轮转 / 定向抓取 / Wireshark 解密)见
> [runbooks/matter-packet-capture.md](../runbooks/matter-packet-capture.md)。
> 下面是最常用的两条。
**视角必须在 LAN55**。**HA matter-server 作配对方时推荐直接在 hass `end0` 抓**——配对方
必然参与配对流程的每一条通讯(mDNS 本段组播 + 自己的 TCP 5540 全程),覆盖最全;AP `br0`
能看到全部 mDNS 组播 + 无线客户端单播,但**看不到有线↔有线单播**(如 Thread 设备经有线 M3
配对时 HA↔M3 的 5540 在 AP 侧不可见)。66 网段电脑看不到 55 的组播。BusyBox 注意点仅适用
AP**不要用 `--line-buffered`**;引号外层双引号、内层单引号);hass 是 HAOS 全量 tcpdump。
完整抓取(跑配对时保持窗口开着,`Ctrl+C` 结束):
```bash
ssh zhiqiangf@192.168.55.5 "tcpdump -ni br0 -s 0 -vvv -tt 'udp port 5353 or tcp port 5540 or tcp port 5552'"
```
hass 侧(HA matter-server 作配对方,推荐;非交互 ssh 需显式 `sudo -n -i`):
```bash
ssh hassio@hass.windy.lan "sudo -n -i tcpdump -ni end0 -s 0 -vvv -tt 'udp port 5353 or tcp port 5540 or tcp port 5552'"
```
精简过滤(只看 Matter 信号):
```bash
ssh zhiqiangf@192.168.55.5 "tcpdump -ni br0 -s 0 -vvv -tt 'udp port 5353 or tcp port 5540 or tcp port 5552' | grep -E '_matterc|_matter|_L[0-9]+|_S[0-9]+|_CM|_V[0-9]+|_T[0-9]+|\.5540|\.5552'"
```
存 pcap 供 Wireshark:把上面 `-w /tmp/matter.pcap` 追加到 tcpdump 参数(去掉 `-vvv`),
`scp zhiqiangf@192.168.55.5:/tmp/matter.pcap .` 拉回本地分析。
> **落盘务必轮转**AP `/tmp` 只有约 60MB。用
> `-C 5 -W 12 -w /tmp/matter.pcap`(每 5MB 轮转、最多 12 个文件)防止写满,
> 详见 runbook Step 3(落盘轮转)。
> **Matter 载荷是加密的**mDNS5353)明文可读;5540 上的 Matter 报文要看明文
> 需要 Wireshark matter-dissector + 会话密钥,详见 runbook Step 5(解密)。
### 阶段对照表
| 阶段 | 应该看到 | 对应问题 |
|---|---|---|
| 发现(设备侧) | `_matterc._udp` + `_L3266._sub` + `_S12._sub` + TXT `D=3266 CM=1` + SRV `:5540` + AAAA | **无宣告**=设备没入网/没进配对模式;**`CM=0`**=不在配对模式(已配设备);**无 `_L3266`**=固件子类型缺失 |
| 发现(配对方侧) | M3/手机查询 `_L3266._sub._matterc._udp` | 查询有、无应答 = 码/discriminator 不匹配或设备不在线 |
| 配对握手 | 到设备 IP **TCP 5540 SYN/SYN-ACK** 双向 | **SYN 无 ACK**=设备不可达/防火墙;**完全无 5540**=发现阶段没完成 |
| 配完后 | 设备宣告 `_matter._tcp` + `_I<fabric>._sub` | 出现 = 已入网成功 |
| BLE 配网(手机 App 直连设备 BLE,如 Aqara Home | 线上**无 TCP 5540**BLE 会话对 AP/hass 抓包不可见);设备入网后仍先 mDNS 宣告 `_matterc` | 成功判据=最终宣告 `_matter._tcp` + `_I<fabric>._sub`;无 5540 **不代表**失败 |
## 5. 排障决策树(按顺序)
1. 抓包看**有没有 `_matterc` 宣告**:没有 → 设备不通电 / 没连上 Wi-Fi / 没进配对模式
(先解决"设备在线",网络侧已反复验证正常)。
2. 有宣告但 **`CM=0`** → 设备已配 / 不在配对模式 → **恢复出厂**后重试(用它自己的二维码)。
3. 有宣告 `CM=1` 但**无 `_L<disc>` 子类型** → 固件 mDNS 缺陷 → 升固件或换通用发现配对方。
4. `CM=1` + 子类型齐全但**无 TCP 5540** → 配对方没匹配上(查码/discriminator)或设备不可达。
5. 有 5540 但配对中断 → 查 `CM` 源(码是否正确)、设备电源、fabric 状态(是否需先清)。
## 6. 相关文档
- [runbooks/matter-packet-capture.md](../runbooks/matter-packet-capture.md) — Matter 抓包指令集(实时/落盘轮转/定向/解密)
- [docs/lan-overview.md](lan-overview.md) — LAN 拓扑、SSID 清理、ULA 不可行
- [hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md) — matter-server 重拨运维规范
- [docs/unifi-network.md](unifi-network.md) — UniFi 网络/IPv6/SSID 记录
- [hosts/gw.md](../hosts/gw.md) — DHCP 保留 `matter` MAC 错位(待修)
## 7. 2026-08-22 实测记录:添加新 ESP32-C2 Matter 灯泡(成功 + 失败路径全记录)
> 场景:手机 AppAqara Home)添加一盏**新的** ESP32-C2 Matter 灯泡
> `34:98:7a:27:10:bc`hostname `matter`,最终 IP `.148`)。中途换了灯泡并断电重启,
> 共经历 **2 种失败模式** 和 **1 条成功路径**,全部抓包实证。
>
> 抓包点:UAP-AC-Lite `192.168.55.5` `br0`(轮转 `udp 5353 or tcp 5540 or tcp 5552`
> + 定向全量 `ether host 34:98:7a:27:10:bc`+ hostapd/stahtd 日志 + gw DHCP/ARP 交叉验证。
> 本地用 tshark 4.7.2 分析。
### 时间线(CST2026-08-22
| 时间 | 事件 | 判据 / 说明 |
|---|---|---|
| 10:50:28 | 启动轮转抓包 | — |
| 10:51:1219 | 手机 `.143`OnePlus,连 wifi0ap0=`ubnt-windy-2`)重新关联;查询 `_matter._tcp` | 运营查询(浏览已配设备),**不是**配网(配网应查 `_matterc._udp` |
| ~10:56 | 用户报「配置 wifi 后挂起,不能加入 wifi」 | 首次失败 |
| 11:00:15 | M3 `.248` 查询 `_L3266._sub._matterc` | 无应答(是另一台设备的 discriminator,无关) |
| 11:01:2442 | **失败模式 A**:故障盏 `…7f:08` 尝试关联 `wifi0ap1`(`ubnt-haas`):发 1 次 open-auth 帧(algorithm 0)→ AP 回 `status_code=0`**客户端不再发 assoc 请求** → 18s 后 `auth_failures=1` + disassociated | auth 阶段卡死(client 侧);非密码错——密码错会先 assoc 再 4-way 失败 |
| 11:04:0105 | **新灯泡 `…10:bc` 关联 `wifi0ap1` 成功**WPA2 4-way 完成,DHCP 拿 `.148`tracker `soft failure`: ip_delta 3.76savg_rssi -68);随即宣告 `_matterc`:实例 `3F4E2C66F2DA85CD`TXT `VP=4891+4100 D=3377 CM=1`SRV :5540**有 GUA** | 发现阶段判据全过 |
| 11:04:05 之后 | **失败模式 B**:灯泡网络栈完全静默——STA 收发计数冻结(rx=89/tx=5 持续 12s+ 不变)、**不掉线不重启** | firmware 挂死 |
| 11:04:5911:07:27 | 手机查 `_matterc` ×4、`.60` 解析实例、M3 查 `_L3377._sub._matterc` ×5discriminator 3377 正是新盏)——**全部无应答**TCP 5540/5552 全程 0 | 配对方找不到设备 → App 报「加不上」 |
| 11:09:3548 | **断电 10 秒重启**:灯泡重新关联 `wifi0ap1` ×2 | 对策生效 |
| 11:10:26 | DHCP 重新拿 `.148`;STA 计数恢复持续增长(活跃) | — |
| 11:1011:15 | 重新宣告 `_matterc`**新实例 `E5BA8E28E4DE23A0`**——入配对模式实例名更换,符合规范);App 走 **BLE 配网** | 线上无 TCP 5540BLE 对 AP 不可见,属正常) |
| 11:15:23 | 灯泡宣告 **`_matter._tcp`**`4DF2B1455D19402D-02EF2FF12DFAF10E`Aqara fabric+ SRV :5540 + GUA + A | ✅ **添加成功**(已入 Aqara fabric `4DF2B1455D19402D` |
### 结论与经验
1. **同族灯泡(VP 4891/4100OUI 34:98:7a)存在两种不同失败模式**
- 故障盏 `…7f:08`:auth 阶段卡死(auth 帧后不发 assoc);此前(08-21 21:27)成功关联后伴随
`ip_failures=1`(拿不到 IP)+ 缺 GUA —— 属更深层故障,需恢复出厂,本次未处理,仍离线。
- 新盏 `…10:bc`:入网 + 宣告 `_matterc`(CM=1)成功后约 3 秒固件挂死(全静默)。
**断电 10 秒重启即恢复**,是最简单有效的对策。
2. **AP 抓包看不到 BLE 配网**Aqara Home App 对 WiFi Matter 设备走 BLE 配网时,线上只有
mDNS/DHCP**无 TCP 5540 不代表失败**;成功判据 = 设备最终宣告 `_matter._tcp` + `_I<fabric>._sub`
3. **发现判据回顾**`_matterc` + TXT`CM=1``D=``VP=`+ SRV :5540 + AAAA(GUA) + A 全齐才算
设备真的在配对模式;配对方按 `_L<disc>._sub._matterc` 精确匹配 discriminator(本例 D=3377)。
4. 新盏 RSSI -68、DHCP 3.76s,射频偏弱,可能加剧 firmware 不稳定(待观察)。
5. DHCP 保留 `matter`.45→`…10:bc`**仍未生效**:新盏实际拿动态 `.148`(待修,见 hosts/gw.md)。
6. 识别「配对方在找但设备不答」的快速方法:抓包里配对方持续查 `_matterc`/`_L<disc>` 而目标 MAC
零应答 + STA 收发计数冻结 = 设备侧挂死;此时**先断电重启设备**,不要怀疑网络/AP。
### 后续:新盏 11:24 起离线循环(同一盏 `…10:bc`2026-08-22
配网成功后约 10 分钟(11:15–11:24 可控制),灯泡进入**持续性故障循环**:
| 时间 | 事件 | 模式 |
|---|---|---|
| 11:24:57 | `EVENT_STA_LEAVE`(真掉线) | 掉线 |
| 11:25:12 | 重连 `auth_failures=2` | **auth 卡死**(同故障盏 `…7f:08` 11:01 的模式) |
| 11:25:2325 | 重连成功,WPA2 完成,重新拿 `.148` | — |
| 11:25:38 | `soft failure`ip_delta 2.65s**avg_rssi -73**-68→-73 持续变差) | 射频偏弱 |
| 11:25 之后 | STA 计数冻结(rx=119/tx=64 不动);M3 持续查询其运营实例 `4DF2B1455D19402D-02EF2FF12DFAF10E._matter._tcp` **无应答** → App 显示「离线」 | 静默挂死 |
**结论**:三盏 ESP32-C2 灯泡中两盏(`…7f:08``…10:bc`)故障,表现覆盖 auth 卡死 / 静默挂死 /
随机掉线三种形态;工作盏 `…25:a1:f0` 正常。网络侧(AP、M3、DHCP、mDNS)均验证正常。
**疑似根因(按可能性)**:① ESP32-C2 Matter 灯泡 firmware 缺陷(同批次)② 射频偏弱
(RSSI -73,天线/距离/遮挡)加剧不稳定 ③ 供电不稳(brownout 造成 Wi-Fi 栈崩溃重启)。
**待办**:移近 AP 或改善供电后观察;App 内查固件更新;仍复发则考虑退换。
## 8. 2026-08-23 状态核查:两盏「半在线」——mDNS 宣告正常但 TCP 5540 无监听(失败模式 C)
> 全程**只读**核查(gw DHCP/ARP、AP hostapd 日志、hass matter-server 状态 + mDNS 抓包、
> 对灯泡 v4/v6 的 TCP 5540 探测,09:0x CST)。结论:**网络侧全部健康;两盏灯泡网络栈活着、
> mDNS 运营宣告正常,但 Matter 会话端点(TCP 5540)无监听**——配对方无法建立 CASE,
> App 内应显示离线/不可达。
| 对象 | 状态(2026-08-23 |
|---|---|
| 新盏 `34:98:7a:27:10:bc``.148`hostname `matter` | DHCP 04:40 续租;gw ARP 完整;ping 通(93122msESP32 省电时延);08-22 16:40 起稳定关联 `wifi0ap1`,关联时 `avg_rssi -70`。mDNS 宣告 3 实例:`4DF2B1455D19402D-02EF079EEB480D07`**新 node ID——08-22 之后被重新配网过**)、`2F6E56020E1996E7-137147AF27BE4EB6``DCE86145C137AF0E-0000000000000011`HA fabric);host 记录 A `.148` + fe80 + **当前前缀** GUA `240e:3bd:238:4812:*`。支持单播 legacy mDNS 查询(`dig -p 5353 @.148 _matter._tcp.local PTR` 可用) |
| 工作盏(MAC 已变)`fc:e8:c0:25:a1:f0``.146`hostname `espressif` | DHCP 07:17 续租;ping 通 v4/v6v6 fe80 3861ms)。mDNS 宣告 3 实例:`4DF2B1455D19402D-02EF4CA3F856B615``2F6E56020E1996E7-EE8F2E4F1A77BF05``DCE86145C137AF0E-000000000000000B`。原 MAC `34:98:7a:25:a1:f0` 全网消失(无租约/ARP/AP 日志)而新 MAC 末 3 字节相同 → 疑固件更新后改 MAC。**拒绝单播 5353**ICMP port unreachable),只应答组播查询——同族固件行为差异。hass 残留其旧前缀 GUA `240e:3bd:235:1fb2:fee8:c0ff:fe25:a1f0`**FAILED** 邻居项 |
| 故障盏 `34:98:7a:27:7f:08`(曾 `.145` | 无租约、ARP incomplete、AP 日志零事件 = 已离网 |
| **TCP 5540 探测(两盏)** | IPv4LAN66 与 hass 本段)、IPv6fe80%end0 + 当前 GUA)全部 **RSTConnection refused** —— SRV 宣告 :5540 且 TXT `T=1`,但实际无监听 |
| hass matter-server | `started`,v9.0.4,无更新;宣告自身运营实例 `DCE86145C137AF0E-…1B669`v4+v6,当前 GUA);**无任何 established :5540 会话**core/add-on 日志无 matter 错误 |
| 其他 Matter 控制器 | Aqara M3 `.248` 在线(有线 0.8ms),宣告含自身 fabric 节点 `4DF2B1455D19402D-11E158E46D24A000`SmartThings `.48` 在线并周期查询 `_matter._tcp.local`;手机(当前前缀 GUA)也在浏览。LAN55 共见 **5 个 fabric**`4DF2B1455D19402D`M3)、`DCE86145C137AF0E`HA)、`2F6E56020E1996E7``03BCFAEDD6153944``6A6FF80C2DB84DEE` |
**判定**:失败模式 C = TCP/IP 栈与 mDNS 守护进程活着(主动 RST、DHCP 续租、ping 通),
但 Matter 应用层监听不存在。与模式 A(auth 卡死)、模式 B(全静默挂死)同族不同形态;
**两盏同时处于同一状态**更指向共同诱因(固件缺陷,或 PD 轮换等共同事件后未恢复)。
**对策(推荐,未执行)**:逐盏断电 10 秒重启(模式 B 的已验证对策),重启后复测
TCP 5540 恢复监听即可确认。
**核查方法备忘**(只读,可复用):
- gw`show dhcp leases` / `show arp`(经 `/opt/vyatta/bin/vyatta-op-cmd-wrapper`)。
- AP`grep -i <mac> /var/log/messages`hostapd 关联事件 + stahtd RSSI/soft failure)。
- hass`sudo -n -i ha apps info core_matter_server``ip -6 neigh show dev end0`
(看灯泡 fe80/旧新前缀 GUA 与 FAILED 项);被动抓包
`sudo -n -i timeout 65 tcpdump -ni end0 -s 0 -tt 'udp port 5353'`——配对方周期查询
会自然引出灯泡宣告,无需主动发包。
- 5540 探测:hass 上 python3 对 v4 / fe80%end0 / GUA 各 connect 一次;RST=无监听,
超时=不可达(两者含义不同)。