# 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`；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](../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` | 出现 = 已入网成功 |
| 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 灯泡（成功 + 失败路径全记录）

> 场景：手机 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=无监听，
  超时=不可达（两者含义不同）。