windy/vps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
vps/docs/matter-pairing-troubleshoot.md
T

19 KiB
Raw Permalink Blame History

Matter 配网排障手册

基于 Matter 1.5.1 Core Spec §4.3.1 与本环境（EdgeRouter X + UniFi AP + Aqara M3 + Home Assistant）2026-08-21 实测整理。配套 Linear W1N-207。

1. Matter 配网协议要点（发现即一切）

  • 发现走 mDNS（DNS-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、 Google Home: Commissionable and Operational Discovery、 Matter Handbook: Discovery、 connectedhomeip: IP commissioning。

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-21，W1N-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（曾 .145，Aqara 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 与 IPv6（fe80+GUA）均 RST 拒绝 → 配对方无法建立 CASE，App 显示离线；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 添加即成功
遗留 SSID（element/vwire/vport） ✅ 已清理

4. 抓包方法（BusyBox 兼容）

完整指令集（实时 / 落盘轮转 / 定向抓取 / Wireshark 解密）见 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 结束）：

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）：

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 信号）：

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 载荷是加密的：mDNS（5353）明文可读；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. 相关文档

7. 2026-08-22 实测记录：添加新 ESP32-C2 Matter 灯泡（成功 + 失败路径全记录）

场景：手机 App（Aqara 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 分析。

时间线（CST，2026-08-22）

时间 事件 判据 / 说明
10:50:28 启动轮转抓包 —
10:51:12–19 手机 .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:24–42 失败模式 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:01–05 新灯泡 …10:bc 关联 wifi0ap1 成功，WPA2 4-way 完成，DHCP 拿 .148（tracker soft failure: ip_delta 3.76s，avg_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:59–11:07:27 手机查 _matterc ×4、.60 解析实例、M3 查 _L3377._sub._matterc ×5（discriminator 3377 正是新盏）——全部无应答；TCP 5540/5552 全程 0 配对方找不到设备 → App 报「加不上」
11:09:35–48 断电 10 秒重启：灯泡重新关联 wifi0ap1 ×2 对策生效
11:10:26 DHCP 重新拿 .148；STA 计数恢复持续增长（活跃） —
11:10–11:15 重新宣告 _matterc（新实例 E5BA8E28E4DE23A0——入配对模式实例名更换，符合规范）；App 走 BLE 配网 线上无 TCP 5540（BLE 对 AP 不可见，属正常）
11:15:23 灯泡宣告 _matter._tcp：4DF2B1455D19402D-02EF2FF12DFAF10E（Aqara fabric）+ SRV :5540 + GUA + A ✅ 添加成功（已入 Aqara fabric 4DF2B1455D19402D）

结论与经验

  1. 同族灯泡（VP 4891/4100，OUI 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:23–25 重连成功，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 通（93–122ms，ESP32 省电时延）；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/v6（v6 fe80 38–61ms）。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 探测（两盏） IPv4（LAN66 与 hass 本段）、IPv6（fe80%end0 + 当前 GUA）全部 RST（Connection 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=无监听， 超时=不可达（两者含义不同）。
Reference in New Issue View Git Blame Copy Permalink