博客/指南

LiveKit Ingress 将来自 LiveKit 外部的媒体引入房间。它接受三种类型的源:

  • RTMP 和 RTMPS,由 OBS、ffmpeg 或硬件摄像头等编码器推送。
  • WHIP,一种基于 WebRTC 的协议,同样由编码器推送。
  • URL 输入,即 Ingress 从你提供的 URL 拉取文件或流:可以是 HTTP(S) URL,例如 HLS 流或 MP4 文件,也可以是 srt:// URL,用于由 SRT 服务器提供的流。

Ingress 服务接收媒体,并将其作为参与者发布到房间中,因此其他参与者订阅其轨道的方式与订阅任何其他参与者的轨道相同。Ingress 会对 RTMP 和 URL 输入进行转码:它解码流并重新编码为 WebRTC。WHIP 媒体默认原样通过,但你可以启用转码。

要了解如何创建和配置 Ingress,请参阅 Ingress 概览.

连接问题#链接到本节

当 RTMP 服务器拒绝发布请求时,它会返回状态 NetStream.Publish.Failed。在 GStreamer 中,错误如下所示:

1ERROR: from element /GstPipeline:pipeline0/GstRtmp2Sink:rtmp2sink0: 2Failed to connect: 'publish' cmd failed: onStatus: { "level": "error", 3"code": "NetStream.Publish.Failed", "description": "Publish failed." }

OBS 和 ffmpeg 等流媒体工具会将此状态隐藏在更通用的错误之后。ffmpeg 显示类似如下内容:

1[rtmp @ 0x...] Server error: Publish failed.2Error opening output rtmp://<ingress-url>/<stream-key>: Operation not permitted

OBS 显示此错误:

1Could not access the specified channel or stream key, please 2double-check your stream key. If it is correct, there may be a 3problem connecting to the server.

这些错误中的每一个都可能有多种原因,如下表所示:

问题解决方法
你提供的 stream key 不正确。使用 CreateIngress返回的 stream key,并检查它是否完全匹配。
该 stream key 属于一个已被 删除.的 Ingress。运行 lk ingress list。如果该 Ingress 未列出,则它已被删除,其 stream key 不再有效。
该 stream key 属于不同输入类型的 Ingress,例如,将 WHIP stream key 用于 RTMP 编码器。运行 lk ingress list --id <ingress-id> --json。如果 state.error 为 invalid ingress type,请更改编码器设置以匹配该 Ingress,或创建正确类型的 Ingress。
该 Ingress 未 启用.运行 lk ingress list --id <ingress-id> --json 并检查 enabled 是否为 false。如果是,请使用 UpdateIngress重新启用它,将 enabled 设置为 true.
发生了其他一些暂时性问题。稍等片刻后重试。

连接超时#链接到本节

如果你的编码器挂起并最终超时而不是立即失败,则连接可能从未到达 LiveKit。要确认这一点,请检查你的 webhooks 中是否有 ingress_started 和 ingress_ended 事件。如果两者都未到达,且 Ingress 状态 没有变化,则连接从未成功建立。

通常的原因是防火墙。普通 RTMP 使用 TCP 端口 1935,企业网络和场馆网络经常会封锁该端口。RTMPS 使用端口 443,该端口几乎总是开放的,因此最快的解决方法是让你的编码器改用 rtmps:// URL。

媒体连接失败#链接到本节

本节仅适用于 WHIP。WHIP 通过 HTTP 请求建立会话,但媒体通过单独的 WebRTC 连接传输,通常基于 UDP。即使 HTTP 请求成功,该连接也可能失败。

你看到的现象取决于 Ingress 是否进行转码:

  • 不转码时(WHIP 的默认设置),Ingress 起初看起来正常。它加入房间并报告 ENDPOINT_PUBLISHING,但大约 15 秒后参与者离开,Ingress 返回 ENDPOINT_INACTIVE.
  • 转码时,Ingress 保持在 ENDPOINT_BUFFERING ,大约 10 秒后转为 ENDPOINT_ERROR ,并带有错误 source encoder not ready.

