feat: 添加可选心跳机制支持，前端定时发送 ping 消息，后端可回应 pong

Author: ShiJiashuai

README.md

@@ -127,7 +127,7 @@ WebRTC/
 
 ## 路线图
 
-- [ ] 房间成员列表与自动呼叫提示
+- [x] 房间成员列表与自动呼叫提示
 - [ ] TURN 支持（coturn）
 - [ ] 多人通话（Mesh / 引入 SFU 框架）
 - [ ] 录制与旁路推流（RTMP/RTC）

ROADMAP.md

@@ -54,9 +54,9 @@
   - [x] 在 `HandleWS` 的循环中，只要出现读/写错误，就调用 `removeClient`，确保房间中不会残留“僵尸连接”。
   - [x] 在 `removeClient` 中确认：当房间成员为空时删除该房间。
 
-- [ ] **（可选）简单心跳机制**  
+- [x] **（可选）简单心跳机制**  
   - 前端每隔 N 秒发送一个 `type: "ping"` 的消息。
-  - 后端可以选择忽略或原样返回，主要用于学习“保活”概念，不做复杂超时逻辑。
+  - 后端可以选择忽略或返回一个 `type: "pong"`，主要用于学习“保活”概念，不做复杂超时逻辑。
 
 ### 3.2 前端（web/app.js + web/index.html）
 

changelog/2025-12-18.md

@@ -12,8 +12,12 @@
 - 后端：入口统一解析 `WS_ALLOWED_ORIGINS` 并注入 Hub；服务启动改用 `ServeMux` + `http.Server`，避免使用默认全局路由。
 - 后端：`writePump` 写失败时主动关闭连接，触发读循环退出并完成资源清理。
 - 后端：升级失败日志补充 `path`；连接结束时关闭 `send` 通道以退出写协程；`removeClient` 调整为不关闭通道，避免 `leave` 后同连接再次 `join` 引发 panic。
+- 后端：支持可选心跳消息 `ping`，并以 `pong` 非阻塞回应，用于学习“保活”概念。
 
 - 文档：同步更新 `docs/signaling.md` 中的 Hub 结构与 `writePump` 示例代码。
 - 文档：更新 `README.md` 配置章节（补充 `ADDR`、`WS_ALLOWED_ORIGINS="*"` 用法），并同步更新 `ROADMAP.md` 阶段 1 后端任务勾选状态。
 
 - 文档：同步补充 `docs/guide.md` 中 Hub 的 Origin 校验配置说明（`allowedOrigins`/`allowAllOrigins`），强调由入口解析 `WS_ALLOWED_ORIGINS` 并通过 `signal.Options` 注入。
+- 前端：WebSocket 信令连接增加简单心跳（定时发送 `ping`，在关闭/离开时清理定时器）。
+- 前端：收到 `room_members` 且 `Remote ID` 为空时，自动填入第一个非自己的成员作为“可呼叫对象提示”。
+- 文档：补充 `ping/pong` 消息类型与处理说明，并在 `ROADMAP.md` 中标记心跳机制已完成。

docs/guide.md

