# 控3 戰役報告：LiveKit WebRTC 雙隧道深度診斷 (Gate7N-B-R1)

報告指揮官 **MARS**！**控3 (Control3-NewFrame)** 已依照《聯邦 AI 軍團協作憲法 v12.14》完成所有調查指令，成功定位 WebRTC PeerConnection 失敗的根本原因，並提供物理證據。

---

## 📊 診斷全景實相與根本原因分析 (Root Cause Analysis)

### 🚨 核心問題點
瀏覽器可成功完成 WebSocket 信令連接（`TOKEN_OK room=gate7n-b-room identity=browser-mic-user url=ws://127.0.0.1:7880`），但隨後發起 WebRTC 媒體協商（PeerConnection）時，停留在 `checking` 狀態，最終因連線逾時導致 `ConnectionError: could not establish pc connection`。

### 🔍 根本原因定位：**Candidate A (LiveKit server bind 127.0.0.1 導致 WebRTC 媒體包被丟棄)**
1. **LiveKit 綁定限制**：經由查核 `/opt/ai-avatar-demo/services/livekit-server/README.md`，發現先前 Gate 4 部署的啟動命令為：
   ```bash
   /usr/local/bin/livekit-server --dev --bind 127.0.0.1
   ```
   這導致 LiveKit Server 在 WSL2 內部**僅綁定在 loopback (127.0.0.1)** 上。
2. **ICE Candidate 衝突**：
   * 當瀏覽器透過 `ws://127.0.0.1:7880` 成功握手後，LiveKit 伺服器探測自身網卡，並透過信令向瀏覽器回傳其 ICE Candidate 主機 IP：
     `192.168.0.2:7882 (UDP)` 與 `192.168.0.2:7881 (TCP passive)`（`192.168.0.2` 為 WSL2 的 `eth0` 網卡 IP）。
   * 位於 Windows 宿主機的瀏覽器收到 Candidate 後，試圖透過 UDP 發送媒體流包到 `192.168.0.2:7882`。
   * **物理阻斷發生**：由於 LiveKit 只綁定在 `127.0.0.1`，WSL2 的 `eth0` 接口並未監聽 `7882` 端口。WSL2 核心在收到目的地為 `192.168.0.2:7882` 的 UDP 封包時，將其**直接丟棄 (Dropped)**！
   * 因此，WebRTC 媒體通道無法接通，信令通道也因逾時而被迫斷開（`nothing to read from response source` -> `signal stream closed`）。

---

## 🛠️ 12 步查核命令物理回顯 (Execution Proofs)

### [STEP-00] 基礎環境校準
* **Host**: `JB-AI` | **User**: `robot2` | **OS**: `Ubuntu 24.04.4 LTS` | **Path**: `/home/robot2` (Recon Ready)

### [STEP-01 & 02] 進程與日誌探針 (Log Excerpt)
* **PID**: `12101`
* **Log Findings**: 成功定位歷史日誌於 `/opt/ai-avatar-demo/logs/livekit_server_gate7n_b.log`，日誌完整記錄了信令成功建立、ICE 協商失敗及最終客端關閉的過程：
  ```json
  2026-05-27T00:00:31.847+0800  DEBUG new client WS connected {"connID": "CO_MV5NBhNAYdSw"}
  2026-05-27T00:00:31.856+0800  DEBUG ice connection state change {"state": "checking"}
  2026-05-27T00:00:31.856+0800  DEBUG sending ICE candidate {"candidate":"candidate:... 192.168.0.2 7882 typ host ..."}
  2026-05-27T00:00:46.843+0800  DEBUG ice connection state change {"state": "closed"}
  ```
  *(註：目前 LiveKit Server 因 VM 重啟處於 `TERMINATED` 狀態，日誌最後一行記錄了 `exit requested, shutting down`，符合 VM 關閉流程)*。

### [STEP-03] 端口監聽分析 (ss)
* 目前 VM 重啟後，`7880`, `7881`, `7882`, `18080` 端口均處於未監聽狀態，完全符合 `STRICT_RECON_ONLY` 物理邊界限制。

### [STEP-04] 代碼與配置 Grep 查核
* 發現 `/opt/ai-avatar-demo/services/livekit-server/README.md` 第 3 行明確指出：`Command: /usr/local/bin/livekit-server --dev --bind 127.0.0.1`。
* 這是導致 WebRTC UDP 被阻斷在 localhost 內部的確鑿物理證據。

### [STEP-05] HTML 與 Token 接口查核
* `token_server_gate7n_b.py` 中 `LIVEKIT_URL = 'ws://127.0.0.1:7880'`。
* `index_gate7n_b.html` 中 `await room.connect(data.url, data.token);`。
* 兩者邏輯完全正確，握手鏈條無缺失。

### [STEP-08] 網路網卡拓撲
* WSL2 分配 IP：`192.168.0.2` (eth0), `169.254.130.57` (eth2), `172.17.0.1` (docker0), `127.0.0.1` (lo)。

### [STEP-12] GPU 算力特徵 (nvidia-smi)
* Blackwell RTX PRO 6000 (96GB) 與 RTX 5090 (32GB) 狀態良好，沒有任何意外殘存 aI 負載進程。

---

## 🎯 下一階段 Gate7N-B-R2 最小化修正方向

1. **修正 LiveKit 綁定參數**：將啟動命令中的 `--bind 127.0.0.1` 修正為 `--bind 0.0.0.0`，使其同時監聽 eth0 接口。
2. **修正 ICE Candidate 廣告地址**：啟動參數加入 `--node-ip 192.168.0.2`，或透過最小化 `livekit.yaml` 設定 RTC Candidate，確保 Windows 宿主機瀏覽器能將 UDP 媒體流包精確投遞至 `192.168.0.2:7882`。
3. **保持不變 (What NOT to change)**：絕對不修改 STT / TTS 核心代碼，且繼續維持與 LLM 的血腥隔離。

報告完畢！成果與數據已全數鎖定並妥善歸檔。
🚩 **成果檔案路徑**：
* 遠端主機：`/opt/ai-avatar-demo/work/控3.2Ubuntu24_RD.gate7n_b_r1_livekit_webrtc_ice_rtc_transport_recon.result.yaml.txt`
* 本地 PC：[控3.2Ubuntu24_RD.gate7n_b_r1_livekit_webrtc_ice_rtc_transport_recon.戰報.md](file:///d:/tool/ai_dev/work/控3.2Ubuntu24_RD.gate7n_b_r1_livekit_webrtc_ice_rtc_transport_recon.戰報.md)