声网SDK旁路推流功能配置指南

在做直播项目的时候，经常会遇到这样的需求：主播在 app 里直播，但同时需要把画面同步推送到其他平台或者 CDN 上，让更多观众能够通过网页、小程序等各种方式看到直播内容。这时候就需要用到旁路推流功能了。这篇文章我们来聊聊声网 SDK 里旁路推流到底是怎么回事，配置起来要注意哪些地方，以及实际开发中容易碰到的一些问题。

旁路推流是什么？为什么需要它？

在解释旁路推流之前，先简单说一下声网的实时传输架构。正常情况下，声网内部有一个高质量的传输通道，主播端的音视频数据会先传到声网的服务器，然后服务器再把数据分发给同一频道里的观众。这个通道走的是声网自己的传输协议，延迟低、抗丢包能力强，体验非常好。

但问题在于，这种传输方式只能覆盖使用声网 SDK 的观众。如果你想让那些没有安装 app、或者在其他平台的用户也能看到直播，这就需要把音视频流”推”到公共的 CDN 上。旁路推流就是这个作用的——它相当于在声网的服务器和外部 CDN 之间架了一座桥，把实时音视频流转成标准的 RTMP 协议，然后推送出去。

举个实际的例子你就明白了。假设你在做一个电商直播，主播在手机 app 里开播，同时你想在微信小程序里也能看，还想在官网页面上嵌入播放器。如果没有旁路推流，你就得分别对接不同的终端，成本很高。有了旁路推流，你只需要在 app 端开启这个功能，声网服务器会自动把流推到你指定的 CDN 地址，小程序和网页只要能播放 RTMP 流就能看，逻辑上简单很多。

旁路推流的两种模式

声网 SDK 支持两种旁路推流模式，一种是云端控制，另一种是本地控制。这两种方式各有适用场景，选择哪个取决于你的业务需求。

云端控制模式

云端控制模式下，你不需要在客户端代码里写太多逻辑，一切都由声网服务端来控制。具体来说，你需要先在声网控制台里开启这个功能，设置好推流地址，然后客户端只需要加入频道、开始推流就行了。服务端会自动根据你的配置，把相应的流推送到 CDN。

这种模式的优势在于配置集中、管理方便。如果你的推流地址相对固定，不需要频繁改动，或者你想统一管理所有频道的推流策略，云端控制是更好的选择。缺点是不够灵活，如果你在运行时需要动态调整推流地址，就不太方便了。

本地控制模式

本地控制模式则相反，所有的推流逻辑都在客户端完成。你需要手动调用 SDK 的接口来开始推流、停止推流，甚至可以在运行时动态切换推流地址。这种方式灵活性很高，适合那些推流需求比较复杂的场景。

比如说，你可能需要根据用户的会员等级来决定是否推流，或者根据不同的直播主题推送到不同的 CDN 地址，又或者要在推流失败时自动重试并切换地址。这些场景下本地控制模式会更合适。

不过本地控制也意味着客户端的逻辑会更复杂，你需要处理更多的边界情况，比如网络波动时的重试逻辑、多地址轮换策略等等。

配置前的准备工作

在正式配置之前，有几件事需要提前准备好，不然很可能在配置过程中遇到各种问题。

账号和权限

首先你得有一个声网的开发者账号，并且确保账号已经开通了旁路推流相关的功能权限。新账号可能需要去控制台申请试用或者升级权限，这块建议提前确认好。另外，如果你用的是云端控制模式，你还需要在控制台里配置推流域名和地址模板。

推流地址的获取

旁路推流需要一个目标地址，也就是要把流推到哪个 CDN 上。这个地址需要你自己准备，通常是你使用的 CDN 服务商提供的推流域名加上一个唯一的流名称。

这里有个小提示，推流地址的流名称（StreamKey 或者 stream name 部分）建议设计成有规律可循的格式。比如可以用频道名加上时间戳，或者用户 ID 加上随机器，这样便于管理，也方便后续排查问题。

SDK 版本要求

声网的旁路推流功能对 SDK 版本有要求，太老的版本可能不支持这个功能。建议使用最新的 LTS（长期支持）版本或者最近几个发布的版本，这样稳定性有保障，文档也最新。如果你的项目还在用很老的 SDK，先评估一下升级的成本。

云端控制模式配置步骤

下面我们来看具体的配置步骤。先从云端控制模式开始，因为它相对简单一些。

