FreeSWITCH proxy_media模式视频黑屏排障与修正指南

搞过FreeSWITCH视频呼叫的兄弟，应该都经历过这种场面：音频通话一切正常，但一进入proxy_media模式，对端要么黑屏，要么画面卡在某一帧，要么干脆只有声音没有图像。查了半天SIP信令，抓了一堆RTP包，最后发现问题往往不是网络，而是FreeSWITCH在处理视频SDP时埋下的雷。这篇文章把我这几年在proxy_media模式下排查和修正视频流问题的经验整理一遍，包含具体的定位思路、SDP比对方法、switch.conf.xml和dialplan里的修正参数，以及几个真实项目里踩过的坑。如果你想在FreeSWITCH上做视频呼叫落地，或者正在排查某个诡异的“只有音频没有视频”问题，这篇应该能帮你省下不少时间。

1. proxy_media模式下video到底代理了什么

很多刚接触FreeSWITCH的人会有一个误解，以为proxy_media就是“媒体复制一份给FreeSWITCH”，或者在FreeSWITCH上跑了什么视频编解码。其实不是。proxy_media更准确的叫法是“代理媒体模式”，它跟bypass、transparent一起，构成了FreeSWITCH处理媒体流的三种典型路径。要理解proxy_media下视频为什么出问题，首先得把这三种模式掰扯清楚。

1.1 先把bypass、transparent和proxy_media放在一起看

bypass_media应该是最直观的模式：SIP信令走FreeSWITCH，但RTP媒体直接在两端之间传，FreeSWITCH完全不碰媒体报文。这种模式开销最小，但问题也明显——FreeSWITCH看不到媒体状态，无法感知通话质量，也没法录音、转码、混音。对于纯粹的SIP中继转发场景，bypass很好用，但一旦涉及视频会议、呼叫录音、IVR接听等需要媒体介入的场景，bypass基本不适用。

transparent_media在国内文档里讨论得相对少一些。它会把RTP报文完整转发，并且尽可能不改变SDP里关于媒体格式的表述。这个模式看起来很“透明”，但说实话，在实际项目中它更多用于一些特殊网关对接场景，比如两端SDP差异特别大、但你又不想让FreeSWITCH转码的时候。

proxy_media则介于两者之间：FreeSWITCH保留对SDP的改写权，会把呼叫两侧的RTP媒体全部拉到自己这里再双向转发。这个过程里，FreeSWITCH不做编解码转换，也就是说它不在媒体层面对视频帧做任何“理解”或“重组”，只是作为一个高质量的信使，把A侧发来的RTP包转发给B侧，再把B侧的RTP包转发给A侧。

@@关键点在于，proxy_media模式下FreeSWITCH会重写SDP里的连接地址和媒体端口，但不会等重协商完成后才转发媒体。@@这既是它灵活的地方，也是视频流最容易出事的根因之一。

1.2 proxy_media实际做的小动作

拿一个最简单的视频呼叫场景举例。A侧终端发起呼叫，Invite里带了一个SDP，里面通常有音频m行和视频m行，分别是类似m=audio 40000 RTP/AVP 0 8 96和m=video 50000 RTP/AVP 97这样的描述。B侧终端返回200 OK，带的SDP可能视频负载类型是98而不是97。

如果是bypass_media，FreeSWITCH会在信令上做透传或简单改写，让两端各自知道对端的地址，然后让RTP自己跑。A说我的视频是97，B说我只收98，两边虽然有可能因为负载类型不一致而出问题，但至少FreeSWITCH不会“掺和”进来。

如果是proxy_media，FreeSWITCH会把自己两端的媒体地址分别填到A和B收到的SDP里。比如A收到的SDP里，音频连接地址变成FreeSWITCH的IP:端口X，视频连接地址变成FreeSWITCH的IP:端口Y；B那边也一样。然后FreeSWITCH在内部把A的音频流映射到B，A的视频流映射到B。

这个映射看起来很简单，但实际情况要复杂得多。FreeSWITCH在proxy_media下会为每个呼叫建立RTP会话，并且对这些RTP包做时间戳、序列号等层面的处理。更重要的是，视频RTP包通常有负载类型、SSRC、时间戳速率等一堆元信息，它们在SDP协商和实际RTP包之间必须保持匹配。一旦某个环节对不上，接收方就会把承载视频的RTP包判定为未知格式或无效格式，得到的自然就是黑屏、绿屏或定格画面。

