1. 蜂鸟不采蜜：Colibri在WebRTC架构里的真实定位

第一次看到Colibri这个词，我以为是个前端UI库或者某个轻量级框架。后来做视频会议系统，反复在Jitsi的文档里撞见它，才意识到这个名字背后藏着一个非常有意思的WebRTC组件—— Colibri不是采集端，不是播放器，而是整个实时音视频通信中负责媒体流路由转发的核心引擎 。

蜂鸟是鸟类中体型最小、翅膀扇动频率最高的物种，每秒振翅可达50次以上。Jitsi团队给这个媒体路由器取名Colibri，意思很直白：小个子，但频率极高、反应极快。它也确实配得上这个名字——在WebRTC的SFU（Selective Forwarding Unit，选择性转发单元）架构里，Colibri不做混流、不转码，只做一件事：把每一路发布者的媒体包高效地转发给需要的订阅者。这个“只转发不处理”的设计，让它在高并发场景下能把单机的性能压榨到极致。

如果你第一次接触这个概念，可以这样理解：传统MCU（多点控制单元）视频会议，所有参会者的画面都要先汇聚到服务器上，由服务器完成混流和转码，再统一推送给每个人。这种方式服务器压力极大，一路1080p转码就要吃掉不少CPU，20个人开会服务器基本就在满负荷运转了。而SFU的思路完全不同，服务器只管当“快递分拣中心”，收到谁的视频包，就照着订阅关系原样转发给其他人。谁的画质好、谁在说话、谁在看谁，这些决策都交给客户端自己处理。服务器既不碰视频内容，也不做任何格式转换，所以一台普通的云主机就能支撑几十上百路并发。

这正是Colibri的价值所在。它不是某个单独安装的软件包，而是深度嵌在Jitsi Videobridge（简称JVB）内部的媒体路由引擎。JVB是它的宿主进程，Colibri是它的灵魂。很多人在部署Jitsi Meet时只关心最终能不能开会，却不知道真正决定并发上限和延迟低不低的，正是这个不起眼的“蜂鸟”引擎。这篇文章我会从它的工作模型、部署方式、性能调优，到我在真实环境中踩过的坑，完整地拆一遍，希望能给正在做WebRTC服务选型或打算深挖Jitsi的读者一些帮助。

2. 媒体路由背后的核心机制：端点、通道与会议三层模型

业务代码里你只需要调用一个 createConference 接口，但Colibri内部管理一场视频会议的方式，远比“建个房间拉流推流”要精细得多。它把一场会议抽象成了三层模型，理解这三层，才能解释后面你会遇到的很多诡异问题。

2.1 三个核心抽象：会议、端点与通道

Colibri里最顶层的是 会议（Conference） ，对应一个虚拟的会议室。会议室本身不直接持有任何媒体流，它只是一个容器，负责创建和销毁底层的传输通道，并维护一份“哪些端点在参会”的名单。

中间层是 端点（Endpoint） ，每个加入会议的浏览器或客户端都是一个端点。端点是逻辑概念，它不负责具体的网络收发，只代表一个参与者。Colibri给每个端点分配一个唯一的ID，并通过这个ID管理媒体流的订阅关系。

最底层是 通道（Channel） ，通道是真正干活的对象。每条通道代表一条端到端的媒体流通路，包含两样关键东西：发送媒体包的 传输（Transport，一般是DTLS-SRTP加密的UDP/TCP连接） ，以及描述媒体本身特征的 载荷类型（Payload Type，即编码格式、采样率、码率等） 。一个端点可以有多个通道，比如一个用户同时开了摄像头和麦克风，那他在媒体层面上就是两条独立的通道。

2.2 信令与媒体流的解耦设计

很多初次接触Jitsi源码的人都会被一个问题绕晕：Colibri既然是媒体路由器，为什么文档里全是HTTP请求和JSON字段？原因在于Colibri严格按照“信令与媒体分离”的原则设计：

• 信令通道 ：Jitsi Meet的前端通过WebSocket与JVB建立连接，路径通常是 /colibri-ws 。前端发起的“我要加入会议”、“我要发布摄像头流”等请求，全部走这个WebSocket通道，以JSON-RPC的形式发送给Colibri。Colibri收到后，负责在内部创建对应的端点与通道，并把协商好的网络信息（IP、端口、指纹等）通过信令返回给客户端。
• 媒体通道 ：协商完成后，真正的音视频数据流走的是RTP协议，通过UDP端口直接传输。信令关了，媒体照常进行；反过来，媒体断了，信令依然健在。这种解耦设计的好处很明显：信令流量极小，可以走稳定的TCP；媒体流量极大，必须走低延迟的UDP。两者互不干扰，各自用最合适的传输方式。

