root/video_socket-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
254d9337bf9e504326f1a2ea7e11d2800a06dce0
video_socket-server/.qoder/repowiki/zh/content/信令系统/信令消息对象.md
stary 6c13817527 修改
2026-05-16 13:24:02 +08:00

15 KiB
Raw Blame History

信令消息对象

**本文引用的文件** - [offer.ts](file://src/class/offer.ts) - [answer.ts](file://src/class/answer.ts) - [candidate.ts](file://src/class/candidate.ts) - [httphandler.ts](file://src/class/httphandler.ts) - [websockethandler.ts](file://src/class/websockethandler.ts) - [signaling.ts](file://src/signaling.ts) - [websocket.ts](file://src/websocket.ts) - [signaling.js](file://client/src/signaling.js) - [signaling.test.js](file://client/test/signaling.test.js) - [服务端接口与WebSocket消息类型.md](file://src/服务端接口与WebSocket消息类型.md) - [package.json](file://package.json)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件系统性地文档化了 WebRTC 信令消息对象 Offer、Answer 和 Candidate 的数据结构、字段定义与实现细节。重点覆盖：

  • Offer 类的 SDP 描述封装、时间戳管理与礼貌协商标志（polite）语义
  • Answer 类的应答消息构建与 SDP 交换流程
  • Candidate 类的 ICE 候选者序列化与传输机制
  • 消息对象的创建、验证与序列化方法
  • JSON 结构规范与字段含义
  • 实际消息交换示例与调试技巧
  • 不同通信模式（公共/私有）下的使用差异

项目结构

该项目采用前后端分离的 TypeScript/JavaScript 架构，核心信令逻辑位于服务端的 HTTP 与 WebSocket 处理器中，前端提供基于 HTTP 轮询与 WebSocket 的信令客户端。

graph TB
subgraph "客户端"
FE_HTTP["HTTP 客户端<br/>signaling.js"]
FE_WS["WebSocket 客户端<br/>signaling.js"]
end
subgraph "服务端"
HTTP["HTTP 路由<br/>signaling.ts"]
WS["WebSocket 服务器<br/>websocket.ts"]
HHTTP["HTTP 处理器<br/>httphandler.ts"]
HWS["WebSocket 处理器<br/>websockethandler.ts"]
MODELS["消息模型<br/>offer.ts / answer.ts / candidate.ts"]
end
FE_HTTP --> HTTP
FE_WS --> WS
HTTP --> HHTTP
WS --> HWS
HHTTP --> MODELS
HWS --> MODELS

图表来源

章节来源

核心组件

  • Offer：封装 SDP 描述、时间戳与礼貌协商标志
  • Answer：封装 SDP 描述与时间戳
  • Candidate：封装 ICE 候选者、SDP 媒体行索引与媒体 ID、时间戳

这些类作为纯数据载体，被 HTTP 与 WebSocket 处理器在消息收发时构造与使用。

章节来源

架构总览

HTTP 与 WebSocket 两条路径共同承载信令消息的收发与存储，处理器负责：

  • 会话与连接管理
  • 消息持久化与检索
  • 消息路由与广播
  • 通信模式（公共/私有）下的差异化行为
sequenceDiagram
participant C as "客户端(HTTP)"
participant R as "HTTP 路由(signaling.ts)"
participant H as "HTTP 处理器(httphandler.ts)"
participant S as "存储(Maps)"
participant WS as "WebSocket 服务器(websocket.ts)"
C->>R : POST /signaling/offer
R->>H : postOffer(...)
H->>S : 存储 Offer 对象
H-->>C : 200 OK
C->>R : GET /signaling/offer?fromtime=...
R->>H : getOffer(...)
H->>S : 查询并过滤
H-->>C : {offers : [{connectionId,sdp,polite,type,datetime}]}
Note over WS,H : WebSocket 路由与处理器同样处理 offer/answer/candidate

图表来源

详细组件分析

Offer 类分析

Offer 类用于封装 WebRTC Offer 信令消息的核心数据，包含 SDP 描述、时间戳与礼貌协商标志。

  • 字段定义

    • sdp: string —— SDP 描述字符串
    • datetime: number —— 消息创建时间戳（毫秒）
    • polite: boolean —— 礼貌协商标志，用于避免并发 offer 冲突

  • 构造与使用

    • HTTP 处理器在收到 offer 后，使用 sdp、当前时间与默认 polite 构造 Offer 对象并持久化
    • WebSocket 处理器在收到 offer 后，同样构造 Offer 对象并进行路由

  • 礼貌协商（Polite）语义

    • 在私有模式下，host 的 polite=false，participant 的 polite=true
    • 在公共模式下，polite 字段通常为 false，由服务端统一构造
classDiagram
class Offer {
+string sdp
+number datetime
+boolean polite
+constructor(sdp, datetime, polite)
}

图表来源

章节来源

Answer 类分析

Answer 类用于封装 WebRTC Answer 信令消息的核心数据，包含 SDP 描述与时间戳。

  • 字段定义

    • sdp: string —— SDP 描述字符串
    • datetime: number —— 消息创建时间戳（毫秒）

  • 构造与使用

    • HTTP 处理器在收到 answer 后，使用 sdp、当前时间构造 Answer 对象并持久化
    • WebSocket 处理器在收到 answer 后，同样构造 Answer 对象并进行路由
classDiagram
class Answer {
+string sdp
+number datetime
+constructor(sdp, datetime)
}

图表来源

章节来源

Candidate 类分析

Candidate 类用于封装 ICE 候选者消息，包含候选者字符串、SDP 媒体行索引与媒体 ID、时间戳。

  • 字段定义

    • candidate: string —— ICE 候选者描述
    • sdpMLineIndex: number —— SDP 媒体行索引
    • sdpMid: string —— SDP 媒体 ID
    • datetime: number —— 消息创建时间戳（毫秒）

  • 构造与使用

    • HTTP 处理器在收到 candidate 后，使用 candidate、sdpMLineIndex、sdpMid、当前时间构造 Candidate 对象并持久化
    • WebSocket 处理器在收到 candidate 后，同样构造 Candidate 对象并进行路由
classDiagram
class Candidate {
+string candidate
+number sdpMLineIndex
+string sdpMid
+number datetime
+constructor(candidate, sdpMLineIndex, sdpMid, datetime)
}

图表来源

章节来源

消息对象的创建、验证与序列化

  • 创建

    • HTTP：客户端通过 POST /signaling/offer、/answer、/candidate 发送 JSON，服务端在处理器中解析并构造对应消息对象
    • WebSocket：客户端通过发送包含 type 与 data 的 JSON，服务端在 WebSocket 处理器中解析并构造对应消息对象

  • 验证

    • HTTP：处理器对必要字段进行校验（如 connectionId、sdp、candidate 等），并在缺失时返回错误
    • WebSocket：处理器对消息结构进行校验，确保 from、to、data 字段存在

  • 序列化

    • HTTP：消息对象被转换为 JSON 并返回给客户端
    • WebSocket：消息对象被包装为 { type, from, to, data, participantId } 形式发送

章节来源

JSON 结构规范与字段含义

  • Offer

    • 字段：connectionId, sdp, polite, type="offer", datetime
    • 含义：连接标识、SDP 描述、礼貌协商标志、消息类型、时间戳

  • Answer

    • 字段：connectionId, sdp, type="answer", datetime
    • 含义：连接标识、SDP 描述、消息类型、时间戳

  • Candidate

    • 字段：connectionId, candidate, sdpMLineIndex, sdpMid, type="candidate", datetime
    • 含义：连接标识、ICE 候选者、SDP 媒体行索引、SDP 媒体 ID、消息类型、时间戳

  • 通用字段

    • type：消息类型（connect/disconnect/offer/answer/candidate/on-message）
    • datetime：消息创建时间戳（毫秒）

章节来源

实际消息交换示例与调试技巧

  • HTTP 模式

    • 客户端通过 PUT /signaling 创建会话，随后通过 PUT /signaling/connection 建立连接
    • 使用 GET /signaling 获取所有消息，或分别 GET /signaling/offer、/answer、/candidate 拉取增量
    • 使用 fromtime 参数实现增量拉取，避免重复处理

  • WebSocket 模式

    • 客户端发送 { type: "connect", connectionId } 建立连接
    • 发送 { type: "offer"/"answer"/"candidate", from, data } 进行 SDP 交换
    • 监听服务端推送的 offer/answer/candidate 消息并更新本地 PeerConnection

  • 调试技巧

    • 使用浏览器开发者工具查看网络面板中的 HTTP 请求与响应
    • 在 WebSocket 面板观察消息收发，注意 participantId 与 from 字段
    • 关注服务端日志输出，定位消息路由问题
    • 使用测试用例参考消息格式与预期行为

章节来源

不同通信模式下的使用差异

  • 公共模式（Public）

    • 所有连接的客户端均可相互通信
    • offer/answer/candidate 向所有其他客户端广播
    • 适合点对点直连场景

  • 私有模式（Private）

    • 一个 connectionId 对应一个房间，包含 1 个 host 与多个 participants
    • host 为第一个加入者（polite=false），participants 为后续加入者（polite=true）
    • host 可单播给特定 participant 或广播给所有 participants；participant 仅能发送给 host
    • host 离开时房间关闭，participants 被断开；participant 离开房间仍保留

章节来源

依赖关系分析

graph LR
O["Offer 类<br/>offer.ts"] --> HH["HTTP 处理器<br/>httphandler.ts"]
A["Answer 类<br/>answer.ts"] --> HH
C["Candidate 类<br/>candidate.ts"] --> HH
HH --> S["会话/连接映射(Maps)"]
HH --> WS["WebSocket 服务器<br/>websocket.ts"]
HH --> HWS["WebSocket 处理器<br/>websockethandler.ts"]
HWS --> O
HWS --> A
HWS --> C

图表来源

章节来源

性能考虑

  • 增量拉取：HTTP GET 支持 fromtime 参数，减少重复消息传输与解析开销
  • 会话超时：10 秒无请求自动清理会话，避免内存泄漏
  • 广播策略：公共模式下广播所有消息，私有模式下按需单播/广播，降低网络负载
  • 心跳检测：可选的心跳机制（ping/pong）用于保持连接活跃，避免被中间设备断开

[本节为通用建议，不直接分析具体文件]

故障排查指南

  • HTTP 404：检查会话 ID 是否正确传入请求头 Session-Id
  • 消息未到达：确认通信模式（公共/私有）与连接配对是否正确
  • polite 标志异常：检查连接顺序与私有模式下 host/participant 的角色分配
  • Candidate 缺失：确认 ICE 候选者是否正确序列化，sdpMLineIndex 与 sdpMid 是否匹配
  • WebSocket 断开：检查心跳机制与网络稳定性，关注服务端日志

章节来源

结论

Offer、Answer 与 Candidate 三类消息对象构成了 WebRTC 信令的核心载体。通过 HTTP 与 WebSocket 双通道，结合公共/私有两种通信模式，系统实现了灵活高效的信令交换能力。理解各字段的语义与消息流转过程，有助于在实际开发中快速定位问题并优化性能。

[本节为总结性内容，不直接分析具体文件]

附录

API 一览（HTTP）

  • GET /signaling/connection-ids
  • PUT /signaling
  • GET /signaling
  • DELETE /signaling
  • GET /signaling/connection
  • PUT /signaling/connection
  • DELETE /signaling/connection
  • GET /signaling/offer
  • POST /signaling/offer
  • GET /signaling/answer
  • POST /signaling/answer
  • GET /signaling/candidate
  • POST /signaling/candidate

章节来源

WebSocket 消息类型

  • connect/disconnect：连接生命周期
  • offer/answer/candidate：SDP 交换
  • on-message：通用消息
  • broadcast：广播消息
  • call-request：呼叫请求
  • participant-joined/participant-left：私有模式参与者变更

章节来源

Reference in New Issue View Git Blame Copy Permalink