旁路推流最佳实践

为了保障旁路推流服务的可靠性，声网建议你参考本文档集成旁路推流 RESTful API。阅读本文档前，建议你参考旁路推流 RESTful API 概览了解旁路推流 RESTful API 的基础流程。

前提条件

开始使用旁路推流 RESTful API 前，你需要满足以下条件：

• 所在频道场景为直播（profile 为 BROADCASTING）。
• 开通旁路推流 RESTful API 服务。
• 建议开通旁路推流消息通知服务，并监听旁路推流事件。

限制条件

API 调用速率限制

声网服务器限制旁路推流 RESTful API 的调用速率，超出限制速率时会返回状态码 429(Too Many Requests)。如果你有更高调用速率需求，请联系技术支持。

API	限流说明
Create	一个项目中，创建 Converter 的速率上限为 50 次/秒。
Delete	一个项目中，销毁 Converter 的速率上限为 50 次/秒。
Update	一个项目中，更新一个指定的 Converter 的速率上限为 50 次/秒。
Get	一个项目中，获取一个指定的 Converter 的速率上限为 50 次/秒。

PCW 限制

PCW 限制与你使用旁路推流服务处理的视频流分辨率和所在地区有关，详见下表：

服务类型	中国大陆	欧洲	美洲	亚洲（除中国大陆）
旁路推流	SD: 300，HD: 50，FHD: 20	SD: 20，HD: 5，FHD: 0	SD: 20，HD: 5，FHD: 0	SD: 20，HD: 5，FHD: 0

分辨率说明：

• SD：标清视频，分辨率 ≤ 640 × 360
• HD：高清视频，分辨率 ≤ 1280 × 720，且 > 640 × 360
• FHD：全高清视频，分辨率 ≤ 1920 × 1080，且 > 1280 × 720

如需更高配额，请联系技术支持。

推流路数限制

旁路推流服务支持的视频属性上限为：分辨率 1920 × 1080，帧率 30 fps。

旁路推流支持的最大推流流路数详见下表：

服务类型	中国大陆	欧洲	美洲	亚洲（除中国大陆）
旁路推流	SD: 300，HD: 50，FHD: 20	SD: 20，HD: 5，FHD: 0	SD: 20，HD: 5，FHD: 0	SD: 20，HD: 5，FHD: 0

分辨率说明：

• SD：标清视频，分辨率 ≤ 640 × 360
• HD：高清视频，分辨率 ≤ 1280 × 720，且 > 640 × 360
• FHD：全高清视频，分辨率 ≤ 1920 × 1080，且 > 1280 × 720

如果需要提升配额，请联系技术支持。

保障 REST 服务高可用

为保障 REST 服务的高可用，避免因区域网络故障造成的服务不可用，声网提供故障迁移和切换域名的方案。

故障迁移

针对网络故障，以及非声网云、非声网软件、设施和不可抗力因素等因素导致的推流中断，声网旁路推流为了保证更好的用户体验，提供自动故障迁移服务，该服务会在尽量短的时间内完成迁移（预计 2 分钟内），迁移期间推流任务中断，可能导致部分数据丢失。
如果对于频道内较多观众端的场景或关键性业务，你需要基于当前业务的重要性和声网提供的自动迁移时效性来考虑是否采用更高的质量保障，例如准备多路流保障以应对迁移期间的快速切换，或者可以采用退避重试策略主动迁移以减少迁移时间。

多路推流任务保障

如需比故障迁移更高的质量保障，你可以采用多路推流任务保障策略。每路推流任务单独计费，计费方式详见旁路推流计费说明。

你可以选择以下两种方式实现多路推流任务保障：

• 同时开启推流主任务和多个备份任务，在每个推流任务中设置不同的 CDN 地址，当主任务发生故障，CDN 观众端可以及时切换到备份的 CDN 地址。

• 如果你想要推送的 CDN 支持优先级功能，你可以开启一个推流任务 1，向优先级为 1 的 CDN 地址（例如：rtmp://xxx/xxx/xxx?priority=1）进行推流，如果任务 1 发生故障，及时开启推流任务 2，向优先级为 2 的 CDN 地址进行推流。此时，任务 1 会被 CDN 忽略。

切换域名

1. 根据你的业务服务器所在地设置主域名：
   • 业务服务器 DNS 地址位于中国大陆时，设置主域名为 api.sd-rtn.com。
   • 业务服务器 DNS 地址位于中国大陆以外的国家或地区时，设置主域名为 api.agora.io。
2. 当使用主域名发起 RESTful API 请求失败时，使用该域名重试一次。
3. 如果步骤 2 的重试依然失败，使用备用的主域名重试：
   • 如果当前设置的主域名为 api.sd-rtn.com，备用的主域名指 api.agora.io。
   • 如果当前设置的主域名为 api.agora.io，备用的主域名指 api.sd-rtn.com。
