7天解决99%的MediaMTX故障：运维工程师的实战排查指南

【免费下载链接】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

作为一款支持SRT/WebRTC/RTSP/RTMP/LL-HLS的媒体服务器，MediaMTX在音视频传输场景中被广泛应用。但运维人员常常面临连接失败、直播卡顿、权限拒绝等问题，本文将通过7个典型故障案例，提供从日志分析到性能调优的全流程解决方案。

故障排查准备工具

在开始排查前，请确保已掌握以下工具和配置文件位置：

• 核心配置文件：mediamtx.yml（位于项目根目录）
• 性能监控：内置pprof性能分析器（需在配置中启用）
• 日志文件：默认输出到stdout，可通过配置重定向至文件
• 官方文档：完整配置说明 | 认证指南

案例1：RTSP流无法发布（权限被拒绝）

故障现象

使用ffmpeg -i input.mp4 -f rtsp rtsp://localhost:8554/mystream发布流时，返回401 Unauthorized错误。

排查步骤

1. 检查认证配置
   打开mediamtx.yml，确认authInternalUsers配置是否正确：

   authInternalUsers:
     - user: admin
       pass: sha256:j1tsRqDEw9xvq/D7/9tMx6Jh/jMhk3UfjwIB2f1zgMo=  # 示例哈希值
       permissions:
         - action: publish
           path: .*  # 允许发布所有路径
   

   密码哈希生成方法：echo -n "password" | openssl dgst -binary -sha256 | openssl base64

2. 验证认证方式
   若使用外部HTTP认证服务，检查authHTTPAddress配置：

   authMethod: http
   authHTTPAddress: http://auth-server:8080/verify  # 确保服务可访问
   

3. 测试命令修正
   添加认证信息后重试：

   ffmpeg -i input.mp4 -f rtsp rtsp://admin:password@localhost:8554/mystream
   

案例2：WebRTC播放延迟超过3秒

故障现象

通过WebRTC播放时，视频延迟逐渐增加至3秒以上，音频同步错乱。

排查步骤

1. 启用性能监控
   在mediamtx.yml中开启pprof：

   pprof: yes  # 启用性能分析
   

   重启服务后执行CPU分析：

   go tool pprof -text http://localhost:9999/debug/pprof/profile?seconds=15
   

   典型输出将显示占用CPU最高的函数，如github.com/bluenviron/gortsplib/v4.(*serverUDPListener).run

2. 优化WebRTC配置
   修改WebRTC相关参数，减少缓冲区大小：

   webrtc:
     jitterBufferDelay: 200ms  # 降低抖动缓冲延迟
     maxBitrate: 2000000       # 限制最大比特率
   

3. 网络检查
   使用tcptrace分析RTCP报文：

   tcptrace -i any port 8554  # 检查丢包率是否超过1%
   

案例3：Docker部署时端口映射冲突

故障现象

启动容器时提示bind: address already in use，但宿主机未显示端口占用。

解决方案

Docker Compose配置示例（避免端口冲突）：

version: '3'
services:
  mediamtx:
    image: bluenviron/mediamtx:latest
    ports:
      - "8554:8554/tcp"   # RTSP (TCP)
      - "8554:8554/udp"   # RTSP (UDP)
      - "8889:8889/tcp"   # WebRTC HTTP
      - "8890:8890/udp"   # SRT
    volumes:
      - ./mediamtx.yml:/mediamtx.yml  # 挂载自定义配置
    restart: unless-stopped

端口映射规则：Docker部署文档中定义了所有默认端口

案例4：录制文件碎片化严重

故障现象

启用录制功能后，生成大量10秒片段文件，占用过多inode资源。

优化配置

修改录制参数，调整分片大小：

pathDefaults:
  record: yes
  recordFormat: fmp4  # 使用MP4格式减少碎片化
  recordSegmentDuration: 30s  # 增加分片时长
  recordMaxSize: 100M  # 限制单个文件大小

录制文件默认保存路径：./recordings/{path name}/{timestamp}.mp4

案例5：HLS流在iOS设备无法播放

故障现象

桌面浏览器可正常播放HLS流，但iOS Safari提示"无法加载媒体"。

修复步骤

1. 检查CORS配置
   在mediamtx.yml中添加跨域支持：

   http:
     allowOrigin: "*"  # 生产环境建议指定具体域名
   

2. 验证LL-HLS配置
   确保启用低延迟模式：

   hls:
     lowLatency: yes  # 启用LL-HLS
     partDuration: 200ms  # 分段大小适配移动网络
     segmentDuration: 1s
   

性能优化最佳实践

系统资源调优

1. 文件描述符限制
   Linux系统需增加最大文件打开数：

   ulimit -n 65535  # 临时生效，需配置/etc/security/limits.conf永久生效
   

2. 内存分配优化
   对于高并发场景，调整Go运行时参数：

   GOGC=20 ./mediamtx  # 降低垃圾回收阈值，减少内存占用
   

监控指标关注

• CPU使用率：单个核心占用超过80%会导致丢包
• 内存增长：通过go tool pprof检查是否有内存泄漏
• 网络抖动：RTCP丢包率应控制在0.1%以内

故障自愈机制配置

通过钩子脚本实现故障自动恢复：

pathDefaults:
  runOnDemand: ffmpeg -i rtsp://camera:554/stream -c copy -f rtsp rtsp://localhost:%RTSP_PORT%/%MTX_PATH%
  runOnDemandRestart: yes  # 进程退出时自动重启
  runOnNotReady: curl http://alert-system:8080/stream-down?path=%MTX_PATH%  # 发送告警

总结与后续建议

1. 必做检查清单

   •  定期备份mediamtx.yml配置
   •  启用pprof监控关键指标
   •  配置日志轮转避免磁盘占满

2. 进阶学习资源

   • 性能调优指南
   • API控制接口
   • Docker部署最佳实践

下期预告：《MediaMTX集群部署：负载均衡与高可用方案》

若遇到本文未覆盖的故障，欢迎在项目Issues提交详细日志，获取社区支持。

【免费下载链接】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