fix(sync): 全部 goroutine 启动点加 panic 防护（GoSafe/goSafe），防单协程异常击穿进程

Author: Aparencia

server/sync-service/handlers/panicguard.go

@@ -0,0 +1,20 @@
+// @ai-context
+// handlers 包内 goroutine panic 统一防护。
+// Why: Go 中任一 goroutine panic 且未 recover 会崩溃整个进程；WebSocket 长连接
+// 场景下单连接异常不应拖垮服务。本文件与 middleware/panicguard.go 分工：
+// middleware.GoSafe 供 main 包使用，本 goSafe 供 handlers 包内部使用（避免
+// handlers → middleware 反向依赖）。
+package handlers
+
+import "log"
+
+// goSafe 执行 fn 并 recover 一切 panic（记录日志，不崩溃进程）。
+// 用法：go goSafe(func() { ... })
+func goSafe(fn func()) {
+	defer func() {
+		if r := recover(); r != nil {
+			log.Printf("[panicguard] goroutine recovered: %v", r)
+		}
+	}()
+	fn()
+}

server/sync-service/handlers/relay.go

@@ -56,7 +56,7 @@ const (
 )
 
 func init() {
-	go relayManager.cleanupLoop()
+	go goSafe(relayManager.cleanupLoop)
 }
 
 // cleanupLoop 周期回收过期配对（waiting 超 TTL / running 超最长存活）。

server/sync-service/handlers/rooms.go

@@ -73,7 +73,7 @@ type RoomManager struct {
 var roomManager = &RoomManager{rooms: make(map[string]*Room)}
 
 func init() {
-	go roomManager.cleanupLoop()
+	go goSafe(roomManager.cleanupLoop)
 }
 
 // 错误哨兵

server/sync-service/handlers/social_mirror.go

@@ -90,7 +90,7 @@ var socialMirrorManager = &SocialMirrorManager{
 }
 
 func init() {
-	go socialMirrorManager.cleanupLoop()
+	go goSafe(socialMirrorManager.cleanupLoop)
 }
 
 // ---------- SocialMirrorManager 核心方法 ----------

server/sync-service/handlers/websocket.go

@@ -170,8 +170,8 @@ func HandleWebSocketWithGin(c *gin.Context, userID string, deviceID string) {
 		return
 	}
 
-	go wsConn.writePump()
-	go wsConn.readPump()
+	go goSafe(wsConn.writePump)
+	go goSafe(wsConn.readPump)
 }
 
 // BroadcastOperation notifies all other online devices of a user about new operations.

server/sync-service/handlers/ws_connection.go

@@ -129,10 +129,10 @@ func (c *WSConnection) readPump() {
 			// 防止单连接洪泛打满数据库连接池（上限 50）拖垮全部用户
 			select {
 			case c.syncReqSlots <- struct{}{}:
-				go func() {
+				go goSafe(func() {
 					defer func() { <-c.syncReqSlots }()
 					c.handleSyncRequest(payload.SinceVersion)
-				}()
+				})
 			default:
 				log.Printf("[ws] sync_request dropped (in-flight limit reached) user=%s device=%s", c.UserID, c.DeviceID)
 			}

server/sync-service/handlers/ws_manager.go

@@ -71,11 +71,11 @@ func (m *WSManager) unregister(c *WSConnection) {
 		}
 	}
 	// M3: 断开时从在线设备集合移除
-	go func() {
+	go goSafe(func() {
 		if err := cache.SetDeviceOffline(context.Background(), c.UserID, c.DeviceID); err != nil {
 			log.Printf("[ws] SetDeviceOffline failed user=%s device=%s: %v", c.UserID, c.DeviceID, err)
 		}
-	}()
+	})
 }
 
 // broadcastToUser sends a message to all online devices of a user, optionally excluding one device.
@@ -94,7 +94,7 @@ func (m *WSManager) broadcastToUser(userID string, excludeDeviceID string, messa
 		if !conn.send(message) {
 			// Buffer full or closed → close connection to protect the server.
 			log.Printf("[ws] buffer overflow, closing user=%s device=%s", userID, deviceID)
-			go conn.close()
+			go goSafe(conn.close)
 		}
 	}
 }
@@ -113,7 +113,7 @@ func (m *WSManager) sendToUser(userID string, message []byte) {
 		if !conn.send(message) {
 			// Buffer full or closed → close connection to protect the server.
 			log.Printf("[ws] buffer overflow, closing user=%s", userID)
-			go conn.close()
+			go goSafe(conn.close)
 		}
 	}
 }

server/sync-service/main.go

@@ -138,11 +138,11 @@ func main() {
 		Handler: r,
 	}
 
-	go func() {
+	go middleware.GoSafe(func() {
 		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
 			logger.Fatal("Failed to start server", zap.Error(err))
 		}
-	}()
+	})
 
 	<-ctx.Done()
 	logger.Info("shutdown signal received, closing WebSocket connections")

server/sync-service/middleware/panicguard.go

@@ -0,0 +1,22 @@
+package middleware
+
+// @ai-context
+// goroutine panic 统一防护：Go 中任一 goroutine panic 且未 recover 会直接崩溃整个进程。
+// 本包提供 GoSafe 包装器，供所有 go 启动点使用（writePump/readPump/cleanupLoop/
+// 异步查询等），把"单连接/单协程异常"隔离在进程之外。
+// Why: 2026-08 审计发现 sync-service 生产代码 0 处 defer recover()，11 处 go 启动点
+// 任一 panic 即整体宕机；WebSocket 长连接场景下恶意/异常帧是真实触发源。
+// 注意：recover 只阻止进程崩溃，不替代业务错误处理——日志必须保留上下文。
+
+import "log"
+
+// GoSafe 在 goroutine 内执行 fn，panic 时记录日志并吞掉异常（不崩溃进程）。
+// 用法：go GoSafe(func() { ... })
+func GoSafe(fn func()) {
+	defer func() {
+		if r := recover(); r != nil {
+			log.Printf("[panicguard] goroutine recovered: %v", r)
+		}
+	}()
+	fn()
+}