mediamtx控制API完全指南：通过RESTful接口实现服务器远程管理

【免费下载链接】mediamtx Ready-to-use SRT / WebRTC / RTSP / RTMP / LL-HLS media server and media proxy that allows to read, publish, proxy and record video and audio streams. 项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx

概述

MediaMTX（原rtsp-simple-server）是一个功能强大的媒体服务器，支持SRT、WebRTC、RTSP、RTMP和LL-HLS等多种流媒体协议。其控制API（Control API）提供了完整的RESTful接口，允许开发者远程监控、配置和管理媒体服务器，实现自动化运维和集成第三方系统。

本文将深入探讨MediaMTX控制API的各个方面，包括API启用、认证配置、端点详解、实战示例以及最佳实践。

API启用与基础配置

启用控制API

在MediaMTX配置文件中启用控制API：

api: yes
apiAddress: ":9997"

默认情况下，API监听在127.0.0.1:9997，仅允许本地访问。如需远程访问，需配置相应的网络设置和认证。

安全配置选项

apiEncryption: false
apiServerKey: ""
apiServerCert: ""
apiAllowOrigin: "*"
apiTrustedProxies: []

API认证机制

MediaMTX支持多种认证方式，确保API访问安全：

基本认证（Basic Authentication）

curl -u username:password http://127.0.0.1:9997/v3/paths/list

JWT认证配置

authMethod: "jwt"
authJWTJWKS: "https://your-domain.com/.well-known/jwks.json"
authJWTClaimKey: "sub"

内部用户认证

authInternalUsers:
- user: "admin"
  pass: "password"
  permissions:
  - action: "api"
    path: "*"

API端点详解

MediaMTX控制API采用RESTful设计，主要端点分类如下：

全局配置管理

端点	方法	描述
/v3/config/global/get	GET	获取全局配置
/v3/config/global/patch	PATCH	部分更新全局配置

路径配置管理

实时监控端点

资源类型	端点	描述
活动路径	/v3/paths/list	获取所有活动路径状态
RTSP连接	/v3/rtspconns/list	RTSP服务器连接列表
RTSP会话	/v3/rtspsessions/list	RTSP会话详细信息
WebRTC会话	/v3/webrtcsessions/list	WebRTC连接状态
SRT连接	/v3/srtconns/list	SRT连接统计信息
录制文件	/v3/recordings/list	录制文件列表

实战示例

1. 获取活动路径列表

curl http://127.0.0.1:9997/v3/paths/list

响应示例：

{
  "pageCount": 1,
  "itemCount": 2,
  "items": [
    {
      "name": "live",
      "confName": "live",
      "source": {
        "type": "rtspSession",
        "id": "abc123"
      },
      "ready": true,
      "readyTime": "2024-01-01T10:00:00Z",
      "tracks": ["video", "audio"],
      "bytesReceived": 10485760,
      "bytesSent": 52428800
    }
  ]
}

2. 动态添加媒体路径

curl -X POST http://127.0.0.1:9997/v3/config/paths/add/mystream \
  -H "Content-Type: application/json" \
  -d '{
    "source": "rtsp://camera.example.com/live",
    "record": true,
    "recordPath": "/recordings/%path",
    "maxReaders": 10
  }'

3. 监控服务器状态

# 获取RTSP连接统计
curl http://127.0.0.1:9997/v3/rtspconns/list

# 获取带宽使用情况
curl http://127.0.0.1:9997/v3/paths/list | jq '.items[].bytesSent'

4. 管理录制内容

# 列出所有录制
curl http://127.0.0.1:9997/v3/recordings/list

# 删除特定录制片段
curl -X DELETE "http://127.0.0.1:9997/v3/recordings/deletesegment?path=mystream&start=2024-01-01T10:00:00Z"

高级功能与集成

WebHook集成示例

MediaMTX支持通过API动态配置WebHook：

runOnConnect: "/opt/scripts/on-connect.sh"
runOnDisconnect: "/opt/scripts/on-disconnect.sh"
runOnRecordSegmentCreate: "/opt/scripts/on-record.sh"

自动化运维脚本

import requests
import json

class MediaMTXClient:
    def __init__(self, base_url="http://localhost:9997/v3", auth=None):
        self.base_url = base_url
        self.auth = auth
    
    def get_active_paths(self):
        response = requests.get(f"{self.base_url}/paths/list", auth=self.auth)
        return response.json()
    
    def add_stream_path(self, path_name, config):
        response = requests.post(
            f"{self.base_url}/config/paths/add/{path_name}",
            json=config,
            auth=self.auth
        )
        return response.status_code == 200
    
    def kick_rtsp_session(self, session_id):
        response = requests.post(
            f"{self.base_url}/rtspsessions/kick/{session_id}",
            auth=self.auth
        )
        return response.status_code == 200

# 使用示例
client = MediaMTXClient(auth=("admin", "password"))
active_paths = client.get_active_paths()
print(f"Active paths: {len(active_paths['items'])}")

监控仪表板集成

// 实时监控仪表板示例
async function updateDashboard() {
    try {
        const response = await fetch('/v3/paths/list');
        const data = await response.json();
        
        updatePathStats(data.items);
        updateBandwidthCharts(data.items);
        updateConnectionCounts();
    } catch (error) {
        console.error('Dashboard update failed:', error);
    }
}

// 每5秒更新一次
setInterval(updateDashboard, 5000);

性能优化与最佳实践

1. API响应优化

# 配置分页参数优化性能
readTimeout: "10s"
writeTimeout: "10s"
writeQueueSize: 1024

2. 监控指标收集

# 使用Telegraf收集监控指标
[[inputs.http]]
  urls = ["http://localhost:9997/v3/paths/list"]
  method = "GET"
  timeout = "10s"
  data_format = "json"
  name_override = "mediamtx_paths"

3. 高可用部署

4. 安全最佳实践

• 使用HTTPS加密API通信
• 配置适当的访问控制策略
• 定期轮换认证凭证
• 监控和记录API访问日志

故障排除与调试

常见问题解决

1. API无法访问

   # 检查服务状态
   netstat -tlnp | grep 9997
   
   # 检查防火墙设置
   iptables -L -n
   

2. 认证失败

   # 验证认证配置
   curl -v -u user:pass http://localhost:9997/v3/paths/list
   

3. 性能问题

   # 监控API响应时间
   time curl http://localhost:9997/v3/paths/list > /dev/null
   

调试技巧

# 启用详细日志
logLevel: "debug"
logDestinations: ["stdout"]

# 使用API调试工具
curl -v -H "Authorization: Bearer token" http://localhost:9997/v3/paths/list

总结

MediaMTX控制API提供了强大而灵活的远程管理能力，使得媒体服务器的运维工作可以完全自动化。通过RESTful接口，开发者可以：

• 📊 实时监控服务器状态和性能指标
• ⚙️ 动态配置媒体路径和流设置
• 🔒 管理认证和访问控制
• 📹 控制录制和播放功能
• 🔧 集成到现有的监控和运维体系

掌握MediaMTX控制API的使用，将极大地提升媒体流服务的可靠性和可维护性，为构建高质量的流媒体平台奠定坚实基础。

---

下一步行动建议：

1. 在测试环境中实践API调用
2. 集成到现有的监控系统
3. 开发自动化运维脚本
4. 实施安全加固措施

通过本文的指导，您应该能够充分利用MediaMTX控制API的强大功能，构建高效、可靠的流媒体服务架构。

【免费下载链接】mediamtx Ready-to-use SRT / WebRTC / RTSP / RTMP / LL-HLS media server and media proxy that allows to read, publish, proxy and record video and audio streams. 项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx