架构概览

┌─────────────┐      RTSP       ┌──────────────┐     WebRTC/WHEP     ┌─────────────┐
│  RTSP 摄像头  │ ─────────────→  │   MediaMTX   │ ──────────────────→ │   Browser   │
│ (海康/大华等) │                 │  (媒体服务器)  │                     │  (WebRTC)   │
└─────────────┘                 └──────────────┘                     └─────────────┘

MediaMTX 负责从摄像头拉取 RTSP 流，并转换为 WebRTC 协议通过 WHEP（WebRTC-HTTP Egress Protocol）提供给浏览器播放。

---

一、下载 MediaMTX

Windows

1. 访问 https://github.com/bluenviron/mediamtx/releases
2. 下载最新版本的 mediamtx_vX.X.X_windows_amd64.zip
3. 解压到目标目录，如 C:\mediamtx\

Linux (x86_64)

wget https://github.com/bluenviron/mediamtx/releases/download/v1.12.0/mediamtx_v1.12.0_linux_amd64.tar.gz
tar -xzf mediamtx_v1.12.0_linux_amd64.tar.gz -C /opt/mediamtx/
cd /opt/mediamtx/

Docker（推荐生产环境）

# Linux
docker run -d \
  --name mediamtx \
  --restart unless-stopped \
  -p 8889:8889 \
  -p 8189:8189/udp \
  -p 9997:9997 \
  -v /data/mediamtx/mediamtx.yml:/mediamtx.yml:ro \
  -v /data/mediamtx/recordings:/recordings \
  bluenviron/mediamtx:latest \
  /mediamtx.yml


# Git bash: MSYS_NO_PATHCONV make relative path work
MSYS_NO_PATHCONV=1 docker run -d \
  --name mediamtx \
  --restart unless-stopped \
  -p 8889:8889 \
  -p 8189:8189/udp \
  -p 9997:9997 \
  -v "$(pwd)/mediamtx.yml:/mediamtx.yml" \
  -v /c/data/mediamtx/recordings:/recordings \
  bluenviron/mediamtx:latest \
  /mediamtx.yml

---

二、配置文件说明

配置文件位于 devops/mediamtx/mediamtx.yml，关键参数说明如下：

2.1 网络端口

2.2 WebRTC 核心参数

2.3 路径（Path）配置

paths:
  camera:                                          # 路径名，访问地址: /camera
    source: rtsp://admin:password@192.168.1.101:554/Streaming/Channels/102  # RTSP 源
    sourceOnDemand: yes                            # 按需拉流（推荐）
    sourceOnDemandStartTimeout: 10s                # 拉流超时
    sourceOnDemandCloseAfter: 10s                  # 无客户端时延迟关闭

2.4 RTSP URL 格式参考

注意： 密码中的特殊字符需要 URL 编码，如 @ → %40

---

三、启动 MediaMTX

方式 1：直接运行（Windows / Linux）

# 在 mediamtx.yml 所在目录下执行
./mediamtx

方式 2：指定配置文件

./mediamtx /path/to/mediamtx.yml

方式 3：Docker

docker run -d \
  --name mediamtx \
  --restart unless-stopped \
  --network host \
  -v $(pwd)/mediamtx.yml:/mediamtx.yml \
  bluenviron/mediamtx:latest

方式 4：Linux systemd 服务（生产推荐）

sudo tee /etc/systemd/system/mediamtx.service << 'EOF'
[Unit]
Description=MediaMTX Media Server
After=network.target

[Service]
Type=simple
ExecStart=/opt/mediamtx/mediamtx /opt/mediamtx/mediamtx.yml
Restart=always
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable mediamtx
sudo systemctl start mediamtx
sudo systemctl status mediamtx

启动成功后，日志显示如下：

2024/01/01 12:00:00 INF MediaMTX v1.12.0
2024/01/01 12:00:00 INF [RTSP] listener opened on :8554
2024/01/01 12:00:00 INF [WebRTC] listener opened on :8889

---

四、验证 MediaMTX 是否正常工作

4.1 检查 WebRTC 端点

# 查看是否有 WHEP 端点
curl -v http://localhost:8889/camera/whep

返回 405 Method Not Allowed 是正常的（需要 POST 请求）。

4.2 检查 RTSP 源状态

访问 API 端点（如果开启了 api: yes）：

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

4.3 查看日志

观察日志确认 RTSP 源连接成功：

INF [path camera] [rtsp source] started

---

五、浏览器端访问

5.1 启动 Node.js 前端服务

cd package/video
node server-mtx.js

5.2 在浏览器中打开

http://localhost:3003

5.3 页面说明

• 页面通过 WHEP 协议（WebRTC-HTTP Egress Protocol）直接从 MediaMTX 获取 WebRTC 流
• 无需插件、无需转码，浏览器原生 WebRTC 支持
• 延迟通常 200ms - 1s

---

六、常见问题排查

Q1: 浏览器无法播放，控制台报错

• 检查 MediaMTX 是否启动： curl http://localhost:8889/camera/whep
• 检查 RTSP 源是否可用： 用 VLC 打开 RTSP 地址测试
• 检查防火墙： UDP 端口 58000-58100 是否放行
• 检查 webrtcICEHostNAT1To1IPs： 必须配置为浏览器能访问到的 IP，本地测试用 127.0.0.1，局域网用本机 LAN IP

Q2: 延迟很高

• 确保浏览器和 MediaMTX 在同一局域网内
• 检查摄像头编码参数（H.264 baseline 延迟更低）
• 配置中已打开 webrtcICELite: yes，这对低延迟有帮助

Q3: 多路摄像头如何配置？

在 paths 下添加多个路径即可：

paths:
  camera1:
    source: rtsp://admin:pass@192.168.1.101:554/Streaming/Channels/102
    sourceOnDemand: yes
    sourceOnDemandStartTimeout: 10s
    sourceOnDemandCloseAfter: 10s
  camera2:
    source: rtsp://admin:pass@192.168.1.102:554/Streaming/Channels/101
    sourceOnDemand: yes
    sourceOnDemandStartTimeout: 10s
    sourceOnDemandCloseAfter: 10s

浏览器端访问 /camera1/whep 和 /camera2/whep。

Q4: 外网访问怎么配置？

1. 修改 webrtcICEHostNAT1To1IPs 为公网 IP
2. 确保防火墙放行端口：8889（HTTP）、58000-58100（UDP）
3. 配置 STUN 服务器：

webrtcSTUNServers:
  - stun:stun.l.google.com:19302

Q5: 支持哪些浏览器？

• Chrome / Edge 80+
• Firefox 80+
• Safari 14+（部分版本有兼容性问题，建议用 Chrome）

---

七、性能参考