2.3 为什么选择UDP为主、TCP兜底

JVB的媒体传输默认使用UDP，这也是我在生产环境里强烈建议保持的配置。原因不复杂：RTP本身是实时传输协议，对延迟极其敏感，对少量丢包则有一定容忍度。UDP没有TCP的重传机制，丢包后只能靠前向纠错或接收端隐藏来弥补，但这在视频会议里是可接受的——你宁可偶尔卡顿100毫秒，也不希望因为一个丢包而整体停顿300毫秒以上。而TCP一旦丢包，后续所有包都要排队等待重传，一个网络抖动就能让整条视频流卡成幻灯片。

Colibri也提供了TCP兜底能力。当客户端处于某些严格限制UDP的NAT或防火墙后面时，媒体可以回退到TCP 443端口传输。但这个方案我建议只在“能开会”和“开不了会”之间做保底，不要作为默认路线。实测下来，TCP模式下JVB的CPU占用和延迟都会明显上升，尤其在多路并发时，TCP队头阻塞的影响会被成倍放大。

3. 从零部署一套可支撑百人并发的Colibri媒体服务

单独把Colibri拎出来部署并不现实，因为它无法独立运行，必须依附于Jitsi Videobridge。但如果你理解它作为JVB核心引擎的角色，就能明白： 部署JVB，本质上就是在部署一个生产级的Colibri运行时 。下面是我在一台4核8G云主机上从裸机到跑通全程的实操记录。

3.1 硬件选型与环境准备

先给出我测试环境的基准配置，给你一个参考坐标：

项目	配置	说明
CPU	4核（Intel Xeon Platinum）	视频转发是网络密集型任务，4核是起步线
内存	8GB	每路流的内存占用不算高，关键看并发尖峰
带宽	200Mbps上行	100路同时通话时，上行带宽决定上限
操作系统	Ubuntu 22.04 LTS	Jitsi官方支持最好，包依赖最省心
架构	x86_64	ARM也可用，但部分依赖需要自己编译

系统准备阶段有个细节容易踩坑： 务必确认防火墙放行了UDP 10000端口段 。JVB默认的媒体端口是UDP 10000，不是TCP 10000，也不是80和443。很多人部署完发现客户端一直“连接中”，十有八九就是这个端口没放行。我还会顺手把TCP 4443和TCP 9090也放行，前者用于TCP兜底传输，后者是JVB的WebSocket信令端口，nginx反代会用到。

3.2 通过apt源安装Jitsi Videobridge

Ubuntu系统下最简单的安装方式是直接使用Jitsi官方apt源：

# 添加Jitsi源的GPG密钥
wget -qO - https://download.jitsi.org/jitsi-key.gpg.key | apt-key add -

# 添加软件源
echo "deb https://download.jitsi.org stable/" >> /etc/apt/sources.list.d/jitsi-stable.list

# 更新并安装
apt update
apt install jitsi-videobridge2

如果要部署完整的Jitsi Meet服务，还需要装 jitsi-meet 和 jicofo （会议焦点组件）。但如果你的目标是单独把媒体转发能力跑起来做二次开发，只装 jitsi-videobridge2 就够了。装完后JVB会以 jvb 系统用户的身份运行，主配置文件在 /etc/jitsi/videobridge/jvb.conf ，日志输出到 /var/log/jitsi/ 。

安装完成后，我习惯立刻验证一下Colibri的WebSocket通道是否正常响应：

curl -s http://localhost:8080/colibri/stats | jq

如果返回了一段JSON，里面有 conferences 、 endpoints 、 channels 这些字段，说明JVB进程已经健康运行，且Colibri的统计接口已经在吐数据了。这个接口平时监控很有用，不需要额外装任何插件。

3.3 让JVB具备公网NAT穿透能力

云主机部署必然涉及NAT问题。不管云厂商的VPC内部怎么玩，你的公网IP和服务器网卡上的私有IP一定不是同一个。JVB默认通过ICE协议自动探测本地IP和公网映射地址，但在某些云环境下探测会失败，导致客户端收到的媒体地址是内网IP，数据包根本飞不回来。

这个问题的解法是在 jvb.conf 里显式指定公网地址。打开配置文件，跳到 ice 相关配置段，添加：

ice.udp.port=10000
ice.tcp.port=4443
ice.nat.harvest.private.ip=false

更稳妥的做法是在JVB启动参数里通过 JVB_OPTS 传 --host=公网IP ，强制本机所有候选地址都绑定到公网IP。但这里有个前提：如果服务器上跑了多个WebRTC服务，强制绑定公网IP会让它们共用同一套候选地址，容易造成端口冲突。所以我个人更推荐在JVB的systemd服务文件里单独配置，而不是改全局Java参数。

提示：配置完记得重启服务： systemctl restart jitsi-videobridge2 ，然后看日志确认没有“Failed to harvest”之类的报错。

4. 实测数据与调优：CPU、带宽与丢包的真实边界

部署只是开始，生产环境最重要的还是性能表现。我在测试环境里做过几轮压测，同时跑了50路视频（每路360p，约300kbps码率）和30路纯音频，把JVB的关键指标拉了一遍，这里直接分享最核心的结论。

4.1 压测环境下的性能基线

50人视频+30人音频同时在线，4核8G的云主机CPU占用率稳定在65%到75%之间，内存占用在2.4GB左右，上行带宽约占满150Mbps，下行流量比较低，因为JVB主要是“拉进来再推出去”。这组数据说明两件事： CPU不是瓶颈，带宽才是 。如果你计划长期支持100人以上并发，带宽规划一定要留出至少50%的余量。

延迟方面，本地局域网压测时RTT中位数是1.2ms，经公网跨地域测试时RTT中位数跳到28ms。这其中有网络本身的物理延迟，也有JVB转发队列带来的排队延迟。整体来说，Colibri自身的处理耗时在2ms以内，绝大多数延迟都发生在网络链路上。

4.2 三个值得调的JVB线程池参数

JVB默认配置直接用也能跑，但在高并发场景下，我建议重点调三个参数，它们直接影响Colibri在繁忙时的吞吐稳定性：

• org.jitsi.videobridge.xmpp.user.threads ：默认值是处理器核数。这个参数控制JVB用于处理XMPP信令的线程数，在4核机器上默认就是4。信令频率不高，保持默认即可，不必调大。
• org.jitsi.videobridge.cc.avgBitrateKbps ：控制单路视频的目标码率上限，默认值很低（几百Kbps级别）。多人场景下建议手动调高到1200左右，否则客户端看到的画面会偏模糊。
• org.jitsi.videobridge.ENABLE_BWE_DISTRIBUTION ：默认开启。它允许Colibri根据每个接收端的带宽反馈动态调整发送码率，避免弱网用户拖垮整体体验。建议保持开启，不要为了“统一画质”把它关掉。

这几个参数都写在 jvb.conf 的 videobridge 配置段里。改完之后不需要重启，JVB支持热加载部分配置，但保险起见我还是会重启一次。

4.3 网络抖动和丢包时，Colibri先保谁

WebRTC的拥塞控制机制在JVB里的表现很有意思。当网络开始抖动，带宽不足以支撑全量转发时，Colibri会自动降级：优先保证音频流完整，然后是活跃说话人的视频流，最后才轮到其他参与者的视频流。这个优先级机制写死在代码里，不需要人工干预。

我专门做过一次人为丢包测试，用 tc 命令在网卡上模拟5%的随机丢包：

tc qdisc add dev eth0 root netem loss 5%

在5%丢包率下，50路视频会议依然能维持基本可用，画面偶有卡顿但很快恢复。丢包率到10%以上时，非活跃发言人的视频会明显降帧率，不过音频始终保持稳定。Colibri的反应速度很快，基本在一两秒内就能根据RTCP反馈调整发送策略。

5. 踩坑笔记：五个真实案例的排查链路复盘

这一节我写五个在部署和运维Colibri过程中亲身遇到并复盘过的问题。每个问题都保留了完整的排查思路，而不是直接告诉你答案——因为下次你遇到的报错未必一模一样，但排查方法是可以复用的。

5.1 案例一：会议建立后17秒必定断开

现象非常规律：每次会议拉起来，17秒后所有客户端同时掉线，日志里出现“Failed to receive RTP data”的告警。

排查链路：

