ZLMediaKit RESTful API详解：完整的Web Hook事件与业务逻辑集成

概述

ZLMediaKit作为一款高性能的流媒体服务器框架，提供了完善的RESTful API和Web Hook机制，使开发者能够轻松实现流媒体业务的深度定制和集成。本文将深入解析ZLMediaKit的API架构、Web Hook事件体系，并提供完整的业务集成方案。

核心架构设计

API请求处理流程

ZLMediaKit RESTful API详解：完整的Web Hook事件与业务逻辑集成_API


配置结构

[api]
apiDebug=1
secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc

[hook]
enable=1
timeoutSec=10
retry=1
retry_delay=3.0
alive_interval=30.0

RESTful API详解

基础API分类

API类别

主要功能

示例接口

服务器管理

配置获取、重启服务

/getServerConfig, /restartServer

流管理

流列表、状态查询

/getMediaList, /isMediaOnline

代理管理

拉流推流代理

/addStreamProxy, /addStreamPusherProxy

会话管理

客户端连接管理

/getAllSession, /kick_session

录制管理

录像文件操作

/getMp4RecordFile, /deleteRecordDirectory

核心API示例

获取媒体流列表
curl "http://127.0.0.1/index/api/getMediaList?secret=your_secret&schema=rtsp"

响应格式：

{
  "code": 0,
  "data": [
    {
      "schema": "rtsp",
      "vhost": "__defaultVhost__",
      "app": "live",
      "stream": "test",
      "readerCount": 3,
      "totalBytes": 1024000,
      "originType": 1,
      "originUrl": "rtsp://source/live/test"
    }
  ]
}
添加拉流代理
curl "http://127.0.0.1/index/api/addStreamProxy?secret=your_secret&vhost=__defaultVhost__&app=live&stream=test&url=rtmp://live.example.com/live/stream"
获取会话信息
curl "http://127.0.0.1/index/api/getAllSession?secret=your_secret"

Web Hook事件体系

事件分类与触发时机

事件类型

触发时机

业务应用场景

on_publish

推流鉴权

推流权限控制、流信息记录

on_play

播放鉴权

播放权限控制、观看统计

on_flow_report

流量统计

流量计费、带宽监控

on_stream_changed

流注册注销

流状态监控、自动清理

on_record_mp4

MP4录制完成

录制文件处理、转存

on_stream_none_reader

无人观看

自动停流、资源释放

Web Hook配置示例

[hook]
enable=1
on_publish=http://your-api-server/hook/publish
on_play=http://your-api-server/hook/play  
on_flow_report=http://your-api-server/hook/flow
on_stream_changed=http://your-api-server/hook/stream_changed
on_record_mp4=http://your-api-server/hook/record_mp4
on_stream_none_reader=http://your-api-server/hook/none_reader
timeoutSec=10
retry=2

Hook请求数据结构

推流鉴权事件 (on_publish)
{
  "mediaServerId": "your_server_id",
  "hook_index": 123456789,
  "schema": "rtmp",
  "vhost": "__defaultVhost__",
  "app": "live", 
  "stream": "test",
  "params": "",
  "ip": "192.168.1.100",
  "port": 1935,
  "id": "client_123",
  "originType": 0,
  "originTypeStr": "unknown"
}
播放鉴权事件 (on_play)
{
  "mediaServerId": "your_server_id",
  "hook_index": 123456790,
  "schema": "rtsp",
  "vhost": "__defaultVhost__",
  "app": "live",
  "stream": "test",
  "params": "token=abc123",
  "ip": "192.168.1.101",
  "port": 554,
  "id": "client_456"
}
流量统计事件 (on_flow_report)
{
  "mediaServerId": "your_server_id",
  "hook_index": 123456791,
  "schema": "rtmp",
  "vhost": "__defaultVhost__",
  "app": "live",
  "stream": "test",
  "params": "",
  "totalBytes": 10485760,
  "duration": 3600,
  "player": true,
  "ip": "192.168.1.102",
  "port": 1935,
  "id": "client_789"
}

