文章目录
- [一、什么是 ZLMediaKit HTTP Hook 机制？](#一、什么是 ZLMediaKit HTTP Hook 机制？)
- [二、核心对比：为什么要用 Hook？](#二、核心对比：为什么要用 Hook？)
- [三、为什么 Hook 能影响 ZLM 行为？](#三、为什么 Hook 能影响 ZLM 行为？)
- [四、Hook 事件详解](#四、Hook 事件详解)
- [五、Spring Boot 实现关键要点](#五、Spring Boot 实现关键要点)
- 六、最佳实践建议
- 七、总结
在做 系统级直播开发 时，很多人都会遇到一个经典问题：
ZLMediaKit 的 WebHook 机制到底是什么？它能干什么？
项目中到底该怎么用？
核心结论：
事件驱动机制 → 实时通知 ZLMediaKit 关键业务事件 → 允许自定义处理逻辑
你要实现什么业务 ------ 就监听什么 Hook 事件并快速返回结果
一、什么是 ZLMediaKit HTTP Hook 机制？
ZLMediaKit 提供了一套 HTTP WebHook 机制 ，当服务器发生关键事件（推流/播放/状态改变/无人观看/未找到流/录制完成等）时，会主动 通过 HTTP POST JSON 向你预设的 URL 推送事件 。
这就像一个"反向调用 API"：
ZLM 事件发生 → ZLM 发起请求 → 你根据业务做处理 → 返回响应控制后续行为。
📌 Hook 不是轮询，而是被动实时通知，适合做鉴权、统计、自动管理等。
二、核心对比：为什么要用 Hook？
| 机制 | 用途 | 是否影响 ZL 行为 | 你能做什么 |
|---|---|---|---|
| on_publish | 推流鉴权 | ✅ 是 | 推流权限/规则校验 |
| on_play | 播放鉴权 | ✅ 是 | 播放防盗链/统计 |
| on_stream_none_reader | 无人观看 | ✅ 是 | 决定是否关闭无人的流 |
| on_stream_not_found | 流未找到 | ❌ 否 | 做按需拉流（懒加载） |
| on_stream_changed | 流上线/下线 | ❌ 否 | 更新流状态表 |
| on_server_keepalive | 节点心跳 | ❌ 否 | 集群节点存活检查 |
| on_server_started | 节点启动 | ❌ 否 | 节点注册/初始化 |
| on_rtp_server_timeout | RTP 超时 | ❌ 否 | RTP 链路异常监控 |
| on_record_mp4 | 录制完成 | ❌ 否 | 录制后处理/入库 |
Hook 的本质是 事件通知 + 结果决策 的事件驱动机制。([ZLMediaKit][1])
三、为什么 Hook 能影响 ZLM 行为？
核心逻辑来自 ZLMediaKit 的配置和 WebHook 处理逻辑：
[hook]
enable=1 # 启用 HTTP Hook
timeoutSec=10 # ZL 等待回调超时时间
on_publish=... # 推流鉴权事件地址
on_play=... # 播放鉴权事件地址
on_stream_none_reader=... # 无人观看事件
on_stream_not_found=... # 流未找到事件
on_stream_changed=... # 流上线/下线事件
on_server_keepalive=... # 心跳事件
on_server_started=... # 启动事件
on_rtp_server_timeout=... # RTP 超时
on_record_mp4=... # 录制完成当 ZLMediaKit 发生对应事件时，它会将事件 JSON 通过 HTTP POST 推送到你设置的 URL。开发者可以根据业务做处理并返回响应控制 ZLMediaKit 的下一步行为。
四、Hook 事件详解
🟣 1. on_publish --- 推流鉴权（核心）
触发时机：
推流开始（RTMP/RTSP/RTP）触发。
常见用途：
- 校验 URL Token
- 白名单/黑名单 IP 控制
- 限制设备推流规则
- 记录推流日志
📌 影响行为
返回非 code=0 ➜ 推流拒绝，否则允许推流。
🟢 2. on_play --- 播放鉴权 / 防盗链
触发时机：
每次播放（RTMP/RTSP/HLS/HTTP-FLV/ws-flv）时触发。
用途：
- 校验播放 Token / 防盗链
- 统计播放次数 / 观看时长
- 限制并发播放
📌 影响行为
返回非 code=0 ➜ 拒绝播放。
🔵 3. on_stream_none_reader --- 无人观看
触发时机：
当一个流在设定延迟内无人观看时触发。
用途：
- 自动关闭无人流
- 推送通知、释放资源
📌 影响行为
返回 JSON { code:0, close:true/false }
close:true 表示通知 ZLMediaKit 关闭该无人流。
🟡 4. on_stream_not_found --- 懒加载 / 按需拉流
触发时机：
客户端请求某个流但服务器当前找不到该流时触发。
用途：
- 自动向上游摄像机或推流器拉流
- 按需创建代理拉流（例如
addStreamProxy）
📌 注意
这个事件 不依赖返回值，只是通知你去做操作。
🟠 5. on_stream_changed --- 流状态变化通知
触发时机：
流上线（推流后真正注册）或下线时触发。
用途：
- 同步数据库流在线状态
- 监控/告警
- 推送业务系统流状态变更
📌 不影响 ZLMediaKit 行为
仅作为通知事件。
🔴 6. on_server_keepalive --- 节点心跳
触发时机：
ZLM 节点定期上报心跳。
用途：
- 保活检测
- 集群节点状态表管理
📌 不影响 ZLMediaKit 行为
仅用于节点健康监控。
🔵 7. on_server_started --- 节点启动事件
触发时机：
ZLMediaKit 完成启动后触发。([ZLMediaKit][1])
用途：
- 向注册中心注册
- 初始化监控链路
- 采集启动参数
📌 不影响 ZLMediaKit 行为
仅用于业务系统初始化逻辑。([ZLMediaKit][1])
🟣 8. on_rtp_server_timeout --- RTP 超时
触发时机：
ZLMediaKit 收不到上游 RTP 数据超时后触发。[3])
用途：
- RTP 失败告警
- 重新拉取或清理相关资源
📌 不影响 ZLMediaKit 行为
🟢 9. on_record_mp4 --- MP4 录制完成
触发时机：
ZLMediaKit 录制 MP4 文件完成后触发。
用途：
- 入库录制文件
- 后续转码发布 CDN
- 生成封面截图
📌 不影响 ZLMediaKit 行为
五、Spring Boot 实现关键要点
🧠 1. 必须用 @RequestBody 接收 JSON
ZLM 发送数据是 JSON，不接会解析失败。
🧠 2. 鉴权类事件要快速返回
ZLMediaKit 有超时等待策略，慢会影响推流/播放。
🧠 3. 非敏感结果可异步处理
on_stream_not_found、on_stream_changed、on_record_mp4 等可以发布事件异步消费。
🧠 4. 返回结构要严格符合 ZLMediaKit 要求
错误返回可能视为拒绝访问。
六、最佳实践建议
🎯 推流/播放鉴权 --- 必须做，否则默认全部允许
🎯 无人流自动关闭 --- 用于节省资源
🎯 按需拉流策略 --- 用于节省上游带宽
🎯 流状态表同步 --- 便于监控 / 大屏联动
🎯 节点心跳/启动 --- 用于节点管理 / 高可用集群
七、总结
ZLMediaKit HTTP Hook 是一种事件驱动机制
ZLM → 事件 → HTTP POST → 你的服务处理 → 控制返回
它让你可以实现：
- 鉴权
- 自动管理流生命周期
- 统计与监控
- 异常与资源管理