1. 我先怀疑是防火墙拦截了UDP 10000，但放行后问题依旧。
2. 接着用 tcpdump -i any udp port 10000 抓包，发现服务器确实收到了RTP包，但包数量忽高忽低，像是被某种策略限速了。
3. 这个“17秒断开”是WebRTC的ICE连接超时机制，说明媒体包虽然到了服务器，但返回路径出了问题。
4. 最后登录云厂商的控制台发现，安全组里虽然放行了UDP 10000，但网络ACL层面还有一条默认拒绝规则，把UDP全部卡掉了。安全组和ACL是两层过滤，只看一层必然踩坑。

这个案例的教训很直接： 排查网络问题时，一定要先确认云厂商的“安全组”和“网络ACL”两层都放行，再看本机iptables 。顺序别反。

5.2 案例二：WebSocket连不上，但是协议和端口都“看起来”没问题

有次部署在公网环境下，用 netstat 能看到JVB监听在9090端口，nginx也配置了 /colibri-ws 的反代，但前端WebSocket就是连不上，浏览器控制台报401。

排查链路：

1. 用 curl -v http://localhost:9090/colibri-ws 测试，能正常返回101 Switching Protocols，说明JVB本身没问题。
2. 再用 curl https://域名/colibri-ws 测试，返回的是404。
3. 检查nginx配置，发现 proxy_pass 写的是 http://127.0.0.1:9090 ，没带URI尾部的 / 。但 location /colibri-ws 正确，问题应该不在这。
4. 翻到nginx访问日志，看到请求实际打到了Jitsi Meet的另一个服务上，原因是nginx里同时挂了Jitsi Meet和JVB的反代规则，而Jitsi Meet的 location / 规则更泛，先匹配到了。

解决方案很朴素：把JVB的WebSocket反代规则提到Jitsi Meet规则之前，并加上精确的 location = /colibri-ws 匹配。这个问题的本质是nginx路由优先级，跟Colibri本身没关系，但排查过程最能暴露对组件边界的理解。

5.3 案例三：多个JVB节点组集群，会议时而正常时而分裂

升级到多节点部署后，20人的会议经常出现“一部分人互相看得见，另一部分人互相看不见”的情况。同一场会议室里，大家像是在两个平行世界。

排查链路：

1. 打开JVB的统计接口，发现这场会议同时存在两个不同的Conference ID，说明客户端被路由到了不同的JVB节点。
2. Jitsi默认的调度策略（通过Jicofo分配）会把新加入的人路由到负载最低的节点，所以20个人可能被拆到两个节点上。
3. 想让不同节点上的参会者能互相通信，必须开启JVB的octo信令与媒体桥接支持。octo是JVB跨节点传输的协议，Colibri通过它把不同节点上的通道互相联通。

解决办法是在 jvb.conf 中启用octo，并确保各节点之间的UDP端口（默认也是10000附近）可以互通：

octo.enabled=true

顺着这个问题深入追了一下源码，octo的设计思路其实很优雅：它把分布式集群模拟成单个JVB实例，每个通道的MediaStreamTrack信息在节点之间同步，媒体包则通过节点间UDP隧道转发。集群里每个节点依然只做转发，不做混流，非常适合做水平扩展。

5.4 案例四：长时间运行后内存持续上涨，最终OOM

服务连续跑了一周后，内存从1.8GB一路涨到6GB，直到进程被OOM killer杀掉。

排查链路：

1. 看JVB日志，没有明显的崩溃或GC错误，说明不是瞬时突增，而是缓慢泄漏。
2. 用 jstat -gc 观察JVM堆内存，发现老年代(GCC)不断上涨，Full GC间隔越来越短。
3. 怀疑某个会议结束后资源没有彻底释放。用REST API查询，果然发现了大量处于“空转”状态的Conference对象，端点数为0但迟迟没有销毁。
4. 逐个看了日志才发现，是某些客户端异常断网，没有正常发送“离开会议”的信令。Colibri有默认的过期机制，但如果客户端进程直接被杀，TCP断连检测需要等TCP超时，这个时间可能长达数分钟。在极端连续异常退出场景下，新会议建得快，旧会议销毁得慢，内存自然就撑爆了。

临时解法是手动调短JVB的会议过期时间；根治方案是在业务层面加一层心跳，客户端每30秒发送一次信令报活，超过3次未收到就主动调用JVB的REST接口清场。这条经验后来被我用到了自研运营系统里，彻底没再OOM过。

5.5 案例五：某些安卓手机上画面正常但声音全无