第一步是登录声网控制台，找到你想要配置的項目。在项目的设置页面里，找到”旁路推流”或者”实时转直播”相关的选项。不同版本的控制台界面可能略有差异，但功能入口通常在”配置”或者”高级功能”这个分类下。

进入旁路推流配置页面后，你需要开启”自动旁路推流”开关。开启后，你需要设置推流地址模板。推流地址通常包含域名和流名称两部分，域名是你 CDN 的推流域名，流名称可以用变量来表示，比如{channelName}，这样每次推流时会自动把实际的频道名填进去。

保存配置后，接下来是客户端的代码实现。在客户端，你需要做的主要是初始化引擎、加入频道，然后 SDK 会自动处理后续的推流逻辑。代码大概是这个样子：

• 创建 rtc 引擎实例，传入你的 AppID
• 加入频道，传入频道名和用户 ID
• 如果需要，开启音视频模块

在云端控制模式下，你不需要手动调用推流相关的接口，SDK 在你加入频道后会根据控制台的配置自动开始推流。你可以通过回调来监听推流的状态，比如是否成功、发生了什么错误等等。

这里有个地方要注意：云端控制模式下，即使客户端没有调用任何推流接口，只要控制台配置了自动推流，并且频道里有用户在说话或者视频，就会触发推流。如果你只想在特定情况下推流，比如主播点击”开始直播”按钮后才推流，那云端控制模式就不太适合了，这种情况应该用本地控制模式。

本地控制模式配置步骤

本地控制模式的配置稍微复杂一些，但逻辑更清晰。首先还是创建引擎、加入频道，这些步骤和云端控制是一样的。区别在于，你需要手动导入旁路推流相关的模块，然后调用相应的接口来控制推流。

在代码层面，你需要先获取旁路推流的服务对象。这个对象提供了一系列方法，比如设置推流配置、开始推流、停止推流、更新推流地址等等。

开始推流之前，你需要构建一个推流配置对象。这个对象里要填的东西包括：

• 推流地址：完整的 RTMP 推流地址
• 音频配置：是否推送音频、编码参数等
• 视频配置：是否推送视频、编码参数、分辨率等
• ，美颜、滤镜等视频增强功能的开关

配置构建好之后，调用开始推流的方法，把配置传进去。SDK 会尝试把流推送到指定的地址。推流开始后，你可以通过回调监听推流的事件，比如推流成功、推流失败、网络状态变化等等。

如果你在推流过程中需要修改配置，比如切换推流地址，可以调用更新配置的方法。声网 SDK 支持在推流过程中动态更新地址，这样可以做到无缝切换，用户基本感知不到中断。

推流参数的细节调整

本地控制模式下，有几个参数值得专门说一下。

首先是视频编码参数。默认情况下，SDK 会使用比较保守的编码设置，适合大多数场景。但如果你的 CDN 对带宽有限制，或者你对画质有特殊要求，可以手动调整分辨率、帧率、码率这些参数。分辨率越高、帧率越高、码率越大，画质越好，但对带宽的要求也越高。需要根据你的目标用户群体的网络情况来权衡。

然后是音频编码参数。声网默认使用高质量的音频编码，但如果你的推流目标是一些对音频格式有特殊要求的平台，可能需要调整编码器的类型和参数。比如有些平台只支持特定的音频格式，这时候你就需要配置成兼容的编码方式。

还有一点，推流是可以选择只推音频或者只推视频的。有时候你可能只需要推送视频画面，不需要音频，或者反过来。这种情况下，可以单独关闭其中一个，节省带宽。

常见问题与解决方案

在实际开发中，旁路推流经常会遇到一些问题。这里总结一下最常见的情况和解决办法。

推流失败，连接被拒绝

这个问题通常有两个原因。第一是推流地址写错了，比如域名拼写错误、流名称里有非法字符、或者地址格式不对 RTMP 协议。检查一下地址是否完整、正确，可以用 FFmpeg 或者其他工具先手动测试一下地址是否可用。

第二个原因是 CDN 侧的权限问题。很多 CDN 服务商要求推流地址带有鉴权参数，比如 token、key 之类的。如果你的地址里没有这些参数，或者参数过期了，连接就会被拒绝。确认一下 CDN 那边设置的鉴权方式，确保你生成的地址包含了所有必要的认证信息。

推流成功了但没有画面

这种情况往往让人困惑——明明回调显示推流成功了，但看播端就是看不到画面。问题通常出在视频源或者编码配置上。

首先确认一下你推送的流确实有视频数据。如果你是用摄像头直播，检查一下摄像头是否正常工作、是否有权限访问。如果你是推送屏幕共享或者自定义的视频源，确保相应的模块已经开启并且有数据产出。