@@ -97,6 +97,10 @@ type Message struct {
 - `candidate`：ICE 候选，帮助打洞。
 - `room_members`：服务器广播的“当前房间成员列表”。
 
+可选的辅助消息：
+
+- `ping` / `pong`：简单心跳（前端定时发送 `ping`，服务端可选回 `pong`），用于学习“保活”概念。
+
 ### 2.2 Hub 与 Client
 
 文件：`internal/signal/hub.go`

docs/signaling.md

@@ -60,7 +60,9 @@ type Message struct {
   - `"leave"`：离开房间请求（当前 Demo 中暂时很少手动用到）；
   - `"offer"` / `"answer"`：SDP 交换；
   - `"candidate"`：ICE 候选；
-  - `"room_members"`：服务端广播的当前房间成员列表（从服务端发给前端）。
+  - `"room_members"`：服务端广播的当前房间成员列表（从服务端发给前端）；
+  - `"ping"`：可选心跳消息（从前端发给服务端，用于保活/学习）；
+  - `"pong"`：服务端对 `"ping"` 的可选回应（从服务端发给前端）。
 - `Room`：房间名，字符串。
 - `From`：发送方 ID（前端生成的 `myId`）。
 - `To`：接收方 ID，仅点对点消息（`offer/answer/candidate`）需要。
@@ -110,7 +112,7 @@ type Client struct {
   - `rooms["room1"]["userB"] = *Client`
 - 处理下列操作：
   - WebSocket 连接升级与关闭；
-  - 收到 `join/leave/offer/answer/candidate` 消息并处理；
+  - 收到 `join/leave/ping/offer/answer/candidate` 消息并处理；
   - 对 `offer/answer/candidate` 按 `Room + To` 进行转发；
   - 在房间成员变化时，广播 `room_members` 消息。
 
@@ -175,6 +177,11 @@ func (h *Hub) HandleWS(w http.ResponseWriter, r *http.Request) {
             h.addClient(client)
         case "leave":
             h.removeClient(client)
+        case "ping":
+            select {
+            case client.send <- Message{Type: "pong"}:
+            default:
+            }
         case "offer", "answer", "candidate":
             h.forward(msg)
         default:
@@ -202,6 +209,7 @@ func (h *Hub) HandleWS(w http.ResponseWriter, r *http.Request) {
 - 根据 `msg.Type`：
   - `join`：设置 `client.id`/`client.room`，并调用 `addClient`；
   - `leave`：调用 `removeClient`；
+  - `ping`：可选心跳消息，服务端可回写 `pong`（非阻塞发送）；
   - `offer/answer/candidate`：调用 `forward(msg)`，根据房间和 `To` 转发；
   - 其他：打印未知类型日志。
 
@@ -268,30 +276,33 @@ func (h *Hub) removeClient(c *Client) {
     if c.room == "" || c.id == "" {
         return
     }
-    if m, ok := h.rooms[c.room]; ok {
-        if existing, ok2 := m[c.id]; ok2 {
-            delete(m, c.id)
-            close(existing.send)
+    room := c.room
+    if m, ok := h.rooms[room]; ok {
+        if _, ok2 := m[c.id]; !ok2 {
+            c.room = ""
+            return
         }
+        delete(m, c.id)
+        c.room = ""
         if len(m) == 0 {
-            delete(h.rooms, c.room)
-            log.Printf("signal: room %s closed", c.room)
-        } else {
-            members := make([]string, 0, len(m))
-            for id := range m {
-                members = append(members, id)
-            }
-            msg := Message{
-                Type:    "room_members",
-                Room:    c.room,
-                Members: members,
-            }
-            for _, cli := range m {
-                if cli != nil && cli.conn != nil {
-                    select {
-                    case cli.send <- msg:
-                    default:
-                    }
+            delete(h.rooms, room)
+            log.Printf("signal: room %s closed", room)
+            return
+        }
+        members := make([]string, 0, len(m))
+        for id := range m {
+            members = append(members, id)
+        }
+        msg := Message{
+            Type:    "room_members",
+            Room:    room,
+            Members: members,
+        }
+        for _, cli := range m {
+            if cli != nil && cli.conn != nil {
+                select {
+                case cli.send <- msg:
+                default:
                 }
             }
         }
@@ -302,10 +313,11 @@ func (h *Hub) removeClient(c *Client) {
 关键点：
 
 - 同样通过互斥锁保护 `rooms`；
-- 找到 `rooms[c.room]` 后：
-  - 删除对应 `id`，并关闭其 `send` 通道；
+- 找到 `rooms[room]` 后：
+  - 删除对应 `id`（这里不关闭 `send` 通道，`send` 在 `HandleWS` 的 `defer` 中统一关闭，以结束 `writePump`）；
   - 若该房间已空，删除房间并打印“room closed”；
   - 若仍有其他成员：重新构建成员列表，广播 `room_members` 给房间内剩余成员。
+- 离开后将 `c.room` 置空，避免同一连接在 `leave` 后被 `defer` 再次 `removeClient` 时重复处理。
 
 > 注意：
 > - 这里使用 `select { case cli.send <- msg: default: }` 非阻塞发送，避免因为某个客户端处理过慢而卡住整个 Hub。

internal/signal/hub.go

@@ -107,6 +107,11 @@ func (h *Hub) HandleWS(w http.ResponseWriter, r *http.Request) {
 			h.addClient(client)
 		case "leave":
 			h.removeClient(client)
+		case "ping":
+			select {
+			case client.send <- Message{Type: "pong"}:
+			default:
+			}
 		case "offer", "answer", "candidate":
 			h.forward(msg)
 		default:

web/app.js

@@ -5,6 +5,7 @@ idEl.textContent = myId
 
 let ws
 let manualClose = false
+let pingTimer = null
 let pc
 let localStream
 let roomId
@@ -143,6 +144,22 @@ if (chatInput) {
 }
 
 const servers = { iceServers: [{ urls: ['stun:stun.l.google.com:19302'] }] }
+const pingIntervalMs = 25000
+
+function startPing() {
+  stopPing()
+  pingTimer = setInterval(() => {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'ping', room: roomId, from: myId }))
+    }
+  }, pingIntervalMs)
+}
+
+function stopPing() {
+  if (!pingTimer) return
+  clearInterval(pingTimer)
+  pingTimer = null
+}
 
 async function getMedia() {
   if (!localStream) {
@@ -233,6 +250,7 @@ function connectWS() {
     setError('')
     ws.send(JSON.stringify({ type: 'join', room: roomId, from: myId }))
     setState('joined')
+    startPing()
   }
   ws.onmessage = async (ev) => {
     const msg = JSON.parse(ev.data)
@@ -255,13 +273,18 @@ function connectWS() {
     } else if (msg.type === 'room_members') {
       const list = msg.members || []
       renderMembers(list)
+      if (state === 'joined' && remoteInput && !remoteInput.value.trim()) {
+        const peer = list.find(id => id && id !== myId)
+        if (peer) remoteInput.value = peer
+      }
     }
   }
   ws.onerror = (e) => {
     console.error('ws error', e)
     setError('信令服务器连接出错')
   }
   ws.onclose = () => {
+    stopPing()
     ws = null
     closePeerConnection()
     roomId = null
@@ -339,6 +362,7 @@ function leaveRoom() {
   renderMembers([])
   if (remoteInput) remoteInput.value = ''
   setError('')
+  stopPing()
   if (ws) {
     try {
       manualClose = true