这个案例不是JVB本身的故障，而是WebRTC与安卓系统音频焦点机制打架。现象：iOS和桌面端一切正常，安卓端有时候只有画面没有声音，尤其是多任务切换后进来。

排查链路：

1. 先排除了网络和JVB转发问题，因为iOS端同场景完全正常。
2. 用WebRTC的统计信息查看音频轨道的发送/接收情况，一切正常，RTP包确实在走。
3. 最后的结论是安卓端WebRTC的音频会话被系统静音了——没有正确申请音频焦点。这是安卓端App层的问题，跟Colibri无关，但排查过程中会让人误以为是媒体服务器的问题。

这类跨端问题的排查启示： 遇到“客户端表现不一致”的故障时，优先对比正常设备与异常设备的差异维度，别先把锅甩给媒体服务器 。Colibri的统计接口提供了每条通道的收发包计数，是快速定位问题在网络层还是应用层的好工具。

6. 基于Colibri做二次开发的三种思路

Colibri对上层暴露的能力比你想象中要多。如果你不只是想“部署一套开会工具”，而是想把媒体路由能力嵌入自己的产品里，下面三个方向是我验证过可行且值得投入的。

6.1 思路一：用Colibri REST API管理媒体通道

JVB暴露了一套REST接口，虽然官方文档写得比较简略，但核心操作都能完成。最实用的是 GET /colibri/conferences ，能返回当前服务器上所有会议、端点和通道的实时状态，包括每个端点的传输地址、通道数量、媒体类型等。

基于这套接口，可以做很多运营侧的事情，比如强制踢出某个异常端点、清空某个卡死的会议、统计每日会议数量和同时在线峰值。我写过一个简单的运营看板，每10秒轮询一次REST接口，结合请求延迟和通道数量画趋势图，故障预警基本能在用户感知之前发出。

6.2 思路二：通过统计接口对接Prometheus监控

运维可观测性方面，JVB内置了一套JSON统计接口，路径是 /colibri/stats ，字段覆盖了并发会议数、端点总数、通道数、RTP收发字节数、丢包率等。我建议直接写一个exporter脚本，把这些指标转换成Prometheus格式，再接入Grafana。

以每个端点的发流稳定性和收流稳定性为核心构建告警规则，能覆盖大部分故障场景。比如收流稳定性在1分钟内持续低于95%，说明该端点的网络正在恶化，可以触发“会议质量预警”。我在朋友圈里见很多人只监控了JVM堆内存和CPU，却忽略了媒体层面的质量指标，这其实比机器指标更贴合用户体验。

6.3 思路三：把媒体路由能力嵌入自己的WebRTC平台

如果你的团队正在自研WebRTC产品，又不想从零实现SFU，Colibri实际上是很好的“半成品底座”。JVB可以被当作一个独立的媒体服务进程，通过XMPP协议层接入你的信令服务。前端通过 lib-jitsi-meet 这类SDK连接JVB时，走的也是标准协议，不需要深度耦合Jitsi Meet的整套前端逻辑。

我自己曾经在一个内部工具项目里偷懒，只部署了JVB，没部署Jitsi Meet的前端，然后用 lib-jitsi-meet 单独做了一个极简的Web端来开会，体验出乎意料地顺。核心原因是Colibri只管媒体路由，它不关心你脖子上长的是Jitsi Meet还是你自己的界面。这种“只用JVB，不要Jitsi Meet”的玩法，在中文社区里讨论度不算高，但对有自研能力的团队来说，是一条轻量、稳妥、可控的路线。

最后说点掏心窝的话

Colibri这套东西，最大的价值不在于它能跑通视频会议，而在于它把“媒体路由”这个在WebRTC世界里最难啃的骨头，封装成了一套相对成熟、可运维、可扩展的工程方案。我见过不少团队一上来就想自研SFU，结果光是ICE穿透、丢包重传、带宽估计这几个模块就耗费了大半年，最后产出的稳定性还不如直接用Colibri二次开发。技术在“够用”和“自己造”之间做选择时，我会毫不犹豫选前者，把精力留给真正能产生产品差异化的地方。

如果你对这个方向感兴趣，建议上手时先从单机部署开始跑通，再逐步叠加集群和高并发调优，不要一开始就追求大规模。Colibri内部的状态机逻辑不少，不亲手压一次50路并发，很难真正理解它在极端情况下的行为和坑点。希望这篇笔记能帮你少走几步弯路。