Linux桌面Python应用ICE连接滞留在checking状态排查求助

核心排查方向 #

1. ICE Candidate配置问题 #

• 检查是否完整收集并交换所有类型ICE Candidate（主机候选、反射候选、中继候选）
  • 确认代码监听icecandidate事件，且通过WebSocket完整发送至对端
  • 对端接收Candidate后，必须调用peerConnection.addIceCandidate()，同时处理Promise异常
• 验证STUN/TURN服务器配置有效性：

  # 示例STUN配置校验
  stun_server = RTCIceServer(urls="stun:stun.l.google.com:19302")
  peer_connection = RTCPeerConnection(configuration={"iceServers": [stun_server]})
  

  • 用stunclient stun.l.google.com 19302命令测试STUN连通性
  • 内网环境必须配置TURN服务器，否则无法完成NAT穿越

2. WebSocket消息交互完整性 #

• 排查消息丢失情况：
  • 在发送/接收offer、answer、Candidate环节添加日志，确认每条消息均被对端正确接收
  • 检查JSON序列化/反序列化逻辑，避免格式错误导致解析失败
• 规范SDP交换时机：
  • 必须在本地媒体流配置完成后再创建offer/answer，防止SDP缺失媒体描述
  • 对端收到offer后，需先绑定本地媒体流，再生成answer

3. 媒体流采集与绑定问题 #

• 验证OpenCV视频流与aiortc的MediaStreamTrack绑定逻辑：

  class VideoTrack(MediaStreamTrack):
      kind = "video"
      def __init__(self):
          super().__init__()
          self.cap = cv2.VideoCapture(0)
      async def recv(self):
          ret, frame = self.cap.read()
          if not ret:
              raise Exception("Failed to capture frame")
          frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
          return VideoFrame.from_ndarray(frame, format="rgb24")
  

  • 检查Linux下摄像头权限：确保当前用户属于video组（执行sudo usermod -aG video $USER）
  • 确认媒体流已添加至PeerConnection：peer_connection.addTrack(video_track)

4. PeerConnection状态监听与异常处理 #

• 完善状态监听与异常捕获逻辑：

  @peer_connection.on("iceconnectionstatechange")
  async def on_iceconnectionstatechange():
      print(f"ICE连接状态: {peer_connection.iceConnectionState}")
      if peer_connection.iceConnectionState == "failed":
          await peer_connection.restartIce()
  
  @peer_connection.on("connectionstatechange")
  async def on_connectionstatechange():
      print(f"PeerConnection状态: {peer_connection.connectionState}")
      if peer_connection.connectionState == "failed":
          await peer_connection.close()
  

  • 检查createOffer()、setLocalDescription()等异步操作是否添加异常捕获，避免Promise未处理拒绝

5. 网络环境限制排查 #

• 关闭本地防火墙或放行UDP端口（ICE默认使用UDP协议）
• 先测试同一局域网内设备连接，排除公网NAT穿越问题
• 暂时关闭VPN或代理后重试连接

内容的提问来源于stack exchange，提问作者Pavan V Parekh