我用一句话总结proxy_media模式下视频问题的本质：媒体包本身没有损坏，但两端对“这段媒体到底该怎么读”的理解不一致。

2. video流在proxy_media模式下最常见的故障现场

视频故障不像音频故障那么“有规律”，它的表现五花八门。但我在实际项目中统计下来，绝大多数proxy_media视频问题都逃不出下面三类。

2.1 只有音频没有视频

这类现象最常见，通常发生在A侧能听到B侧说话，B侧也能听到A侧说话，但视频画面完全黑屏，或者对方头像一直转圈、不渲染。

排障时如果只看音频，你会发现媒体通得很顺畅。问题往往出在视频方向的SDP协商结果上。常见原因包括：

• 视频编解码器在SDP中被协商成了某个负载类型，但实际媒体包使用的是另一个负载类型。
• B侧SDP里声明的视频编码格式比A侧多，FreeSWITCH做了“某种取舍”之后，A侧以为双方协商的是H.264，但B侧实际收到的却是VP8，而proxy_media又不会帮你做转码。
• 还有很多终端在SDP里声明了多个视频格式，比如H.264和H.265同时列出来，但FreeSWITCH只转发其中一个，另一侧又只会解码另一个。

这种情况下，信令上是看不到报错的，因为SIP本身是“成功”的。只有把两端的SDP摆在桌上逐行diff，才能发现问题。

2.2 视频能显示，但过几秒就卡死

另一个非常典型的现象是：接通之后前几秒画面正常，然后突然卡住，音频还继续走。过一会儿画面又恢复，然后又卡住。这种“间歇性定格”往往不是网络丢包，而是RTCP和RTP的时间戳对不上。

视频RTP包的时间戳单位通常是90000Hz，也就是说每秒钟时间戳会增加90000。但很多终端或网关在发送视频时，时间戳增量不是严格按照90000来算的。如果FreeSWITCH在proxy_media模式下启用了某些对时间戳的调整选项，而两端的时钟速率又有细微差异，就会导致接收端收到的时间戳跳动异常。表现就是解码器刚开始能出图，后续帧的timestamp乱跳，解码器直接把帧丢弃。

还有一种情况是RTCP反馈里的SR包所携带的RTP时间戳和实际RTP包时间戳基准不一致。这在视频会议里很常见：终端A发送RTP时基准是0，FreeSWITCH转发了一段时间后，B侧回RTCP SR，A侧发现RTCP里说的媒体时间跟自己的时间轴完全对不上，于是视频渲染线程直接罢工。

2.3 花屏、绿屏或者画面撕裂

花屏和绿屏通常意味着RTP包到了，但解码器把错误的负载解析成了视频帧。这在代理媒体模式下，大概率是负载类型（Payload Type）冲突。

比如说，A侧SDP里视频m行写的是rtpmap:98 H264/90000，B侧SDP里写的是rtpmap:98 VP8/90000。如果FreeSWITCH在转发时没有把A侧SDP里的98“翻译”成B侧认识的98对应的格式，B侧就会拿VP8的解码逻辑去解H.264的码流，结果自然就是满屏花绿。这种问题在跨越不同厂商终端对接时尤其多，尤其是那些SDP里同时带了一堆冗余rtpmap的终端。

3. 视频断流排障实录：我拿到一个问题怎么查

排障proxy_media视频问题，普通人可能第一反应是“查日志”。这没错，但FreeSWITCH日志默认级别下根本不会打印RTP层面的细节，所以要学会有步骤地抓包和看包，而不是在console里瞎翻。

3.1 先开SIP全量跟踪，把协商过程固定下来

我一般的操作顺序是：先打开SIP跟踪，确认呼叫建立时两侧的SDP到底长什么样。在FreeSWITCH里可以执行：

bash复制sofia global siptrace on

然后复现一次视频呼叫。呼叫结束后执行：

bash复制sofia global siptrace off

这样会在日志里留下整个INVITE、180、200 OK、ACK的完整SIP消息，包括SDP体。把这些SDP复制出来，分别保存成A侧SDP和B侧SDP。

这里有个经验：不要只看Freeswitch和A之间的SDP，也不要只看Freeswitch和B之间的SDP，你要对比的是A最终收到的SDP和B最终收到的SDP。 proxy_media模式下，出问题的往往不是某一侧跟FreeSWITCH的协商结果，而是两侧之间经过FreeSWITCH“翻译”后是否仍然能对得上。