4. 如果步骤 3 的重试依然失败，使用与当前解析区域相邻的区域域名重试。
   举例说明：假设你的业务服务器位于欧洲，你设置主域名为 api.agora.io，而且业务服务器解析主域名解析到德国。德国位于欧洲中部 api-eu-central-1.agora.io，查域名信息表可知，相邻区域为欧洲西部 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com。因此，出现网络故障且步骤 2、3 的重试失败时，请使用 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com 域名重试。

注意事项

• 为避免重试请求过于频繁，超过声网服务所规定的 QPS（每秒请求数），声网建议你使用退避策略。例如，第一次等待 1 秒后重试、第二次等待 3 秒后重试、第三次等待 6 秒后重试。
• 如果是网络问题而非 DNS 解析域名问题导致的请求失败，声网建议你跳过步骤 3，直接进行步骤 4。
• 切换至区域域名前，请确保你使用的业务（例如，云端录制、云信令、频道管理等 REST 服务）在该区域有部署服务。

域名信息

主域名	区域域名	地理区域
api.sd-rtn.com	api-us-west-1.sd-rtn.com	美国西部
	api-us-east-1.sd-rtn.com	美国东部
	api-ap-southeast-1.sd-rtn.com	亚太东南
	api-ap-northeast-1.sd-rtn.com	亚太东北
	api-eu-west-1.sd-rtn.com	欧洲西部
	api-eu-central-1.sd-rtn.com	欧洲中部
	api-cn-east-1.sd-rtn.com	中国华东
	api-cn-north-1.sd-rtn.com	中国华北
api.agora.io	api-us-west-1.agora.io	美国西部
	api-us-east-1.agora.io	美国东部
	api-ap-southeast-1.agora.io	亚太东南
	api-ap-northeast-1.agora.io	亚太东北
	api-eu-west-1.agora.io	欧洲西部
	api-eu-central-1.agora.io	欧洲中部
	api-cn-east-1.agora.io	中国华东
	api-cn-north-1.agora.io	中国华北

启动旁路推流

创建一个 Converter（Create）时，你需要关注以下注意事项：

• 你需要通过 region 参数分区域创建 Converter：

  • 设置的 region与你的 CDN 源站在同一个区域。
  • 传入 region 的值为小写。
  • 确保本地服务器覆盖本地推流服务。

• 声网推荐你对请求报文的 Header 中的 X-Request-ID 字段赋值，声网服务器会在响应 Header 中返回一个 X-Custom-Request-ID 字段，以用于问题排查。

• 为避免重复创建多个 Converter 导致重复推流，使用 name 字段管理指定项目下的 Converter：

  • 同一时间，一个项目下不允许出现重名的 Converter，否则在尝试创建同名的 Converter 时会收到响应状态码 409(Conflict)。
  • 声网推荐你以频道名和 Converter 特性组合来为 name 赋值。例如 show68_horizontal 和 show68_vertical，分别代表在频道 show68 中创建的用户画面为水平布局和和垂直布局的 Converter。

• 纯音频流或纯视频流场景下 audioOption 和 videoOptions 设置如下：

  • 在纯视频流（无音频）场景中，无需设置 audioOptions 及其相关字段。
  • 在纯音频流（无视频）场景中，默认情况下无需设置 videoOptions 及其相关字段。特殊情况请参考纯音频场景中输出 SEI。
  • 在音视频场景中，videoOptions 为必填字段，不可设置为空；audioOptions 为必填字段，可以设置为空。

• 请设置合理的 idleTimeout 的参数值，推荐使用默认值 300 秒，表示当频道内所有订阅主播都离开频道 300 秒后 Converter 自动销毁，旁路推流停止。

纯音频场景中输出 SEI

在纯音频流（无视频）场景中，默认情况下无需设置 videoOptions 及其相关字段。但是如果你需要在音频流中携带用户的额外信息，例如音量，你可以通过 videoOptions 中的 seiOptions 字段设置 SEI 信息。

如果你想在纯音频场景下输出用户携带的 Metadata 或 DataStream 类型的 SEI 信息，而且不想被收取视频转码费用，那么你可以进行如下设置：

• 在 videoOptions.seiOptions 中传入待输出的 SEI 信息。
• 确保 videoOptions.canvas 中的宽度和高度均设为 16，否则会产生视频转码费用。
• 在 videoOptions.layout 中将携带 SEI 信息的用户的 UID 传入 rtcStreamUid 字段中。

更新旁路推流

更新指定的 Converter（Update）时，你需要关注以下注意事项：

