在嵌入式 Linux 摄像头上跑 WebRTC：metaRTC 8.0 的 8 个坑与解法

摄像头产品想把延迟从 RTSP 的 1~5 秒压到亚秒级，WebRTC 绕不开，而 libwebrtc 在嵌入式设备上基本没法用，实际可选的开源方案就是 metaRTC。这篇文章是把它用到商用摄像头上的完整复盘：为什么选它，裸库和"能上生产"之间差了什么，8 个真实踩过的坑和解法代码，以及我们自己写的那层封装。这套封装连同整套固件来自我们开源的项目 NeuroCast，文中代码在仓库里都能找到完整出处，地址在文末。

---

一、先说背景：设备端跑 WebRTC 到底难在哪

我们的场景很典型：一颗 ARM 嵌入式 Linux 芯片（百 MB 级内存），摄像头采集出 H.264 码流，要求用户用浏览器打开页面就能看实时画面，延迟亚秒级，不支持任何插件。

这个需求用 RTSP 做不到（浏览器不认 RTSP），用 RTMP 延迟太高（3~5 秒起），转码方案（服务器转 WebRTC）又吃带宽成本。所以设备端直接说 WebRTC 是唯一的路。

但在嵌入式设备上，把 WebRTC 真正跑起来是另一回事。

难点有三：

1. libwebrtc 太重。Google 官方实现静态链接出来动辄 20~30MB，我们的设备闪存和内存都有限；而且它是 C++ 写的，API 每个版本都在变，交叉编译一次能折腾一周。
2. 嵌入式 SoC 没有 x86 那么好的生态。很多芯片 SDK 里没有现成的 WebRTC 组件，只能自己集成。
3. 设备端场景特殊。设备在 NAT 后面、4G 网络开机慢、没有 GPU 转码能力、内存按 MB 算------这些约束 PC 端的 WebRTC 方案都替你想好了，嵌入式端全要自己扛。

二、选型：三条路，我们为什么选 metaRTC

方案	体积	语言	许可证	嵌入式友好度
libwebrtc	20~30MB+	C++	BSD（但构建体系封闭）	差：交叉编译痛苦，API 不稳定
GStreamer webrtcbin	依赖全家桶	C	LGPL	中：功能全但依赖重，裁剪麻烦
metaRTC 8.0	轻量（MB 级以下）	纯 C	MIT	好：轻量、可裁剪、MIT 商用无忧

metaRTC（GitHub: metartc/metaRTC）是国人维护的嵌入式 WebRTC 实现，纯 C 写的，支持 Full-ICE、STUN/TURN、DTLS-SRTP、WHIP/WHEP，MIT 许可证对商用友好。

它最大的代价是文档少，示例代码和真实工程之间隔着大量坑。它的 demo 信令是手工拼 JSON 字符串，放到真实工程里（规范 JSON 库、浏览器标准 WebRTC API 对接）就处处对不上。

我们不是纸上评估，是直接拿它做了产品。下面 8 个坑，就是把 metaRTC 8.0 从"demo 能跑"推进到"商用产品量产"的路上一个一个踩出来的。整套方案来自我们开源的摄像头固件项目 NeuroCast，文中代码全部出自它的封装层。

三、我们的整体架构（先交代上下文，坑才有参照）

先看设备端在 NeuroCast 里的角色设计：

• P2P 模式 （单人观看）：设备做 answer 方，浏览器做 offer 方，SDP 和 ICE 候选通过 MQTT 交换
• SFU 模式 （多人观看 / P2P 打不通兜底）：设备做 offer 方，通过 WHIP 协议把流推到 SRS 服务器，浏览器用 WHEP 拉流

浏览器 ──MQTT(offer/answer/candidate)──► 设备（answer 方，Full-ICE）
浏览器 ◄══════ WebRTC P2P 直连（H.264）══════► 设备

设备 ──WHIP(HTTP 信令)──► SRS ──WHEP──► 多个浏览器

两种模式共用一条帧发送管线：相机编码出的 Annex-B 裸流进环形队列，发送线程取帧交给 metaRTC 的 Pacer 打包发出。

坑 1：浏览器报 "Expect line: v=" ------ SDP 被双重转义了

现象 ：answer 发到浏览器，调用 setRemoteDescription 直接抛异常，报 Expect line: v=，意思是浏览器拿到的 SDP "不是一个合法的多行文本"。

原因 ：metaRTC 开启 enableSdpCandidate 后，生成 answer 时会把换行符 CRLF 预先转义成字面文本 \r\n（四个字符） ------这是为了配合它自家 demo 里手工拼 JSON 信令的做法。而我们的工程用 cJSON 生成信令消息，cJSON 会再做一次规范转义。两次转义叠加，浏览器收到的 SDP 里所有换行都变成了字面的 \r\n 字符串，整个 SDP 被"看"成一行。