3.2 用Wireshark按通话筛选RTP流

SIP SDP只是确定了“理论上的媒体格式”，实际RTP报文内容才是真相。建议在Wireshark里抓包，过滤条件可以这么写：

text复制(ip.addr == <对端IP>) && (rtp || rtcp)

把抓到的RTP包按SSRC归类。对于视频流，要重点看：

• RTP Payload Type是否与SDP一致。
• 视频SSRC是否在通话过程中发生切换（切换大概率导致花屏或黑屏）。
• 视频时间戳是否连续、是否出现大幅度突跳。
• 是否存在RTCP BYE报文，如果有，是谁在什么时间点发的。

很多时候，你在Wireshark里看到视频RTP包一直在跑，数量也没问题，但PT字段跟SDP里声明的PT完全不同。这种情况基本可以断定是代理转发或者SDP改写环节出了问题，而不是网络丢包。

3.3 用uuid_dump看FreeSWITCH当前会话的媒体状态

如果抓包不方便，可以在FreeSWITCH里用uuid_dump把当前呼叫的媒体状态拉出来看看：

bash复制uuid_dump <uuid>

这个命令会显示每个腿的SDP协商结果、媒体方向、RTP地址、负载类型等。重点看proxy_media两侧的RTP会话是否都处于“已激活”状态。

3.4 一个真实排障的简化复盘

我处理过一个案例，A公司视频话机呼叫B公司视频网关，音频正常，视频全黑。最初怀疑是B网关卡了视频编码，但单独用其他SIP话机点对点呼叫B完全正常。后来打开SIP Trace，把A侧收到B的200 OK SDP和B侧收到A的INVITE SDP对比，才发现A发给B的SDP里视频行只有H.264，但B回给A的SDP里视频行却有H.264、H.265、VP8三个编码。FreeSWITCH在proxy模式下转发媒体时，把A侧的视频RTP包保持H.264格式原样转发给B，B拿到的也是H.264的RTP包，理论上是能解码的。

问题出在B侧SDP里有一个rtcp-fb参数，声明了支持nack pli等反馈，而A侧SDP里没有这些反馈参数。B侧收到A的视频后，按照自己SDP里声明的能力，觉得A会支持RTCP NACK反馈，于是通过RTCP反馈让A重传丢掉的视频包。A侧压根不处理这个反馈，导致B侧在解码端持续等待重传帧，最终画面一直卡在I帧前。这类问题只有在代理媒体场景下才容易暴露，因为如果是bypass模式，A和B直接协商，终端自己知道对方能力，反而不会产生这种错位。

4. 修正方案：把两端SDP和RTP行为捏到能互相听懂

搞清楚proxy_media视频流问题的本质后，修正起来就有方向了。核心思路只有一个：让FreeSWITCH在代理转发时，不破坏两端本来能互相理解的信息。

4.1 从SDP协商入手，压缩视频编码范围

最粗暴但最有效的方式，是让FreeSWITCH在SDP协商阶段就把视频编码范围压缩成两端的公共交集。FreeSWITCH支持通过配置视频编码偏好来影响协商结果。

在vars.xml里，通常会看到如下配置：

xml复制<X-PRE-PROCESS cmd="set" data="video_codec_prefs=H264,VP8,VP9,H263,PASSTHROUGH"/>

这段配置的作用是告诉FreeSWITCH，在媒体协商时优先选择哪些视频编码。如果你的场景里对端终端只支持H.264，那建议把前面的优先级调整成：

xml复制<X-PRE-PROCESS cmd="set" data="video_codec_prefs=H264,PASSTHROUGH"/>

另一方面，如果对端网关在SDP里坑了一把，把两端本不统一的编码也列进去了，可以在呼叫路由时通过dialplan直接指定编解码字符串：

xml复制<action application="set" data="codec_string=H264:96,PCMU:0,PCMA:8"/>

这样FreeSWITCH在bridge时会基于这个codec_string去匹配对端，能有效避免“SDP里列了一堆，实际只发一种”的错位。

4.2 用时间戳修正参数消除画面卡死

对于前面提到的“视频能显示但几秒卡死”问题，重点检查FreeSWITCH的这三个参数：

