OPC/mediamtx

Table of Contents

故障排查

管理页无法访问
返回 401 或 403
登录页反复返回或无法进入管理页
添加 RTSP 后离线
页面能打开但视频不播放
Wiki 同步失败

故障排查

管理页无法访问

确认 api: true。
确认 apiAddress 的监听地址和端口。
查看启动日志是否显示 API listener。
确认请求路径为实现约定的 /admin/。

返回 401 或 403

检查 authInternalUsers 是否为管理员配置 action: api。
局域网访问必须使用命名管理员；删除 localhost 匿名 action: api 权限，避免绕过登录页。
不要为了排错永久开放匿名写权限。

登录页反复返回或无法进入管理页

确认账号在 authInternalUsers 中具有 action: api，并检查用户名和密码是否匹配。
清除当前标签页后会话自动失效；重新打开页面需要再次登录。
收到 401 时页面会清除 sessionStorage 中的 Authorization 并返回登录状态。
HTTP Basic 在 HTTP 下不加密；只允许可信局域网使用，不配置公网/NAT 端口映射，后续优先增加 HTTPS。
不在日志、截图、工单或 Wiki 中粘贴账号、密码、Authorization 或完整源地址。

添加 RTSP 后离线

先用 VLC/FFmpeg 直接验证上游 RTSP URL。
检查用户名、密码中的特殊字符是否已 URL 编码。
尝试 rtspTransport: tcp。
查看 MediaMTX 日志中的具体路径和源错误，不在工单粘贴含凭据的完整 URL。

页面能打开但视频不播放

WebRTC 检查 :8889 和媒体 UDP :8189。
HLS 检查 :8888/{path}。
检查浏览器是否支持源编码；H.265 和带 B 帧 H.264 可能存在兼容问题。
用 VLC 读取 rtsp://host:8554/{path} 区分源问题和浏览器问题。

Wiki 同步失败

确认 GITEA_TOKEN 只通过环境提供。
确认 wiki-docs.json 指向 OPC/mediamtx。
本地镜像存在未提交改动时先确认来源，工具应停止而不是覆盖。