企业官网建设流程全解析

rtsp-stream故障排除手册：常见问题与解决方案大全

【免费下载链接】rtsp-streamOut of box solution for RTSP - HLS live stream transcoding. Makes RTSP easy to play in browsers.项目地址: https://gitcode.com/gh_mirrors/rt/rtsp-stream

rtsp-stream是一款开箱即用的RTSP-HLS直播流转码解决方案，能够轻松实现在浏览器中播放RTSP流。本手册将帮助您快速定位并解决使用过程中可能遇到的各类常见问题，让您的流媒体服务稳定运行。

📋 目录

• 连接与播放问题
• 转码服务异常
• 配置相关错误
• 认证与权限问题
• 日志分析指南

连接与播放问题

无法访问直播流

症状：浏览器中显示无法加载或404错误。

解决方案：

1. 检查RTSP源地址是否正确，确保格式为rtsp://username:password@ip:port/path
2. 确认服务是否正常运行：ps aux | grep rtsp-stream
3. 验证端口是否开放：netstat -tuln | grep 8080（默认端口为8080，可在core/config/config.go中修改）

视频加载缓慢或卡顿

症状：视频播放断断续续，缓冲时间过长。

解决方案：

1. 检查网络带宽，确保服务器上行带宽足够
2. 调整转码参数，降低视频质量或分辨率
3. 清理临时文件：默认存储目录为./videos（可在core/config/config.go的StoreDir配置修改）

rtsp-stream典型播放界面展示，正常情况下视频应流畅播放

转码服务异常

转码进程意外终止

症状：流突然中断，日志中出现stream stopped信息。

解决方案：

1. 检查是否达到core/config/config.go中配置的BlacklistLimit（默认25次错误后自动拉黑）
2. 查看转码日志：默认路径为/var/log/rtsp-stream（可通过PROCESS_LOGGING_DIR环境变量修改）
3. 检查系统资源：top命令查看CPU和内存使用情况

音频无法播放

症状：视频正常但没有声音。

解决方案：

1. 确认音频转码功能已启用：检查core/config/config.go中的Audio配置（默认开启）
2. 验证源RTSP流是否包含音频轨道
3. 尝试重启转码服务：POST /stop后再POST /start

配置相关错误

配置文件加载失败

症状：服务启动失败，日志中出现error reading rtsp-stream.yml。

解决方案：

1. 检查配置文件格式是否正确（YAML格式）
2. 确保配置文件位于正确路径：项目根目录下的rtsp-stream.yml
3. 验证配置项是否符合core/config/config.go中定义的结构

端口冲突问题

症状：服务启动失败，提示address already in use。

解决方案：

1. 修改默认端口：通过环境变量PORT设置或修改core/config/config.go中的Port默认值
2. 查找并终止占用端口的进程：lsof -i :8080

认证与权限问题

API请求被拒绝（403 Forbidden）

症状：调用API接口时返回403错误。

解决方案：

1. 检查JWT认证是否启用：core/config/config.go中的JWTEnabled配置
2. 验证请求头中的Authorization字段是否正确
3. 检查端点权限配置：core/controller.go中的isAuthenticated函数定义了各端点的权限验证逻辑

无法启动受保护的流

症状：调用/start接口失败，提示权限不足。

解决方案：

1. 检查rtsp-stream.yml中对应端点的secret配置
2. 确保JWT令牌中包含正确的secret声明
3. 临时测试可关闭认证：设置环境变量AUTH_JWT_ENABLED=false

日志分析指南

启用详细日志

通过修改core/config/config.go中的以下配置开启详细日志：

Debug bool `envconfig:"DEBUG" default:"false"` // 设置为true启用调试模式

或启动时设置环境变量：DEBUG=true ./rtsp-stream

常见日志错误解读

• Invalid URI：RTSP源地址格式错误
• Timeout error：转码进程启动超时，可能是源地址不可达
• blacklist：流地址被临时封禁，检查源是否稳定
• CORS：跨域访问问题，需在core/config/config.go中配置CORS选项

获取帮助

如果遇到本手册未涵盖的问题，可参考项目文档：

• API文档
• 配置指南
• 贡献指南
• 调试指南

快速部署检查清单

1. ✅ 确认RTSP源可访问
2. ✅ 检查端口占用情况
3. ✅ 验证配置文件格式
4. ✅ 设置适当的日志级别
5. ✅ 测试基本API功能：POST /start和GET /list

通过以上步骤，大多数常见问题都能得到快速解决。如问题持续存在，请收集详细日志信息并寻求社区支持。

【免费下载链接】rtsp-streamOut of box solution for RTSP - HLS live stream transcoding. Makes RTSP easy to play in browsers.项目地址: https://gitcode.com/gh_mirrors/rt/rtsp-stream