xml复制<param name="rtp-rewrite-timestamps" value="true"/>
<param name="rtp-auto-adjust-timestamp-rate" value="true"/>
<param name="disable-rtp-auto-adjust" value="false"/>

rtp-rewrite-timestamps的作用是让FreeSWITCH在转发RTP时重新计算并统一时间戳基准。很多时候，终端A发出的视频时间戳不是从0开始的，或者初始时间戳非常大，经过FreeSWITCH转发给B时，B的时间戳判断逻辑会认为这个流异常。打开时间戳重写之后，FreeSWITCH会为标准间隔重新映射时间戳，视频解码器对时间轴的判断就正常了。

rtp-auto-adjust-timestamp-rate主要用于处理采样率变化的场景。音频常见的采样率有8000、16000、48000，视频一般是90000。如果你发现某个视频终端实际发包的时间戳速率不是90000，而是45000或180000，这个参数会在媒体流统计过程中自动调整速率，避免接收端解码时间轴错乱。

我在实际项目里一般会保持rtp-auto-adjust-timestamp-rate为true，但要注意，它并不是万能的。如果两端SDP里声明的编码时钟频率差异过大，单靠这个参数救不回来，还是得回到SDP层去修正。

4.3 控制对称RTP和NAT行为，减少视频端口错乱

proxy_media模式下，如果呼叫涉及NAT穿越或者对称RTP，常见的故障是视频RTP端口对不上。A侧发给FreeSWITCH的视频流是50000端口，FreeSWITCH转发给B侧后，B侧回复时却发到了FreeSWITCH的另一个端口，这个端口不是FreeSWITCH监听视频RTP的端口。结果就是视频方向上的RTP包到了FreeSWITCH后被丢弃。

排查这个问题时，可以检查如下配置：

xml复制<param name="apply-nat-acl" value="wan.auto"/>
<param name="aggressive-nat" value="true"/>

apply-nat-acl决定了FreeSWITCH对哪些来源地址启用NAT穿透处理。如果对端设备在NAT后面，而你没有把对应网段加入NAT ACL，FreeSWITCH可能不会对视频RTP流做端口映射修正。

另外要注意，很多终端支持对称RTP（symmetric RTP），也就是说它发送和接收RTP使用同一个端口。如果FreeSWITCH在跟它对接时，一侧用了A:50000转A:50000，另一侧却把媒体转发到B:50002，而B终端又只有50002端口在收视频流，那么即使SDP看起来没问题，视频也无法正常显示。遇到这种情况，最直接的修正方法是把B侧的RTP端口固定下来，或者要求终端关闭对称RTP特性。

4.4 实在救不了，就果断切bypass或中间转码

如果你已经排查了SDP、时间戳、端口，仍然无法解决视频问题，就要重新考虑策略了。在不需要FreeSWITCH做录音、混音、会议等强媒体处理时，完全可以切换到bypass_media模式。

在dialplan里可以这样设置：

xml复制<action application="set" data="bypass_media_after_bridge=true"/>

这个参数的作用是：在bridge建立后，FreeSWITCH尝试把后续媒体切换为bypass模式。切换成功后，A和B直接互通RTP，FreeSWITCH不再介入媒体转发。视频黑屏、花屏这类问题往往立刻消失。

但这里要提醒一句，bypass_media_after_bridge只对支持无缝切换的呼叫有效。如果呼叫里正在使用录音、会议桥、IVR等资源，媒体无法被释放，这个参数就不会生效。

如果必须保持proxy_media同时又不能在业务层面放弃媒体感知，那就只能老老实实让FreeSWITCH做一次转码。比如A侧只发H.264，B侧死活只接VP8，两端SDP取不了交集。这时在outbound呼叫侧指定bridge时加上视频转码参数，强制呼叫进入转码模式：

xml复制<action application="set" data="video_repair_enable=true"/>
<action application="bridge" data="sofia/external/1000@172.16.1.20"/>

video_repair_enable并不是FreeSWITCH官方标准变量，我这里只是为了示意“转码修复”的思路用到它，真正实施时请根据你使用的版本和模块能力去配置。但在架构层面，你要明白一个道理：proxy_media省的是编解码开销，如果省掉这些开销带来的问题比开销本身更麻烦，那不如直接转码。

5. 真实场景复盘与速查清单

理论说了一堆，我把几个代表性场景整理成速查形式的笔记，也分享一些长期积累的经验建议。这些场景我刻意隐去了具体厂商和项目名称，但问题表现、排障路径和修正参数都是可以直接参考复用的。