解法 ：外发给浏览器的副本要把 \r\n 字面文本还原成真正的回车换行：

/* metaRTC 生成的 answer 里换行是字面 "\r\n" 四个字符（它 demo 手工拼 JSON 用），
 * 我们经 cJSON 规范转义后不能重复转义，外发前还原成真正的 CRLF */
size_t escPos = 0;
while ((escPos = answerSdp.find("\\r\\n", escPos)) != std::string::npos) {
    answerSdp.replace(escPos, 4, "\r\n");
    escPos += 2;
}

更坑的地方 ：setLocalDescription 还必须用未还原的原始缓冲，metaRTC 内部认的是它自己的转义格式。也就是说同一份 answer 要维护两个版本：给 metaRTC 的、给浏览器的。我们实测只有"外发副本还原、本地调用不动"这一种组合是通的。

坑 2：DTLS 握手失败 ------ isControlled 必须在 setRemote 之前设置

现象：信令全部正常收发，ICE 连通性检查也过了，但 DTLS 握手阶段反复失败，视频始终出不来。

原因 ：设备是 answer 方，在 DTLS 握手里应该扮演 passive 角色（等对方先发 ClientHello）。metaRTC 里这个角色由 isControlled 标志决定，而且 setRemoteDescription 执行时就会读这个标志来定 DTLS 角色，并跳过播放初始化路径。

关键在于时序：createAnswer 内部虽然也会设置这个标志，但那已经发生在 setRemoteDescription 之后，来不及了。

解法：

peerInfo.iceMode = YangIceModeFull;        /* Full-ICE，gather 线程真实执行 */
peerInfo.rtc.enableSdpCandidate = yangtrue; /* answer 内联 host 候选 */
peerInfo.rtc.isControlled = yangtrue;       /* 必须在 setRemoteDescription 之前！ */

m_conn = new YangPeerConnection8(&peerInfo, ...);
/* ... addTrack / addTransceiver ... */
m_conn->setRemoteDescription(offer);   /* 此刻读取 isControlled 决定 DTLS 角色 */
m_conn->createAnswer(answerBuf);

这类"标志生效时序"的坑在 metaRTC 里不止一处。排查的土办法：凡设置在 PeerConnection 上的标志，都默认它在创建后第一次调用方法时就被读取，宁可早设不要晚设。

坑 3：4G 网络下 TURN 打不通 ------ Allocate 等待窗口默认只有 1 秒

现象：WiFi 环境下 P2P 一切正常；换成 4G 模块的设备，凡是要走 TURN 中继的场景，连接大概率超时。

原因：TURN 的 Allocate 请求要走完设备 → CGNAT → TURN 服务器的完整往返。metaRTC 默认的 Allocate 等待窗口是 1000ms（内部按 50 次 × 20ms 轮询折算）。家用 WiFi 一跳 RTT 几十毫秒，1 秒够用；但 4G 链路 RTT 经常 100~300ms，再叠加基站调度抖动，1 秒窗口余量严重不足。

解法：TURN 模式下把等待窗口放宽到 5 秒。成功时循环会提前退出，所以放宽不会拖慢正常场景：

if (iceType == 2) {   /* TURN 模式 */
    peerInfo.rtc.maxTurnWaitTime = 5000;   /* 默认 1000ms，4G 下不够 */
}

经验：凡是带"网络超时"字样的默认值，都按最差网络环境（4G 弱信号）重新评估一遍，而不是按开发时的 WiFi 环境想当然。

坑 4：设备刚开机 P2P 必失败 ------ DNS 还没就绪

现象：4G 设备上电后头一两分钟内发起的观看请求全部失败，之后恢复正常，稳定复现。

原因：ICE 服务器地址配的是域名。4G 模块拨号注册网络需要时间，开机初期 DNS 解析失败，STUN/TURN 配置等于没配，全候选模式直接废掉。

解法：把 ICE 域名解析从"启动时做一次"改成"每次建会话都做"，并且解析失败不报错、降级为仅 host 候选，这样同局域网的观看至少还能直连：

/* 每次建会话都重新解析：4G 开机网络未必就绪 */
if (iceType > 0) {
    if (resolveHostIPv4(cfg.ice.host, iceIp)) {
        /* 正常，走 STUN/TURN */
    } else {
        /* 解析失败：降级仅 host 候选，局域网直连不受影响 */
        NC_LOGW("ice server resolve failed: %s, degrade to Host-only", cfg.ice.host);
        iceType = 0;
    }
}

教训：设备"开机后的第一分钟"要当成独立的测试场景，DNS、NTP、MQTT 重连都得按"网络随时可能不存在"来设计。

坑 5：浏览器候选收不到 ------ addIceCandidate 的格式不是裸 SDP

现象 ：设备端日志显示浏览器发来的 ICE 候选都收到了，但 addIceCandidate 全部返回失败，连接永远停在 checking。

原因 ：metaRTC 的 addIceCandidate 接口要求的不是标准 SDP 候选字符串，而是一层它自己的 JSON 包装：{"candidate": "candidate:1 1 udp ..."}。前端按标准 WebRTC API 生成的是裸 SDP 字符串，直接传进去当然失败。

解法：信令层收到的裸候选，包一层 JSON 再交给 metaRTC：

/* metaRTC 要求 JSON 格式，前端发来的是裸 SDP 字符串，包一层 */
std::string json = "{\"candidate\":\"" + candidate + "\"}";
m_conn->addIceCandidate((char*)json.c_str());

反过来，metaRTC 回调吐给我们的本地候选也是它自己的格式，同样要在信令层做适配后再发 MQTT。把 metaRTC 当成一个格式和标准 WebRTC 有出入的黑盒来对待，格式适配集中在信令层做掉，别让格式假设散落在业务代码里。

坑 6：用户关掉页面，设备线程死锁 ------ 回调线程里不能"顺便"清理会话

现象：测试时反复开关浏览器页面，偶发设备端卡死，看门狗复位。

原因 ：metaRTC 检测到对端关闭时会回调 sslCloseAlert，这个回调运行在 metaRTC 自己的接收线程里。如果在这个回调里直接调 stopSession()，它会 join 发送线程、delete 连接对象，等于在 metaRTC 的线程里销毁 metaRTC 正在使用的对象，标准作死。

解法：回调里只置标志，清理动作交给服务线程在安全上下文里做：

void P2PSession::sslCloseAlert(int32_t uid) {
    /* 运行在 metaRTC 接收线程：直接 stopSession 会 join 发送线程并销毁
     * 连接对象，存在自锁/自毁风险。只置标志，由服务线程轮询处理。 */
    m_peer_closed.store(true);
}

/* 服务线程循环里 */
if (m_session.isPeerClosed()) {
    m_session.stopSession();   /* 安全上下文：不持有 metaRTC 内部锁 */
}

教训：第三方库的回调线程是它的地盘，回调里只做"记一件事"，资源操作一律搬到自己的线程。随机死锁这类问题，多半就是这么来的。

坑 7：画面轻微抖动 / 时间轴漂移 ------ 时间戳单位别预转换

现象：P2P 能出图，但画面节奏不对，有周期性的小抖动；抓包看 RTP 时间戳增长不均匀。

原因：metaRTC 的 Pacer 拿到帧后自己把 PTS 换算成 90kHz 时钟（微秒 × 9 ÷ 100）。我们最初按直觉"先把硬件毫秒时间戳转成 90kHz 再喂进去"，结果 Pacer 又换算了一遍，时间轴彻底错乱。

解法 ：喂给 Pacer 的 PTS 单位是微秒，其他什么都不要做。另外会话重启时必须复位时间基准，否则上一场会的陈旧时间戳会污染新会话：

/* 每次会话启动，复位时间基准（幂等保障：不受旧会话残留影响） */
m_first_hw_ts = 0;

void FrameSender::pushFrame(const uint8_t* data, int len,
                            uint64_t timestampMs, bool keyframe) {
    if (m_first_hw_ts == 0) m_first_hw_ts = timestampMs;
    uint64_t hw_ts_ms = timestampMs - m_first_hw_ts;   /* 相对毫秒 */
    /* item 是队列槽位（入队代码省略），这里只看时间戳字段 */
    item.pts = (int64_t)hw_ts_ms * 1000;               /* 转微秒。到此为止，
                                                          90kHz 换算由 Pacer 内部做，
                                                          禁止在这里预转换 */
}

经验：接第三方多媒体库，先把它所有"数值字段"的单位列一张表（毫秒/微秒/90kHz tick/字节/千比特），对照它的源码确认换算点，再动手写代码。

坑 8：两种推流模式要共存 ------ 端口隔离是前置设计

问题：产品要求 P2P（单人直连）和 SFU（WHIP 推 SRS）两种模式随时切换、长期共存。如果两条链路共用同一个本地 UDP 端口，先起的会话占住端口，后起的绑定就会失败；UDP 五元组一旦冲突，还会出现收包串流这类极难排查的问题。

设计：给两条链路分配固定的隔离端口，做成配置项：

• P2P 会话：17100
• WHIP 推流：17000

avinfo.rtc.rtcLocalPort = cfg.rtcLocalPort;   /* P2P=17100 / WHIP=17000 */

还有一个隐性好处：WHIP 路径在 metaRTC 内部走的是 ICE-Lite（对接 SRS 这类 SFU 的标准做法），P2P 路径走 Full-ICE，两条路径的会话状态完全独立，排查问题时互不污染。

四、裸 metaRTC 离"能上生产"差多远

前面 8 个坑解决的是"正确使用"的问题。但复盘整个项目会发现：metaRTC 提供的是 WebRTC 协议栈本身（ICE / DTLS / SRTP / WHIP），把它用到商用产品上，缺的东西比坑多得多。这一半工作，是我们自己的封装层补齐的（源码在 github.com/neurocast-iot/firmware 的 libs/rtc/ 目录，可直接查看）：

裸 metaRTC 的状态	商用产品需要的	我们的封装层实现
demo 级信令：手工拼 JSON 字符串	生产级可靠信令	MQTT 信令层：六类消息、会话状态机、bye 原因码、心跳保活
没有帧发送管线	编码帧稳定喂给协议栈	FrameSender：定长环形队列、队列满丢帧计数（绝不阻塞采集线程）、会话重启自动复位时间基准
没有线程安全约定（回调线程里清理会话 = 死锁，见坑 6）	多线程下可预期的生命周期	回调只置标志，服务线程在安全上下文清理
没有 P2P / SFU 模式概念	两种模式随时切换共存	双模式统一封装、端口隔离、模式冲突仲裁、推流 token 校验
多处格式与标准 WebRTC 有出入（坑 1、5）	浏览器端无感	信令层集中适配，业务代码零感知
只能在板子上调试	开发效率	与平台抽象层配合，x86 上跑通全流程单元测试

说到底，metaRTC 解决的是"协议通不通"，封装层解决的是"产品能不能卖"。这套封装已经在真实商用产品上量产验证过，也是我们把它放进开源仓库的原因：代码和文章里的坑基本一一对应，不想重踩的直接看它。

五、串起来：最终跑通的完整链路

浏览器                     MQTT broker                设备 (mediad)
  │ offer ───────────────────►│──────────────────────►│
  │                           │                       │ P2PSession (metaRTC)
  │ ◄──────────────────────── │◄───── answer ─────────│  · setRemote(offer)
  │ candidate ───────────────►│──────────────────────►│  · Full-ICE gather
  │ ◄──────────────────────── │◄───── candidate ──────│  · DTLS-SRTP
  │═════════════ P2P 直连 · 亚秒延迟 · H.264 ═══════════│
  │                                                  FrameSender
  │                                     相机 VENC ──► 环形队列 ──► Pacer ──► on_video

最后是几个经过量产验证的设计决策，写出来供参考：

1. 设备只做 answer 方（P2P），复杂度留在浏览器端，设备端逻辑最简单
2. 模式切换由前端控制 ：设备超时只发带原因码的 bye，切 SFU 的决定由前端做------设备逻辑可预测，好测试
3. 帧管线单线程化：采集线程只负责入队（满了丢帧并计数，绝不阻塞采集），发送线程独占出队和 metaRTC 调用
4. 回调线程零资源操作：见坑 6
5. 信令层集中做格式适配：metaRTC 的各种非标准格式在信令层一处消化，见坑 1、5

六、metaRTC 还值不值得选？

踩完 8 个坑，给个客观结论：

适合你，如果：嵌入式 Linux、内存紧张（百 MB 级）、需要 P2P + SFU 双模式、能接受读它的源码来排问题、MIT 许可证对你重要。

不适合，如果：需要 Simulcast / 复杂的编解码能力协商 / 大规模多方通话------这些 libwebrtc 生态更成熟；或者你的团队完全没有读 C 源码排问题的准备。

metaRTC 帮我们把 WebRTC 塞进了百 MB 内存的设备里，这笔账怎么算都值。坑虽然多，但踩一次就够了：修掉，写进注释和测试，不会再犯。另外有个事实值得强调：我们从头到尾没有 fork metaRTC，没有改它一行源码，全部适配都消化在自己的封装层里，metaRTC 出新版随时可以升级。这是把第三方库用进产品的正确姿势，也是上一节那些封装代码的价值所在。

---

本文方案来自开源项目 NeuroCast------嵌入式 IP 摄像头全栈固件（WebRTC 推流、设备管理、OTA、平台抽象层），Apache-2.0 开源，x86 开发机可直接跑通全流程与单元测试；本文的 WebRTC 封装层（信令 / 帧管线 / 双模式管理）源码在仓库 libs/rtc/ 目录。下一篇：《换颗芯片不改一行上层代码》：摄像头固件的平台抽象层设计，讲我们怎么做到应用层零厂商依赖、换芯片只加目录不改代码。