vps/docs/matter-pairing-troubleshoot.md

# 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](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-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`，OUI `34:98:7a`） | 工作盏 `34:98:7a:25:a1:f0`；故障盏 `34:98:7a:27:7f:08`（hostname `matter`，动态 .145） |
| 故障盏已在 Aqara fabric `4DF2B1455D19402D`，宣告 `CM=0` 且缺 GUA | ⚠️ 找回需**恢复出厂**（清 fabric + 重拿 IPv6），再扫它自己的二维码 |
| DHCP 保留 `matter`（.45 → MAC `…10:bc`）与实际灯泡 MAC（`…7f:08`）不符 | ⚠️ 保留从未租出，待修（见 hosts/gw.md） |
| 遗留 SSID（element/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 载荷是加密的**：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` | 出现 = 已入网成功 |

## 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 错位（待修）