5.1 场景一：SIP话机呼叫视频会议系统，视频黑屏

问题现象：音频双向正常，视频黑屏，两端视频编码都设置为H.264。

排查过程：打开SIP Trace后对比SDP，发现会议系统返回的SDP里有a=imageattr、a=rtcp-fb等参数，话机侧SDP没有这些能力声明。话机收到对方带rtcp-fb的SDP后，本能地认为对方支持RTCP反馈，但对方实际没有启用相关的反馈处理，导致视频包在RTCP反馈环节被等待和超时拖住。

修正方法：在FreeSWITCH侧将其中一端SDP里的rtcp-fb参数过滤掉，或者用bypass_media_after_bridge=true跳过代理，让两端直接协商。经过调整后，视频恢复稳定。

5.2 场景二：视频网关出局呼叫只通音频

问题现象：FreeSWITCH通过网关对接运营商视频线路，出局呼叫后对端振铃但没视频。本端媒体配置和SDP都确认有视频行。

排查过程：抓包发现A侧INVITE只有音频SDP，FreeSWITCH虽然配置了视频编码，但Inbound呼叫的SDP里没有视频m行，导致bridge出局时也带不上视频。这个现象在“本端是SIP话机，出局目标是运营商网关”时很容易出现，因为话机在INVITE里发的是全量SDP，但FreeSWITCH收到后，如果没有正确保留视频m行，后续bridge时就会丢失视频能力。

修正方法：在自由的dialplan里设置outbound_codec_prefs和pass_rtp_answers等参数，并确保inbound_codec_negotiation设置为generous。同时检查出局网关的编码范围，必要时在呼叫前强制设置media_handling=proxy配合video_codec_prefs=H264，让FreeSWITCH在SDP里主动补齐视频m行。

5.3 场景三：两点间视频经常出现慢动作或跳帧

问题现象：A和B通过FreeSWITCH进行H.264视频通话，正常时也时有跳帧，但点对点直连时无此问题。

排查过程：Wireshark显示视频时间戳偶发大幅回退，RTP时间戳增量并不是均匀的90000增量。FreeSWITCH日志里可以看到RTP自动调整信息。

修正方法：在switch.conf.xml中打开rtp-rewrite-timestamps并保持rtp-auto-adjust-timestamp-rate启用。这样FreeSWITCH会将时间戳重新统一映射到稳定递增序列。实测调整后，视频解码器不再频繁丢帧，画面流畅度明显改善。

5.4 排查速查表

下面这张表是我个人在排障时经常参考的清单，直接抄下来用就行。

5.5 一些长话短说的经验建议

最后分享几个我根据多年经验总结出来的建议。谈不上有多高深，但真能帮你在后续排障时少走弯路。

第一，做视频排障不要先改配置，先抓数据。 很多人一看到视频不通就怀疑某个参数没配好，然后东改一个、西改一个，最后问题不仅没解决，还不能确定是哪个改动起的作用。正确的做法是把SIP Trace和Wireshark抓包都留下，先还原问题现场，再动手改配置。修改之后复现测试，对比前后数据是否发生变化。

第二，proxy_media模式不是“默认选项”。 很多人把proxy_media当成一个既不会像bypass那样暴露NAT问题、又不会像转码那样消耗CPU的“中间路线”，但proxy_media其实有自己的坑。在业务允许的情况下，能bypass就直接bypass，省心。只有在需要媒体介入或遇到NAT穿透问题时，再考虑用proxy_media。

第三，关注SDP里的每一个a行，特别是rtcp-fb和fmtp。 视频RTP本身的问题，十有八九是SDP里某些看起来不起眼的参数没有对齐。常见的fmtp参数如果漏掉或写错，比如H.264的profile-level-id不一致，即使PT协商成功，接收方也可能找不到合适的解码配置。这类问题抓包看不出明显异常，只能通过仔细对比SDP逐个属性去找。

我自己在实际操作中最大的体会是，视频问题绝大多数不是“包丢了”，而是“包到了但不会被正确解析”。所以你在排查时，少一点对网络丢包的执着，多一点对SDP、SSRC、PT和时间戳这些“元数据”的敏感，反而更容易找到真相。希望这篇关于proxy_media模式下video流问题的修正总结，能帮你在下一次排障时少熬几个通宵。