• 使用查询参数 sequence 对同一个 Converter 进行多次 Update 时，请确保 sequence 值递增，旁路推流服务会按照最新 Update 请求（即最大序列号）更新 Converter。
• Update 不支持更新 Converter 的如下配置：
  • name
  • idleTimeOut
  • transcodeOptions.rtcChannel
  • transcodeOptions.audioOptions.codecProfile
  • transcodeOptions.audioOptions.sampleRate
  • transcodeOptions.audioOptions.bitrate
  • transcodeOptions.audioOptions.audioChannels
  • transcodeOptions.videoOptions.codec
  • transcodeOptions.videoOptions.codecProfile

问题排查及建议措施

使用退避策略重试

当推流过程中出现 404、429、5xx 错误码时，你需要采取退避策略，例如等待 5-6 秒、10-11 秒、15-16 秒后重试。

使用退避策略重试后，如果连续 3 次出现 404、5xx 错误码，或查询推流状态响应包体中的 state 字段为 failed，说明推流失败，请按照以下步骤进行排查：

1. 确认 CDN 推流地址是否正确。
2. 如果 CDN 推流地址正确，请销毁当前 Converter，并重新创建。

其他异常情况下，旁路推流服务会自动更换推流服务器重新推流。

根据错误码排查

• 如果状态码为 200，则请求成功。
• 如果状态码不为 200，则请求失败。请根据对应的响应报文 Body 中的 message 字段内容排查问题。

状态码	可能的 message 字段内容	原因	建议措施
200 OK	/	创建成功	/
400 Bad Request	Invalid parameter: rtmpUrl. Replace it and retry.Invalid parameter: idleTimeout. Replace it and retry.	请求参数错误	参考 HTTP 响应 Body 中的 reason 字段进行排查。
401 Unauthorized	Invalid authentication credentials.	RESTful API 认证失败	重新 HTTP 基本认证。
403 Forbidden	No valid permission to use this function. Contact us.	未开通服务	开通旁路推流 RESTful API 服务。
404 Not Found	Resource is not found and destroyed.	并未成功启动推流任务、启动任务后中途退出、自动迁移中、正在销毁 Converter。	采用退避策略重试。
409 Conflict	Resource with the same name has already existed. Use the existing resource, otherwise delete it and create a new resource.	已存在相同名称的 Converter。	删除已有 Converter 并重新创建。
429 Too Many Requests	Request rate limit exceeded.Resource quota limit exceeded.No available resources.	并发请求过多	采用退避策略重试。
500 Unknown	Internal errors. Contact us for troubleshooting.	服务端内部错误	采用退避策略重试。
501 Not Implemented	The method requested has not been implemented.	服务端内部错误	采用退避策略重试。
503 Service Unavailable	The server is temporarily overloading. Retry with a backoff strategy and contact us for troubleshooting.The server is temporarily down. Retry with a backoff strategy.	服务端内部错误	采用退避策略重试。
504 Gateway Timeout	Gateway timeout. Check whether the resource is created, if not, re-create a new resource.	服务端内部错误	采用退避策略重试。

联系声网技术支持

如果以上排查方法并未解决问题，请务必在日志中打印出响应 Header 中的 X-Request-ID 和 X-Resource-ID 字段值，并联系声网技术支持。

检查清单

参考以下表格，快速确认每条检查项是否符合集成要求，以保证旁路推流服务的可靠性。

编号	重要程度	检查项	检查内容	符合集成要求
1	必要	频道模式	所在频道场景为直播。	✓
2	必要	开通服务	开通旁路推流 RESTful API 服务。	✓
3	必要	QPS 限制条件	确保一个项目中，API 的调用速率低于最大限制。详见 API 调用速率限制。	✓
4	必要	PCW 限制	确保一个项目中，并发任务数低于 300。详见 PCW 限制。	✓
5	可选	管理 Converter	使用 name 字段管理指定项目下的 Converter，以频道名和 Converter 特性组合来为 name 赋值。	✓
6	必要	区域设置	设置的 region 与你的 CDN 源站在同一个区域。传入 region 值为小写。	✓
7	必要	超时逻辑	设置合理的 idleTimeout，推荐设置为 300 秒。	✓
8	必要	更新 Converter	对同一个 Converter 进行多次 Update 时，sequence 值递增。	✓
9	可选	问题排查	请按照如下方案进行问题排查： 使用退避策略。 根据错误码排查。 如果以上排查方法并未解决问题，请打印出响应 Header 中的 X-Request-ID 和 X-Resource-ID 字段值，并联系声网技术支持。	✓
10	可选	消息通知	开通旁路推流消息通知服务，并监听旁路推流事件。	✓