SkeyeVSS中SSE（Server-Sent Events）架构设计

本文说明core/app/sev/vss信令服务内SSE 长连接的实现方式独立 HTTP 服务、/events入口、按type路由到不同 Logic以及messageChan→ 文本帧 → Flush的推送模型。可与《SkeyeVSS中HTTP架构设计》《skeyeVSS中WebSocket架构设计》对照阅读。源代码 点击直达一、定位与进程角色项目说明启动main.gogo server.NewSSESev(svcCtx).Start()与Gin HTTP、WebSocket、SIP并行。监听Config.HostConfig.SSE.Port与Http.Port、WS.Port分离。实现标准库net/http非 Gin单路由GET /events。用途运维/诊断类服务端单向推送服务状态指标、SIP 日志流、下载进度、设备/通道诊断、设备在线状态等。类型名SSWSev为历史命名源码internal/server/sse.go语义上即SSE Server。二、整体数据流messageChan (buffer 10)Logic DO (goroutine)RegisterRouterhandler /events客户端 EventSourcemessageChan (buffer 10)Logic DO (goroutine)RegisterRouterhandler /events客户端 EventSourceloop[消费]GET /events?typesev_state...Header: text/event-stream, Flushmake(chan SSEResponse, 10)RegisterRouter(ctx, r, svcCtx, Ch)go DO(req) 或 DO()SSEResponsetoResp → fmt.Fprintf FlushSSE 帧defer close(Ch)要点每个 SSE 连接独占一个messageChan缓冲10。Logic 通过messageChan - SSEResponse{...}产出事件handler中的for range messageChan统一写出并http.Flusher.Flush()在需分帧场景。请求生命周期绑定r.Context()RegisterRouter将context.WithCancel(r.Context())传入各 Logic客户端断开时可取消内部select具体 Logic 是否完全退出取决于是否仍向 channel 发送、以及 channel 何时关闭见后文「生命周期」。三、HTTP 层handler与 SSE 帧格式文件internal/server/sse.go。3.1 响应头Content-Type: text/event-stream Cache-Control: no-cache Connection: keep-alive Access-Control-Allow-Origin: *3.2toResp与SSEResponse语义types.SSEResponseinternal/types/types.go字段含义Data业务负载序列化后写入 SSEdata行。Err错误输出为event: end JSONerror字段并结束本次连接循环。Done正常结束输出event: enddata: {}。DelayClose为true时在defer中延迟 2s 再close(messageChan)便于尾包发出。帧拼装规则toResp成功且带Datadata: {data: JSON}\n\n返回flushtrue→ 写完后继续for range流式多帧。Errevent: end\ndata: {error:...}\n\nflushfalse→ 写出后跳出循环。仅Doneevent: end\ndata: {}\n\n跳出循环。空字符串且非 Done跳出循环。前端可使用EventSource或自行解析data:行嵌套结构为{data: ...}与部分框架 data裸JSON 略有不同联调时需注意。四、路由type查询参数 注册表文件internal/handler/sse/routers.go。根据r.URL.Query().Get(type)switch分发。带请求体的类型使用sseHandlergorilla/schemaDecode(req, r.URL.Query())go-playground/validatorStruct(req)校验失败向messageChan写入SSEResponse{Err: ...}go handler.DO(req)在独立 goroutine中执行避免阻塞RegisterRouter。sip_logs同步调用VSipLogs.New(...).DO()DO内部再起 goroutine自身立即返回。4.1 已支持的type一览type值Logic说明sev_stateSevState约1s推送一组服务内部计数下载任务、Catalog/心跳 map、Invite 限流、WS 连接数等。sip_logsSipLogLogicSIP 收/发日志流全局单活atomic.Bool订阅Broadcast两路 topic带1s heartbeat数据帧。file_downloadFileDownloadLogic文件下载进度通过DownloadManager拉文件并SSE 推送进度支持取消 querycancel1。device_diagnoseDeviceDiagnose设备诊断多阶段向 channel 推DeviceDiagnosesResp行。channel_diagnoseChannelDiagnose通道诊断逻辑类似步骤更多。device_online_stateDeviceOnlineStateLogic设备在线状态相关推送。未传type或无法识别向 channel 写入Err如 type 不能为空。各 Logic 的GetType()与常量如SevStateType需与前端约定一致。五、Logic 层契约定义于internal/types/types.gotypeSSEResponsestruct{Datainterface{}Err*response.HttpErr DoneboolDelayClosebool}// 带 URL 参数解析 DO(req)typeSSEHandleLogic[Logic any,Req SSERequestType]interface{New(ctx context.Context,svcCtx*ServiceContext,messageChanchan*SSEResponse)LogicDO(req Req)GetType()string}// 无 Req仅 DO() — 如 sip_logstypeSSEHandleSPLogic[Logic any]interface{New(ctx context.Context,svcCtx*ServiceContext,messageChanchan*SSEResponse)LogicDO()GetType()string}约定New注入ctx可取消、ServiceContext、messageChan。DO内可多协程向客户端推送唯一途径是写messageChan由handler统一编码。长任务应在select中监听ctx.Done()避免协程泄漏。六、典型实现摘析6.1sev_state定时指标快照time.NewTicker(1 * time.Second)每秒组装[]SSESevStateItem。指标覆盖DownloadManager、SIP 节流 map、Invite 限流、流存在表、SN map、级联、WSClientCache.Len()等。适合状态获取 / 运维页订阅。6.2sip_logs广播订阅 单连接互斥sipLogIsActive同一时间只允许一路sip_logsSSE否则Err「其他客户端正在使用」。Broadcast.RegisterReceiver订阅BroadcastTypeSipRequest/BroadcastTypeSipReceive将字符串日志包装为map[type,content]写入messageChan。另起协程每秒推送content: heartbeat保持连接与前端心跳逻辑。ctx.Done()时sipLogIsActive置 false发Done: trueUnregisterReceiver结束。6.3file_download文件下载进度订阅Queryurl、filename、cancel等与DownloadManager的Subscribe / Unsubscribe / Finished配合。进度更新按状态机推送Data完成/取消/错误时带Done或Err结束会话。注意使用file_download需要详细阅读DownloadManager实现与使用。6.4 诊断类device / channel多步骤 RPC/探测分多帧推送DeviceDiagnosesRespLine/Title/Value等便于控制台逐行渲染含超时与错误分支。七、与 HTTP API、WebSocket 的对比维度Gin HTTP/apiSSE/eventsWebSocket端口Http.PortSSE.PortWS.Port方向请求-响应为主服务端主导推送双向框架Gin httpxnet/httpnet/http Gorilla鉴权视网关/业务当前 handler 未内置鉴权部署侧需网络隔离或反向代理校验子协议 TokenSSE 适合单向、文本 JSON、浏览器 EventSource大流量二进制更偏向 WS 或独立下载接口。八、背压与 channel 容量messageChan容量为 10。Logic 若在短时内连续发送超过 10 条且handler未及时消费发送方会阻塞。高频场景如 SIP 日志洪峰需控制上游广播速率或评估增大缓冲 / 丢弃策略。Flush每次写后刷新减少代理缓冲导致的延迟。九、连接生命周期说明handler的defer在for range messageChan退出后close(messageChan)若DelayClose则延迟 2s 再 close。长连接类 Logic如sev_state仅在ctx.Done()时停止发送若客户端断开而channel 未再收到结束帧且未 close理论上range可能长期阻塞——生产环境建议结合代理超时、客户端重连或在演进中在handler侧selectctx.Done()与messageChan做联合消费属增强项以当前源码为准。十、扩展新 SSE 能力的步骤在internal/logic/sse新增 Logic实现SSEHandleLogic或SSEHandleSPLogic定义GetType()常量。在internal/handler/sse/routers.go的switch增加case有 Query 结构体 →sseHandler(...)无参或特殊启动方式 → 与sip_logs类似直接New(...).DO()。约定Query 字段 tagform/validate与前端/events?type...一致。评估推送频率与channel 缓冲避免阻塞 Logic。若对公网开放在网关上补认证、限流、IP 白名单。十一、相关源码索引说明路径SSE 服务启动与写出core/app/sev/vss/internal/server/sse.go路由与参数解析core/app/sev/vss/internal/handler/sse/routers.go类型契约core/app/sev/vss/internal/types/types.goSSEResponse、SSEHandleLogic各业务 Logiccore/app/sev/vss/internal/logic/sse/*.go进程入口core/app/sev/vss/main.goSSE 端口配置core/tps/conf/config.go→VssSevConfig.SSE.Port