gin.Context.Stream是SSE推送的唯一可行入口，因其绕过中间件干扰、直接接管响应流，避免手动设置头和flush的易错环节；使用前须设Content-Type、Cache-Control等关键头，每次推送后立即Flush，且不可混用其他响应方法。
为什么 gin.Context.Stream 是 SSE 推送的唯一可行入口
Gin 本身不提供原生 SSE 封装，context.Stream 是最直接、最可控的底层接口。它绕过中间件对响应体的二次处理（比如 gin.Recovery 可能提前关闭连接），也避免了用 context.Writer 手动写 header + flush 的繁琐和易错——比如忘记设置 text/event-stream、漏掉 Cache-Control: no-cache 或连续两次 Flush() 失败导致连接静默断开。
使用时必须注意：context.Stream 会接管整个响应流，后续不能再调用 c.JSON、c.String 等方法；且一旦开始推送，客户端断连后 Gin 不会自动通知服务端，需靠心跳或超时机制主动清理 goroutine。
- 必须在调用前设置：
c.Header("Content-Type", "text/event-stream")、c.Header("Cache-Control", "no-cache")、c.Header("Connection", "keep-alive") - 每次推送日志行前，必须调用
c.Writer.Flush()，否则数据滞留在缓冲区，客户端收不到 - 不要在流中混用
c.Error()或 panic 恢复逻辑，它们可能干扰流状态
如何安全地把系统日志（如 log.Logger 或 zerolog）接入 SSE 流
不能直接把日志输出重定向到 c.Writer——那会破坏 HTTP 响应结构，且无法控制每条日志的 event 格式。正确做法是用 channel 作桥接：日志写入一个带缓冲的 chan string，HTTP handler 启动一个 goroutine 从该 channel 读取、格式化为 SSE 标准事件（data: ...\n\n），再通过 c.Stream 推送。
关键约束在于并发安全与背压：多个日志 goroutine 往 channel 写，SSE handler 单独消费；channel 缓冲区大小建议设为 64～128，太小易丢日志，太大则内存积压；若 channel 满，日志写入应非阻塞丢弃（用 select { case ch ），避免阻塞业务线程。
立即学习“go语言免费学习笔记（深入）”；
- SSE 格式必须严格：每条日志封装为
data: {"level":"info","msg":"cpu=82%"}\n\n，结尾两个换行不可少 - 推荐加
event: log字段便于前端区分事件类型，如：event: log\ndata: ...\n\n - 若用
zerolog，可用zerolog.NewConsoleWriter()输出 JSON 字符串，再套一层fmt.Sprintf("data: %s\n\n", jsonStr)
net/http.TimeoutHandler 会杀死 SSE 连接？必须绕开
Gin 默认使用标准 http.Server，而其 ReadTimeout 和 WriteTimeout 对长连接是致命的——哪怕只设了 30 秒，只要连接空闲超时，Go 就会强制关闭连接，前端收到 error 事件。这不是 Gin 的问题，是 Go HTTP Server 的设计限制。
解决方式只有两个：一是彻底禁用超时（server.ReadTimeout = 0、server.WriteTimeout = 0），二是改用 IdleTimeout + 心跳保活。更稳妥的是后者：在 SSE handler 中每 15 秒推一条空事件（:\n\n），同时设置 server.IdleTimeout = 30 * time.Second，这样既满足连接存活，又不被误杀。
- 绝对不要设置
ReadTimeout或WriteTimeout，它们对 SSE 无意义且有害 - 心跳事件必须以冒号开头（
:），这是 SSE 注释语法，客户端忽略但可重置 idle 计时器 - 前端 JS 需监听
onerror并自动重连，因为网络抖动仍可能导致断连
前端 EventSource 怎么处理断连与重连边界
浏览器 EventSource 默认重试间隔是 3 秒，但首次失败后不会立即重试，而是等待约 5 秒——这会导致监控画面卡顿。更严重的是，如果服务端推送了非法格式（比如少了一个换行），EventSource 会静默关闭连接，不触发 onerror，只走 onclose，容易误判为正常结束。
实际部署时，必须手动接管重连逻辑：监听 onerror 和 onclose，用指数退避（如 1s → 2s → 4s）重新创建 EventSource 实例，并记录最后收到的 id 字段用于断点续推（如果服务端支持）。另外，Chrome 对单域名 EventSource 连接数有限制（通常 6 个），监控页若开多个标签页可能触发限流。
- 初始化时传入
{ withCredentials: true }，否则跨域请求带 cookie 会失败 - 服务端推送时加上
id: 12345字段，前端可在onmessage中缓存该值 - 避免在
onopen中立刻执行 heavy 渲染，应等首条message到达后再更新 UI
Gin 下 SSE 最难缠的不是推送逻辑，而是连接生命周期管理——服务端没感知断连、客户端不明确错误原因、超时配置反向破坏长连接。这些点不提前堵住，上线后只会看到日志流时断时续，却查不出根因。