业务逻辑集成方案

鉴权系统集成

class AuthHandler:
    def handle_publish(self, data):
        """推流鉴权处理"""
        # 验证推流权限
        if not self.check_publish_permission(data['app'], data['stream']):
            return {"code": -1, "msg": "推流权限不足"}
        
        # 记录推流信息
        self.record_stream_event(data)
        
        return {"code": 0, "msg": "success"}

    def handle_play(self, data):
        """播放鉴权处理"""
        # 验证播放token
        token = data.get('params', '').split('token=')[-1]
        if not self.validate_token(token):
            return {"code": -1, "msg": "无效的播放token"}
        
        return {"code": 0, "msg": "success"}

流状态监控系统

class StreamMonitor {
    constructor() {
        this.activeStreams = new Map();
    }

    handleStreamChanged(data) {
        const streamKey = `${data.vhost}/${data.app}/${data.stream}`;
        
        if (data.regist) {
            // 流注册
            this.activeStreams.set(streamKey, {
                schema: data.schema,
                startTime: Date.now(),
                readerCount: 0
            });
            console.log(`流上线: ${streamKey}`);
        } else {
            // 流注销
            this.activeStreams.delete(streamKey);
            console.log(`流下线: ${streamKey}`);
        }
    }

    handleFlowReport(data) {
        // 流量统计处理
        this.updateBandwidthUsage(data);
    }
}

自动伸缩资源管理

public class AutoScalingManager {
    private static final int MAX_STREAMS_PER_NODE = 100;
    
    public JsonNode handleStreamPublish(JsonNode data) {
        int currentStreams = getCurrentStreamCount();
        
        if (currentStreams >= MAX_STREAMS_PER_NODE) {
            // 触发水平扩展
            scaleOut();
            return createResponse(-1, "服务器负载过高，请稍后重试");
        }
        
        return createResponse(0, "success");
    }
    
    public JsonNode handleStreamNoneReader(JsonNode data) {
        // 无人观看时自动关闭流
        return createResponse(0, "success", Map.of("close", true));
    }
}

高级配置与优化

性能优化配置

[general]
maxStreamWaitMS=15000
streamNoneReaderDelayMS=20000
mergeWriteMS=0

[hook]
timeoutSec=5
retry=1
retry_delay=1.0

集群模式配置

[cluster]
origin_url=rtmp://origin1:1935/%s/%s;rtmp://origin2:1935/%s/%s
timeout_sec=15
retry_count=3

安全配置

[api]
secret=your_secure_random_secret

[http]
allow_ip_range=192.168.0.0-192.168.255.255,10.0.0.0-10.255.255.255

错误处理与调试

常见错误码

错误码

含义

解决方案

-100

鉴权失败

检查secret配置和IP白名单

-300

参数不合法

验证请求参数完整性

-400

代码异常

查看服务器日志排查问题

-500

接口未找到

检查API路径是否正确

调试模式启用

# 启用API调试日志
curl "http://127.0.0.1/index/api/setServerConfig?secret=your_secret&api.apiDebug=1"

# 获取服务器状态
curl "http://127.0.0.1/index/api/getStatistic?secret=your_secret"

最佳实践建议

  1. 密钥管理: 使用强随机密钥并定期更换
  2. 超时设置: 根据网络状况合理设置hook超时时间
  3. 重试机制: 配置适当的重试次数和间隔
  4. 监控告警: 实现hook失败告警机制
  5. 性能优化: 使用异步处理避免阻塞主线程
  6. 日志记录: 完整记录所有API和hook操作

总结

ZLMediaKit的RESTful API和Web Hook机制提供了强大的流媒体业务集成能力。通过合理配置和深度定制，可以实现完整的流媒体业务管理系统，包括权限控制、状态监控、自动伸缩等功能。本文提供的配置示例和代码模板可以帮助开发者快速构建稳定高效的流媒体服务平台。

在实际部署中，建议根据业务需求选择合适的hook事件，并实现相应的业务逻辑处理。同时注意性能优化和安全防护，确保系统的稳定性和安全性。