SRS HTTP Callback 深入指南事件通知协议、配置实战与业务鉴权集成【免费下载链接】srsSRS is a simple, high-performance, AI-driven real-time media server supporting RTMP, WebRTC, HLS, HTTP-FLV, HTTP-TS, SRT, MPEG-DASH, and GB28181, with codec support for H.264, H.265, AV1, VP9, AAC, Opus, and G.711.项目地址: https://gitcode.com/GitHub_Trending/sr/srsSRSSimple Realtime Server内置了完整的 HTTP CallbackHTTP 钩子能力允许流媒体服务器在推流、拉流、录制、切片等关键生命周期节点通过 HTTP POST 请求主动通知业务服务器实现鉴权、计数、录制联动、CDN 分发等业务扩展。本文将以 SRS 官方文档《HTTP Callback》为主体结合仓库内源码与配置系统讲解回调事件的完整协议、逐项配置参数、多语言业务端实现以及基于回调的 Token 鉴权与 HTTPS 安全实践。回调机制总览SRS 的 HTTP Callback 本质上是一个事件通知 鉴权回调机制当客户端如 FFmpeg、OBS向 SRS 推流或播放流时SRS 会向你的业务服务器发送 HTTP 请求通知对应事件的发生。整体工作流如下-------- -------- ----------------------- | FFmpeg |---- SRS |--HTTP-Callback---- Your Business Server | -------- -------- -----------------------在这个流程中FFmpeg / OBS 等推流端或播放端作为事件源触发on_publish、on_play等事件SRS事件触发的中转方负责构造事件数据并以 HTTP POST 方式投递给业务服务器业务服务器Your Business Server接收并处理事件返回 HTTP 200 与错误码 0 表示成功从而放行或拒绝客户端。从源码结构看这一能力由 trunk/src/app/srs_app_http_hooks.hpp 中的ISrsHttpHooks接口定义全局实例_srs_hooks由 trunk/src/app/srs_app_http_hooks.cpp 实现。接口注释明确区分了两类语义返回srs_error_t的方法如on_publish、on_play用于校验业务方可以通过返回错误拒绝推流/播放返回void的方法如on_unpublish、on_stop是纯通知无法阻止该操作的发生。快速体验10 分钟跑通第一个回调SRS 官方文档给出了一个完整的端到端验证链路仓库中对应的示例配置文件位于 trunk/conf/http.hooks.callback.conf。第一步启动开启回调的 SRS./objs/srs -c conf/http.hooks.callback.conf该示例配置在__defaultVhost__上开启了http_hooks并配置了四个最常用的回调事件详见 trunk/conf/http.hooks.callback.confvhost __defaultVhost__ { http_hooks { enabled on; on_publish http://127.0.0.1:8085/api/v1/streams http://localhost:8085/api/v1/streams; on_unpublish http://127.0.0.1:8085/api/v1/streams http://localhost:8085/api/v1/streams; on_play http://127.0.0.1:8085/api/v1/sessions http://localhost:8085/api/v1/sessions; on_stop http://127.0.0.1:8085/api/v1/sessions http://localhost:8085/api/v1/sessions; } }注意该示例配置中daemon off;、srs_log_tank console;日志直接输出到控制台便于观察回调触发过程。第二步启动演示回调服务器SRS 仓库自带一个用 Go 原生 HTTP 框架实现的演示回调服务器即文档所说的你的业务服务器位于 trunk/research/api-server/server.go其中注册了/api/v1/streams、/api/v1/sessions等处理端点go run research/api-server/server.go启动后日志大致如下端口默认 8085#2023/01/18 22:57:40.835254 server.go:572: api server listen at port:8085, static_dir:... #2023/01/18 22:57:40.835600 server.go:836: start listen on::8085第三步推流触发回调用 FFmpeg 推流并在流地址后携带自定义参数ffmpeg -re -i doc/source.flv -c copy -f flv rtmp://localhost/live/livestream?kv业务服务器随即会收到on_publish事件Got actionon_publish, client_id3y1tcaw2, ip127.0.0.1, vhost__defaultVhost__, streamlivestream, param?kv这里的kv参数会被原样透传进param字段这正是基于回调做 Token 鉴权的关键入口——文档明确提示基于 HTTP 回调的 Token 鉴权方案详见 Token Authentication对应 DRM 文档。编译与内置性SRS 默认始终开启 HTTP 回调能力无需额外编译选项。构建 SRS 的完整流程可参考仓库内 Build 文档从 trunk 目录执行./configure make即可编译产物位于trunk/objs/srs这也是上文启动命令./objs/srs的路径来源。配置 SRS完整参数逐项解析官方文档以http.hooks.callback.conf为示例给出了包含全部事件与详尽注释的配置模板完整版见 trunk/conf/full.conf 中的hooks.callback.vhost.com示例以及精简版 trunk/conf/http.hooks.callback.conf。以下是各配置项的核心语义。通用结构vhost your_vhost { http_hooks { # 是否启用 http hooks默认 off。 enabled on; # 事件与回调 URL 的映射见下文各事件详解。 ... } }每个事件均可配置多个 URL用空格分隔SRS 会逐个依次通知。enabled与各事件 URL 均支持环境变量覆盖SRS_VHOST_HTTP_HOOKS_ENABLED控制开关SRS_VHOST_HTTP_HOOKS_ON_PUBLISH、SRS_VHOST_HTTP_HOOKS_ON_UNPUBLISH、SRS_VHOST_HTTP_HOOKS_ON_PLAY、SRS_VHOST_HTTP_HOOKS_ON_STOP等控制对应事件 URL详见 trunk/conf/full.conf 的注释使用环境变量时多个 URL 需用空格分隔并正确加引号。on_publish推流开始当客户端编码器向vhost/app/stream推流时触发。SRS 会 POST 一个 JSON 对象字段如下{ action: on_publish, client_id: 9308h583, ip: 192.168.1.10, vhost: video.test.com, app: live, stream: livestream, param:?tokenxxxsaltyyy, server_id: vid-werty, stream_url: video.test.com/live/livestream, stream_id: vid-124q9y3 }若鉴权通过业务方必须返回 HTTP 200 且响应体为整数0或 JSON{code:0}。# 支持多个 API 钩子 on_publish http://xxx/api0 http://xxx/api1 http://xxx/apiNon_unpublish推流结束当客户端停止推流时触发数据字段与on_publish相同action为on_unpublish。这是纯通知类事件业务方返回失败也不会阻止推流停止。on_play播放开始当客户端开始播放流时触发POST 数据在on_publish基础上额外携带pageUrl字段{ action: on_play, client_id: 9308h583, ip: 192.168.1.10, vhost: video.test.com, app: live, stream: livestream, param:?tokenxxxsaltyyy, pageUrl: http://www.test.com/live.html, server_id: vid-werty, stream_url: video.test.com/live/livestream, stream_id: vid-124q9y3 }补充在完整配置 trunk/conf/full.conf 的对应注释中on_play的 JSON 还包含clients: 3字段表示当前播放该流的客户端数量含刚接入的这一个。这在按需起播第一个观众到达时clients1才启动推流端场景下非常有用。on_stop播放结束当客户端停止播放时触发数据字段与on_play相同action为on_stop同为纯通知类事件。on_dvrDVR 文件生成当 SRS 完成一个 DVR 录制文件reap时触发POST 数据在公共字段基础上增加录制文件信息{ action: on_dvr, client_id: 9308h583, ip: 192.168.1.10, vhost: video.test.com, app: live, stream: livestream, param:?tokenxxxsaltyyy, cwd: /usr/local/srs, file: ./objs/nginx/html/live/livestream.1420254068776.flv, server_id: vid-werty, stream_url: video.test.com/live/livestream, stream_id: vid-124q9y3 }cwd是 SRS 工作目录file是录制文件的相对路径。on_hlsHLS 切片生成当 SRS 生成一个新的 HLS TS 切片并更新播放列表时触发POST 数据中包含切片时长与路径信息{ action: on_hls, client_id: 9308h583, ip: 192.168.1.10, vhost: video.test.com, app: live, stream: livestream, param:?tokenxxxsaltyyy, duration: 9.36, cwd: /usr/local/srs, file: ./objs/nginx/html/live/livestream/2015-04-23/01/476584165.ts, url: live/livestream/2015-04-23/01/476584165.ts, m3u8: ./objs/nginx/html/live/livestream/live.m3u8, m3u8_url: live/livestream/live.m3u8, seq_no: 100, server_id: vid-werty, stream_url: video.test.com/live/livestream, stream_id: vid-124q9y3 }各字段含义duration为切片时长秒file/url为切片本地路径与相对 URLm3u8/m3u8_url为播放列表本地路径与相对 URLseq_no为切片序列号。on_hls_notifyHLS 切片 CDN 通知与on_hls不同on_hls_notify用于将切片文件推送/预热到 CDN 网络因此采用HTTP GET请求并在 URL 中内联替换变量# [server_id] 替换为服务器 ID[app] 替换为 app[stream] 替换为流名 # [param] 替换为参数[ts_url] 替换为切片 URL。 # 忽略业务服务器的任何返回数据。 # 注意随机选择一个 URL 上报并非全部上报。 on_hls_notify http://127.0.0.1:8085/api/v1/hls/[server_id]/[app]/[stream]/[ts_url][param];在源码 trunk/src/app/srs_app_http_hooks.cpp 中on_hls_notify的实现会读取回调响应体且设有独立的超时时间SRS_HLS_NOTIFY_TIMEOUT10 秒错误只记录日志、不影响切片流程。公共字段说明所有事件都携带以下两个公共标识字段stream_url不含扩展名的流标识如/live/livestreamstream_id流 ID业务方可用它去 HTTP API 查询流的详细信息。注意流媒体相关回调是on_publish与on_unpublish播放相关回调是on_play与on_stop。协议细节POST 请求与响应规范以on_publish为例SRS 发往业务服务器的完整请求如下POST /api/v1/streams HTTP/1.1 Content-Type: application-json Body: { server_id: vid-0xk989d, action: on_publish, client_id: 341w361a, ip: 127.0.0.1, vhost: __defaultVhost__, app: live, tcUrl: rtmp://127.0.0.1:1935/live?vhost__defaultVhost__, stream: livestream, param: , stream_url: video.test.com/live/livestream, stream_id: vid-124q9y3 }可以看到on_publish的请求中还包含了tcUrl客户端推流使用的完整 RTMP 地址。文档提示可以使用 wireshark 或 tcpdump 抓包验证这一协议。从源码 trunk/src/app/srs_app_http_hooks.cpp 的do_post实现可以确认响应校验的完整逻辑业务服务器必须返回 HTTP 状态码 200或 201 Created否则报ERROR_HTTP_STATUS_INVALID响应体不能为空响应体必须是以下两种之一数字字符串0对应宏SRS_HTTP_RESPONSE_OK定义于 trunk/src/app/srs_app_http_hooks.cppJSON 对象且code字段为整数 0形如{code: 0, data: }若code非 0SRS 会报ERROR_RESPONSE_CODE并断开客户端连接。Heartbeat服务器健康状态上报除了业务事件回调SRS 还支持心跳Heartbeat机制定时向 HTTP 回调服务器上报自身状态便于业务方监控 SRS 的健康状况、判断是否发生重启。# 心跳上报到 api server # 注意上报的 ip 从系统统计中获取需要配置 stats.network。 heartbeat { # 是否启用心跳。 # 可通过环境变量 SRS_HEARTBEAT_ENABLED 覆盖。 # 默认off enabled off; # 心跳间隔秒推荐 0.3,0.6,0.9,1.2,1.5,1.8,2.1,2.4,2.7,3,...,6,9,12,.... # 可通过环境变量 SRS_HEARTBEAT_INTERVAL 覆盖。 # 默认9.9 interval 9.3; # 启动时 SRS 心跳上报的 RESTful HTTP API 地址。 # SRS 将 POST 如下数据 # { # device_id: my-srs-device, # ip: 192.168.1.100 # } # 可通过环境变量 SRS_HEARTBEAT_URL 覆盖。 # 默认http://127.0.0.1:8085/api/v1/servers url http://127.0.0.1:8085/api/v1/servers; # 设备 ID。 # 可通过环境变量 SRS_HEARTBEAT_DEVICE_ID 覆盖。 device_id my-srs-device; # 是否附带 summaries 上报。 # 若开启请求数据中会追加 /api/v1/summaries 的摘要对象 # { # summaries: summaries object. # } # 可选配置。 # 可通过环境变量 SRS_HEARTBEAT_SUMMARIES 覆盖。 # 默认off summaries off; # 心跳请求的可选认证。 auth { # 可通过环境变量 SRS_HEARTBEAT_AUTH_ENABLED 覆盖。 # 默认off enabled off; # 可通过环境变量 SRS_HEARTBEAT_AUTH_TYPE 覆盖。 # 仅支持 bearer type bearer; # 可通过环境变量 SRS_HEARTBEAT_AUTH_TOKEN 覆盖。 token proxy-registration-token; } }开启summaries后业务方可以拿到self.pid、self.srs_uptime等服务器状态字段从而判断 SRS 是否发生过重启。summaries各字段的详细说明参见 HTTP API: summaries。业务端实现Go / Nodejs(Koa) / PHP 三种示例Go 示例用 Go 原生net/http处理on_publish回调读取请求体并返回标准成功响应http.HandleFunc(/api/v1/streams, func(w http.ResponseWriter, r *http.Request) { b, err : ioutil.ReadAll(r.Body) if err ! nil { http.Error(w, err.Error(), http.StatusInternalServerError) } fmt.Println(string(b)) res, err : json.Marshal(struct { Code int json:code Message string json:msg }{ 0, OK, }) if err ! nil { http.Error(w, err.Error(), http.StatusInternalServerError) } w.Write(res) }) _ http.ListenAndServe(:8085, nil)Nodejs / Koa 示例用 Koa koa-router 处理回调直接以 JSON 对象返回const Router require(koa-router); const router new Router(); router.all(/api/v1/streams, async (ctx) { console.log(ctx.request.body); ctx.body {code: 0, msg: OK}; });PHP 示例PHP 通过php://input读取原始请求体$body json_decode(file_get_contents(php://input)); printf($body); echo json_encode(array(code0, msgOK));三个示例的共同点是读取 POST 的 JSON 请求体做业务处理然后返回 HTTP 200 与code0。仓库内的演示服务器 trunk/research/api-server/server.go 也采用同样的 Go 模式http.HandleFunc(/api/v1/streams, ...)、http.HandleFunc(/api/v1/sessions, ...)可作为生产级参考实现。回调事件汇总与响应规则SRS 支持的全部 HTTP 回调事件如下事件触发时机语义可拒绝操作on_publish客户端Flash/FMLE 等开始推流校验/通知是on_unpublish客户端停止推流通知否on_play客户端开始播放校验/通知是on_stop客户端停止播放通知否on_dvrDVR 录制文件 reap 完成通知否on_hlsHLS 切片文件 reap 完成通知否要点归纳Event事件发生时回调到指定 HTTP URLHTTP URL可配置多个 URL用空格分隔SRS 会逐个通知DataSRS 以 POST 方式将事件数据投递给指定 HTTP API拒绝语义对on_publish与on_playSRS 要求响应为表示错误码的整数0 表示成功当响应非 0 或 HTTP 状态码非 200 时SRS 会断开该客户端连接从而实现基于 IP、URL Token 或任意客户端信息的高级安全策略。高级主题HTTPS 回调SRS4 起支持 HTTPS 回调只需把回调 URL 从http://换成https://vhost your_vhost { http_hooks { enabled on; on_publish https://127.0.0.1:8085/api/v1/streams; on_unpublish https://127.0.0.1:8085/api/v1/streams; on_play https://127.0.0.1:8085/api/v1/sessions; on_stop https://127.0.0.1:8085/api/v1/sessions; on_dvr https://127.0.0.1:8085/api/v1/dvrs; on_hls https://127.0.0.1:8085/api/v1/hls; on_hls_notify https://127.0.0.1:8085/api/v1/hls/[app]/[stream]/[ts_url][param]; } }HTTPS 模式下SRS 的 HTTP 客户端ISrsHttpClient见 trunk/src/app/srs_app_http_hooks.cpp 中按 URL schema 初始化客户端会使用 HTTPS 建立连接业务端需部署 TLS 证书。响应与回调错误码回调成功时必须返回证明成功的响应否则 SRS 会拒绝客户端——这正好可用于拒绝非法客户端。成功响应有两种合法形态HTTP/1.1 200 OK Content-Length: 1 0或HTTP/1.1 200 OK Content-Length: 11 {code: 0}关于 SRS 标准错误码的完整定义如ERROR_HTTP_STATUS_INVALID、ERROR_RESPONSE_CODE对应的数值与含义参见 HTTP API: Error Code。运行上文提到的演示回调服务器cd trunk/research/api-server go run server.go 8085即可直观观察到正确的响应形态。WebRTC / WHIP / WHEP 支持这些回调同样适用于 WebRTC 场景WHIP 推流触发on_publishWHEP 拉流触发on_play。由于默认情况下 RTC Bearer 鉴权关闭回调本身即可独立完成对 WHIP 与 WHEP 的授权若同时启用 Bearer 鉴权则需在配置中开启rtc_bearer_enabled此时 WHIP/WHEP 请求必须先通过 Bearer 鉴权SRS 才会回调业务服务器。旧事件 on_connect / on_close在 SRS 4 之前的版本中存在on_connect与on_close事件。它们是 RTMP 协议层面定义的连接事件仅适用于 RTMP 流且与推流/播放事件存在语义重叠官方不推荐使用。从源码看这两个事件在 trunk/src/app/srs_app_http_hooks.cpp 中仍保留了实现on_connect返回错误码可拒绝连接on_close会携带send_bytes/recv_bytes累计字节数但新项目应以on_publish/on_play等事件为准。回调鉴权实战on_publish回调用作高级安全网关是官方推荐实践业务服务器根据回调 JSON 中的ip、paramURL 中的 token或任意客户端信息返回code0放行或非 0拒绝。结合本文开头快速体验中的?kv参数透传即可实现基于 Token 的流级鉴权更完整的方案含 HMAC 签名等细节参见 Token Authentication。扩展阅读回调配置完整注释版trunk/conf/full.conf搜索hooks.callback.vhost.com即可定位 HTTP hooks 完整示例精简可运行示例trunk/conf/http.hooks.callback.conf回调核心实现trunk/src/app/srs_app_http_hooks.cpp 与接口定义 trunk/src/app/srs_app_http_hooks.hpp演示回调服务器trunk/research/api-server/server.goHTTP API 与错误码HTTP API 文档快照场景下的 HTTP Callback 应用snapshot【免费下载链接】srsSRS is a simple, high-performance, AI-driven real-time media server supporting RTMP, WebRTC, HLS, HTTP-FLV, HTTP-TS, SRT, MPEG-DASH, and GB28181, with codec support for H.264, H.265, AV1, VP9, AAC, Opus, and G.711.项目地址: https://gitcode.com/GitHub_Trending/sr/srs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考