本文是 VSS流播放详解 的配套开发笔记。项目地址https://github.com/openskeye/go-vss1. 明确三个要点POST /api/video/stream只有一套StreamResp外壳内里走哪路完全由Device.AccessProtocol决定。流媒体是否拉起来不都是StartRelyPull的成功协议 4GB28181在Invite 成功后就返回不会再走文件末尾的StartRelyPull没画面需要去查SIP MS Pub。streamName是全局会话键回放带PlaybackCount后缀、QuerystreamName可覆盖默认值StopMultiMSStream / Invite 防重入 / 快照都围着他的规则改命名规则要谨慎。2. 时间参数直播 / 回放// 回放 if req.EndAt 0 req.StartAt 0 { playType stream.PlayTypePlayback autoStopPullAfterNoOutMs 10000 }回放判定是StartAt 0 EndAt 0毫秒时间戳少一个则仍是直播流名与autoStopPullAfterNoOutMs60s vs 10s都不一致。前端只传endAt、或把秒当毫秒传表现为「以为是回放实际一直 live」Invite/拉流行为全错。联调先打印时间戳数量级。3. MS 节点VoteNode与PlayAddressMSIds投不出节点→ 直接「未设置流媒体源」与设备是否在线无关。IsDef分支非默认要GetMSConf拉端口再PlayAddress默认节点用已有msNode。MS HTTP 管理端口不通时地址数组全空客户端报「没地址」先检测curlhttp://{msAddress}的配置接口。httpsquery通过ms.New(...).WithHttps(req.Https)影响投票与播放侧 HTTPS 能力与 SIP 无关和网关TLS 终止混用时容易出错。4. 协议表协议streamUrl是否StartRelyPull排障1 流媒体源设备StreamUrlstreamUrl ! 会MS 拉流参数、RTSPTCP/UDPMediaProtocolMode→rtspMode2 RTMP 推不设等设备推一般不进StartRelyPullon_pub_start 收到了没、流名与 MS 是否一致3 ONVIF通道StreamUrl同左通道 URL 是否过期、认证、rtsp_mode4 GB28181Invite 链路透传本接口不调StartRelyPullCatalog/Invite/200 SDP/MS RTPPub见下节rtspMode注释在源码里写的是0tcp1udpMediaProtocolMode 0时置rtspMode 1UDP需要和 MS 文档对照核对别凭直觉写反了。5. GB28181stream_playcase devices.AccessProtocol_4: // GB28181协议 if playType stream.PlayTypePlayback { if err : ms.New(l.ctx, l.svcCtx).StopMultiMSStream(/* 流名前缀playback */); err ! nil { // ... } else { time.Sleep(1 * time.Second) } } if res : gbs.InviteLogic.New(...).Invite(gbs.InviteParams{ ... }); res ! nil res.Err ! nil { return res } go l.saveChannelSnapshot(streamName, res.Data) return types.HttpResponse{Data: data}回放先StopMultiMSStreamSleep 1s为的是少抢流前缀拆法依赖streamName与playType字符串改Produce规则时要连同这里一起测。成功路径Invite→ 立刻 HTTP 返回StreamResp媒体建立是异步的。通常「接口通了没画面」多半还在 SIP/MS。请参考 [5.1 信令与 SDP]、[2.4.1.1 SDP]。6.streamName覆盖 Query对齐现有会话if l.c ! nil { if v : l.c.Query(streamName); v ! { streamName v } }前端随便传streamName与Invite 里实际用的名不一致会导致Stop 停错流、快照存错键、前端播放器 404。应对约定覆盖仅用于重连同一会话与video_live_invite同源。7.StartRelyPull失败即整体失败在非 GB 分支在streamUrl ! 时调用 MS/api/ctrl/start_relay_pull任一错误直接 HTTP 错误响应。MS 离线、超时、URL 不可达、鉴权失败——现象都是业务层 4xx/5xx注意排查。8. 快照与播放解耦go saveChannelSnapshot流截图、FFmpeg、目录配置失败不影响播放接口返回成功。当看到没有缩略图就认定播放失败需要先分两条线查拉流 URL 能否播vsSaveVideoSnapshotDir/ FFMpeg 配置。9. 并发与防抖2.4.1.0第六节已讲解stream_play高频重入要考虑dt节流或前端防抖否则 GB 路径尤易出现「第二次 Invite 被拒」。10. 联调清单回放StartAt/EndAt正整数、毫秒、时区是否一致。拉流协议MediaProtocolMode需与现场 RTSPTCP/UDP一致。改stream.New().Produce规则同步测StopMultiMSStream 前缀、快照路径、前端流名。RTMP(2)确认推流已上再播别只看 HTTP 返回。11. 相关文档文档内容2.4.1.0 VSS流播放详解主流程与源码索引2.4.1.2 信令发送流水线Catalog / SendLogic5.1 开发心得-信令字段与 SDPINVITE 头与 SDP 身份