然后检查一下视频编码参数有没有问题。有时候分辨率设置得过高，编码器初始化会失败，这时候会默默跳过去，导致没有视频输出。可以试着把分辨率和码率调低一些，看能不能解决问题。

还有一种可能是 CDN 那边的问题。推流端看到推流成功，不代表 CDN 那边已经正确接收和处理了。你可以登录 CDN 的后台，看看是否收到了流、流的健康状态是否正常。

推流延迟过高

旁路推流相比纯实时传输，延迟会高一些，这是正常的。但如果延迟高得离谱，比如超过十秒，那就需要排查问题了。

首先看网络状况。推流端到声网服务器的网络是否稳定，到 CDN 的网络是否稳定。可以分别在推流端 ping 一下声网服务器和 CDN 的域名，看看延迟和丢包情况。如果网络不好，延迟自然就上去了。

然后检查一下 CDN 的配置。有些 CDN 有缓存策略或者转码流程，会增加延迟。如果你对延迟敏感，选择 CDN 时要选那种针对实时流做了优化的服务，普通的点播 CDN 可能不太适合。

另外，推流参数的设置也会影响延迟。比如 GOP（Group of Pictures）大小、关键帧间隔这些参数。GOP 越大，延迟越高，因为播放器需要等一个完整的 GOP 才能开始解码。如果对延迟敏感，可以把 GOP 设小一点，比如两秒一帧关键帧，但这样会增加码率，需要权衡。

多路推流怎么弄

有时候你需要同时把流推到多个 CDN 地址，比如主备切换、或者同时推不同的平台。声网 SDK 是支持多路推流的，原理就是你调用多次开始推流的方法，每次传不同的地址和配置。

不过多路推流对资源的消耗会更大，特别是视频编码，多推一路就要多编码一次，CPU 和带宽的压力都会增加。如果你需要推很多路，考虑一下在 CDN 层面做分发，而不是在源头推多路。

多路推流时，建议给每路流设置唯一的 ID，这样便于区分和管理。在回调里也会带上这个 ID，你可以知道是哪一路出了问题。

推流过程中网络波动怎么办

网络波动是难免的，特别是在移动场景下。SDK 内部有重连机制，但有时候还需要业务层配合处理。

首先，建议在业务层实现一个监控逻辑，持续检测推流的状态。当检测到推流失败时，可以根据错误类型做不同的处理。如果是临时性网络问题，可以等几秒后重试；如果是地址不可用，可能需要切换到备用地址。

声网 SDK 提供了推流事件回调，你可以监听推流开始、停止、失败、恢复这些事件。当收到失败事件时，不要立即重试，最好有一个退避策略，比如先等两秒，不行再等四秒，再不行再等八秒，避免频繁重试加重服务器负担。

另外，推流地址最好准备备用的。当主地址连续失败几次后，自动切换到备用地址，这样可以提高整体的可用性。

监控与调试技巧

旁路推流上线后，监控是很重要的。声网控制台提供了一些统计信息，可以看到推流的时长、成功率、码率等指标。但这些可能不够用，你最好自己接入更详细的监控。

SDK 里有获取推流统计信息的方法，定期调用一下，把数据上报到你的监控系统。需要关注的指标包括：推流是否还在进行、当前的视频和音频码率、帧率、丢包率、端到端的延迟等等。当这些指标出现异常时，及时告警。

调试的时候，如果遇到奇怪的问题，可以打开 SDK 的日志。声网 SDK 的日志很详细，会记录推流的每一步操作，遇到问题先看日志，往往能找到线索。

还有一个技巧是用第三方工具验证。比如用 VLC 播放器直接播放你的推流地址，看看能不能看到画面、延迟大概是多少。这样可以帮你快速定位问题是出在推流端还是播放端。

写在最后

旁路推流这个功能说复杂不复杂，说简单也不简单。基本的配置步骤其实就那么几步，但要把稳定性做好、把体验优化到位，还是需要花一些心思的。

个人建议是先从简单的场景做起，比如单路推流、固定地址，跑通了再考虑复杂的场景比如多路推流、动态切换地址。一步到位往往容易出问题，迭代着来更稳妥。

另外，多看看声网的官方文档和开发者社区，里面有很多实战经验分享。遇到问题先搜索一下，很可能别人已经遇到过并且有解决办法了。

希望这篇文章能帮到你。如果在实际配置中遇到什么问题，可以再交流。