docs: add client-side troubleshooting (Force Relay, bufferbloat)

Document the 'Force relay connection' switch that silently disables
ICE gathering on iOS NetBird (and similar on macOS), which was the
real cause of all peers showing Connection type: Relayed despite
STUN being correctly configured.

Also document bufferbloat diagnosis via macOS networkQuality, which
was a red herring during the P2P investigation (large RTT spikes
were the WiFi/ISP, not NetBird).
This commit is contained in:
2026-04-18 10:40:04 +08:00
parent 31a874f3be
commit c5a8757da4
3 changed files with 152 additions and 1 deletions

View File

@@ -83,6 +83,8 @@ reopen fd 8: permission denied
| 手機 App`server closed the stream without sending trailers` | 透過 NPM 對外公開時NPM 用 `proxy_pass` 而非 `grpc_pass` 轉 gRPC加上 Caddy `:80` 預設不支援 h2c | NPM 加 `advanced_config`gRPC 路由)+ Caddy 全域啟用 `protocols h1 h2 h2c`;見 [npm-grpc-fix.md](./npm-grpc-fix.md) |
| `PUT /api/setup-keys/{id}` 回 200 但 `name` 沒改 | NetBird API 只更新 `auto_groups``revoked``name` 是 read-only | 改 `store.db``setup_keys.name` → 重啟 `netbird-server`;見 [setup-keys-and-pat.md](./setup-keys-and-pat.md) |
| peer 之間一直走 Relay`[stun:...:3478] is Checking...` | STUN port 3478 被 Headscale (`.126`) 搶先佔用 DNAT | NetBird 改用 3479/udpserver config + OpenWrt DNAT見 [stun-port-conflict.md](./stun-port-conflict.md) |
| STUN 都通了,仍然 `Connection type: Relayed``ICE candidate: -/-` | 客戶端 **Force Relay Connection** 開關被打開,跳過 ICE gathering | App Settings → Advanced → 關掉 Force Relay見 [client-troubleshooting.md](./client-troubleshooting.md) |
| ping RTT 尖峰到 2-4 秒 | 當下 WiFi/ISP 有 bufferbloat | 用 `networkQuality -v` 確認(看 RPM與 NetBird 無關 |
## 檔案位置
@@ -95,7 +97,8 @@ reopen fd 8: permission denied
├── netbird-selfhosted-setup.md ← 完整安裝指南
├── npm-grpc-fix.md ← 經 NPM 對外公開時的 gRPC 修復
├── setup-keys-and-pat.md ← Setup Keys / PAT 操作與 API 限制繞道
── stun-port-conflict.md ← STUN 改用 3479 (3478 被 Headscale 佔用)
── stun-port-conflict.md ← STUN 改用 3479 (3478 被 Headscale 佔用)
└── client-troubleshooting.md ← 客戶端 Force Relay / bufferbloat 排錯
```
### 遠端伺服器192.168.42.127:/opt/netbird/