在两种情况下,最可能的原因是媒体连接无法建立。流本身没有问题;只是你的编码器与 LiveKit 之间的 WebRTC 连接从未完成。

一个可能的原因是防火墙封锁了 UDP,而 WebRTC 优先使用 UDP。当 UDP 被封锁时,某些编码器(例如 GStreamer 的 whipsink)会回退到基于 TCP 的 ICE,这在 LiveKit Cloud 上使用端口 7881。其他编码器(包括 OBS)不会回退,因此连接失败。如果你无法开放 UDP,请确保 TCP 端口 7881 可访问,并使用支持基于 TCP 的 ICE 的编码器。

在自托管部署中,如果 WHIP 源与 Ingress 服务之间网络路径上的某个环节不支持 IPv6,媒体连接也可能失败。最简单的解决方法之一是在服务器上禁用 IPv6。

你的编码器可能比 Ingress 更晚察觉媒体连接失败。OBS 会持续尝试约一分钟,然后显示此错误:

1An unexpected error occurred when trying to connect to the2server. More information in the log file.

OBS 的日志文件显示连接从未完成: PeerConnection state is now: Connecting,随后是 Failed,中间没有 Connected 。

如果 WHIP 流正常工作几分钟或几小时后冻结,可能的原因是网络路径上影响 UDP 流量的变化。

编解码器问题#链接到本节

如果某条轨道使用的编解码器不受 Ingress 支持,该轨道可能会从房间中缺失,且不会报告任何错误。例如,在撰写本文时,Ingress 不支持通过 RTMP 传输的 H.265 视频。如果你发送它,Ingress 参与者只会发布音频轨道。请确保你的编码器发送受支持的编解码器,例如 H.264。 编码器文档 中提供了每种输入类型的示例配置。

区域注意事项#链接到本节

如果观众看到高延迟或画面冻结,请检查 Ingress 连接到了哪个区域,如 LiveKit Cloud 仪表板的会话视图所示。Ingress 会根据网络状况路由到某个 LiveKit 区域,但如果 Ingress 始终连接到远离你的推流者或观众的区域,则值得进一步调查。

最佳实践#链接到本节

Ingress 会在房间不存在时创建它。如果你需要控制房间的属性,请在开始推流前调用 CreateRoom 。

先删除 Ingress,再删除房间。如果你在编码器仍在向该房间中的 Ingress 发送数据时调用 DeleteRoom ,Ingress 会重新加入,房间也会被重新创建。

复用 Ingress。RTMP 或 WHIP Ingress 不是单个流;它是一个长期存在的端点,你可以多次向其推流。每个 RTMP 和 WHIP Ingress 在其存在期间都会计入项目的 并发导入 只要它存在,就会一直占用并发导入限额,即使没有任何流推送到它,因此请复用你的 Ingress,并删除不再需要的 Ingress。否则, CreateIngress 最终会失败并报错 total ingress object limit exceeded.

URL 输入会立即开始。与等待编码器的 RTMP 和 WHIP 不同,URL Ingress 在创建后就会立即开始拉取源。请仅在准备好让它发布时再创建它,并在创建后立即 检查其状态 。

无论是否有人在观看,转码分钟数都会计费。请添加应用逻辑以避免浪费分钟数,例如监听 ingress_started 事件并 删除 运行时间超过设定时长的任何 Ingress。


如果你仍然遇到 Ingress 问题,请加入 LiveKit 开发者社区 并分享你看到的情况。

相关内容

10.16.2026

如何构建生产就绪的 AI 语音代理

阅读
10.13.2026

Egress 故障排查

阅读
10.06.2026

Retell vs. Vapi vs. LiveKit 语音 AI 代理:面向开发者的比较

阅读