1. 先弄清楚 Colibri 是什么

最近在搭一套内部用的视频会议系统，群里朋友提到一个词叫 Colibri，一开始我以为是某个新出的开源项目名字，后来查了一圈才发现，它就是 Jitsi 视频会议系统里那个决定媒体流能不能稳定转发的核心协议模块。如果你也想自建一套类似 Zoom、腾讯会议的私有化部署方案，或者正在研究 WebRTC 音视频架构，这篇内容应该能帮你在群里多聊两句。

Colibri 全称是 Conferencing Logic with Integrated Bridge and Routing Infrastructure，翻译过来就是“带集成桥接与路由基础设施的会议逻辑”。名字挺长，但核心就两件事：第一，它是 Jitsi Videobridge（媒体桥）内部的一套逻辑框架；第二，它负责管理所有参会者之间的音视频通道，决定每一路媒体流从哪进来、转到哪去。它不直接处理编解码，也不负责画质增强，它做的事情更像是会议室里的音视频调度员。

我第一次接触这套系统时，注意力全放在 WebRTC 和前端界面上，觉得能开个网页就开会已经很神奇了，压根没注意到 Colibri 的存在。后来并发了二十几路视频，系统时不时出现有人黑屏、有人没声音的情况，我看日志翻到 Colibri 的字样才意识到，真正让这座“媒体桥”跑起来的，正是这套平时看不见摸不着的调度逻辑。

1.1 Colibri 的定位：一座会思考的桥

Jitsi 整个生态里，Colibri 最常被人混淆的概念是“Jitsi Videobridge”本身。简单说，Jitsi Videobridge 是一个媒体服务器程序，而 Colibri 是它内部用来管理媒体会议和路由的核心逻辑。Videobridge 是身体，Colibri 是神经中枢。

为什么需要这样一个“神经中枢”？因为 WebRTC 本身是点对点的设计，两个人开会没问题，十个人开会如果每个人都向其他九个人推流，数据量会爆炸。Colibri 做的事情，就是把“所有人互联”变成“所有人连接到桥”，再由桥统一转发媒体流。这种方式在架构上叫 SFU（Selective Forwarding Unit，选择性转发单元），媒体桥只转发而不混流，既节约了服务端 CPU，又避免了所有音频视频合成一路带来的复杂性和延迟。

从协议层面看，Colibri 工作在 XMPP 信令和 RTP 媒体流之间。Jicofo（会议焦点组件）告诉它“我要创建一个会议”，它就分配资源、创建媒体通道；某个用户加入会议，它就把新的媒体源绑定到对应通道上；有人离开，它负责回收通道。整个过程非常高频，多路音视频同时进出的情况下，消息交互频率和通道增删速度都很快。

1.2 为什么说它是整套系统的“心跳”

我刚开始部署这套系统时，有个特别直观的感受：只要 Colibri 组件异常，整个会议系统就像人没了心跳一样直接瘫痪。最典型的表现是，页面能打开、房间能创建，但所有人进不去，或者进去了互相看不到画面。

这是因为媒体的建立链路完全依赖 Colibri 的通道管理。浏览器端也参与信令交互，但真正决定媒体流往哪走的，是 Jitsi Videobridge 里的 Colibri 通道表。它不只是做“转发”，还会根据参会者的网络状态、带宽情况、是否开启摄像头等条件，动态调整媒体流的走向和优先级。开会时画面是否清晰、声音是否同步，最终都取决于这座“桥”忙不忙得过来。

所以如果你只是把 Jitsi Meet 当成一个网页应用来看待，忽略了 Colibri 这座核心媒体桥，后续排查问题会非常痛苦。它才是真正决定“能不能开会”“开得好不好”的关键。

2. 一套 Colibri 系统里都有谁

Colibri 不是单独运行的软件，它嵌在一套完整的开源视频会议系统里。平时大家说的“Jitsi Meet 部署”，其实就是把这套系统里所有组件编排到一起。组件之间的配合逻辑搞清楚了，部署和维护都会顺很多。

2.1 组件分工

我简单梳理一下这套系统里的主要成员，以及它们各自负责的事情。

Jitsi Meet（Web 前端）

用户浏览器里打开的界面。负责采集摄像头的音视频流、展示远端画面、提供聊天和参会控制按钮。它不处理媒体转发，只做内容呈现和本地采集。

Prosody（XMPP 服务器）

系统的“前台接待”。所有信令消息都走 XMPP 协议，比如创建房间、加入房间、参会者状态同步等。用户和会议室之间的“对话”都经过它中转。

Jicofo（会议焦点组件）

会场的“组织者”。它负责实际创建会议、协调参会者加入流程、和 Colibri 配合分配媒体通道。当用户点击“加入会议”时，Jicofo 会通知 Videobridge 准备好媒体通道。

Jitsi Videobridge（媒体桥）

真正的“音视频转发中枢”，Colibri 就在这里面。所有媒体流都汇聚到这里，再由它转发给各个参会者。

Nginx（反向代理）

最外层的“门卫”。负责给用户提供网页资源，终止 TLS 加密连接，同时把信令请求转发给内部的 Prosody 等服务。云服务器上部署时，80 和 443 端口都由它接管。

这五个角色配合跑起来，才是一个完整的视频会议系统。缺了任何一个，会议都进行不下去。比如 Prosody 挂了，用户连房间都创建不了；Jitsi Videobridge 挂了，用户能进会议室但互相看不到画面；Jicofo 挂了，会议无法正常协调。

2.2 一次会议请求的完整流转

为了让你更清楚 Colibri 在整个链路里处于哪个位置，我走一遍完整流程。

用户输入网址打开页面，请求先到 Nginx，Nginx 返回 Jitsi Meet 的前端静态文件。用户输入房间名并点击“加入”，浏览器向 Prosody 发送 XMPP 信令，请求加入某个会议室。Prosody 收到请求后，让 Jicofo 介入协调。Jicofo 检查这是一个新会议还是已有会议，如果是新会议，它会向 Jitsi Videobridge 发送 Colibri 协议指令，创建会议并分配媒体通道。创建完成后，Videobridge 返回媒体服务器的地址和端口信息给客户端，浏览器开始通过 WebRTC 与媒体桥建立音视频连接。

这个过程中有一个关键角色容易忽略——会议 ID 和媒体通道的映射关系。Jicofo 负责维护“哪个会议对应哪些通道”，Colibri 则只负责“通道怎么建、流怎么转”。职责分离得很清楚，这也是它能支撑大量并发会议的架构基础。

打个比方，Prosody 是酒店前台，Jicofo 是会议统筹，Colibri 是会议室里的调音台和线路分配器。调音台不负责唱歌，也不负责请人，但所有声音能不能准确传到每个人耳朵里，全靠它后面的线路接得对不对。

3. 实操：从零部署一套 Colibri 会议系统

理论讲完，下面进入实操环节。我自己用的是 Ubuntu 22.04 服务器，通过官方 Docker 编排方式来部署，这也是目前最省心、最好维护的方式。整套流程走下来大概二十分钟左右，适合给团队搭一套内部可用的视频会议系统。

3.1 准备环境与端口

服务器最低配置建议 2 核 4G 内存，带宽按实际并发人数估算。如果只是十几人内部使用，5Mbps 上行基本够用；如果是几十人培训或发布会场景，建议 50Mbps 以上，并且优先关注上行带宽。

需要开放的端口有三个关键位：TCP 80 和 443 给 Nginx 提供网页访问和证书签发；UDP 10000 到 20000 给媒体流传输使用。这里提醒一句，很多云服务器默认安全组只开了 80 和 443，UDP 端口容易漏掉，一旦漏掉就会出现“网页能打开但互相看不到人”的诡异问题。

安装 Docker 和 docker-compose 插件：

# 安装 Docker（如果还没有）
curl -fsSL https://get.docker.com | bash

# 安装 docker-compose 插件
sudo apt update
sudo apt install -y docker-compose-plugin

# 验证
docker --version
docker compose version

docker-compose-plugin 是 Docker 官方的 Compose V2 插件，用起来比老版的 docker-compose 命令更顺手，语法也完全兼容。

3.2 使用 Docker 快速部署

官方维护了一套 docker-jitsi-meet 仓库，直接用编排脚本部署特别方便。

# 拉取仓库
git clone https://github.com/jitsi/docker-jitsi-meet.git
cd docker-jitsi-meet

# 生成环境变量模板
cp env.example .env

编辑 .env 文件，有几个必改项。以下是我的配置示例：

# 域名配置，务必替换成自己的域名
PUBLIC_URL=https://meet.example.com

# 自动签发 HTTPS 证书
ENABLE_LETSENCRYPT=1
LETSENCRYPT_DOMAIN=meet.example.com

# 时区
TZ=Asia/Shanghai

# 组件间通信密码，自己生成随机字符串
JICOFO_COMPONENT_SECRET=替换为随机密码
JICOFO_AUTH_PASSWORD=替换为随机密码
JVB_AUTH_PASSWORD=替换为随机密码

# 媒体端口配置
JVB_TCP_HARVESTER_PORT=4443
JVB_UDP_PORT=10000

生成随机密码可以用 openssl rand -hex 16 ，一行命令搞定，别用太简单的字符串。

配置完成后，创建数据目录并启动所有服务：

mkdir -p ~/.jitsi-meet-cfg/{web/letsencrypt,transcripts,prosody/config,prosody/data,jicofo,jvb}

docker compose up -d

首次启动会自动拉取镜像、创建容器、申请 HTTPS 证书。整个过程可能需要几分钟，看到所有容器状态为 running 之后，就可以用浏览器访问自己的域名了。打开页面输入任意房间名，如果能看到自己的摄像头画面，说明整个链路已经通了。

3.3 关键配置项解析

部署完之后你会发现，相比复杂的手工编译安装，Docker 编排方式最大的好处是容器隔离、配置集中、升级方便。但 .env 里变量很多，新手容易一头雾水。这里挑几个和 Colibri 密切相关的配置重点说明。

ENABLE_LETSENCRYPT 和 LETSENCRYPT_DOMAIN 是 HTTPS 证书相关。证书签发的逻辑是 Nginx 容器启动时向 Let's Encrypt 发起申请，申请成功后会挂载到 web 目录下的 letsencrypt 文件夹里。如果证书一直没生成，先检查域名解析是否已经指向服务器 IP。

JICOFO_COMPONENT_SECRET 是 Prosody 和 Jicofo 之间的通信密钥，必须设置，否则两个组件无法握手。JICOFO_AUTH_PASSWORD 和 JVB_AUTH_PASSWORD 是内部组件认证密码，改不改都行，但建议设置，避免使用默认值。

JVB_TCP_HARVESTER_PORT=4443 是媒体桥的 TCP 回退端口。某些网络环境 UDP 被封，用户端会自动尝试 TCP 方式连接媒体桥。这个值在 WebRTC 领域叫作 ICE-TCP candidate，属于备用方案，但对移动网络用户和严格防火墙环境来说非常重要。

JVB_UDP_PORT=10000 是媒体桥的 UDP 端口起点。默认会占用 10000 到 20000 这一段区间，云服务器的安全组里必须放行。我之前碰到过一种很奇怪的现象，网页正常、创建会议正常、但别人一加入就掉线，排查到最后发现就是安全组忘了开 UDP 端口。

容器启动完成后，检查各服务状态：

docker compose ps
docker compose logs -f jvb

看到类似 “JVB started” 或 “XMPP connection established” 的日志，说明 Videobridge 已经和 Prosody 成功建立连接，Colibri 协议通道处于就绪状态。

4. 把 Colibri 调得更好用

系统跑起来只是第一步，真正考验功力的是调优。Colibri 在默认配置下能用，但离“稳定扛住并发”还有距离。下面说几个我实际用下来比较关键的调整项。

4.1 核心机制拆解

从协议层面看，Colibri 和 Jicofo 之间的交互是典型的 XMPP IQ 消息流。Jicofo 向 Videobridge 发送 Colibri 指令，比如创建会议室、新增媒体通道、更新通道属性、销毁通道。Videobridge 收到指令后，在自己的内部状态表里维护一份“会议室-通道-端点”的映射关系。

每个参会者加入会议时，Videobridge 会为这个用户分配一个媒体通道，同时分配一组 SSRC（同步源标识符）。音视频流打到媒体桥后，Colibri 根据通道表把这些流转发给会议里的其他人。这个机制决定了它天然适合做大规模分发现场，因为它不混流、不转码，只是做 RTP 层的选择性转发。

但“不转码”也有代价。如果某个参会者的上行带宽很差，媒体桥不会主动帮你把清晰度降下来，画面就会卡顿。所以 Jitsi 在前端层面做了码率和分辨率控制，而 Colibri 在桥层面做的是多路媒体流的优先级管理——当资源不足时，优先保证音频流和屏幕共享流的传输，其次才保证所有人视频帧的完整度。

4.2 几个值得调整的参数

下面这几个参数我建议部署完成后就调好，避免正式使用时出问题。

配置项	建议值	说明
ENABLE_SIMULCAST	1	开启多播流，允许同一路视频按不同码率分发给不同终端
JVB_OPTS	-Xmx2g	设置媒体桥 JVM 最大堆内存，避免 OOM
JVB_TCP_HARVESTER_PORT	4443	TCP 回退端口，移动网络必须保留
ENABLE_AVMODERATION	1	开启音视频管理权限，主持人可控麦
ENABLE_BREAKOUT_ROOMS	1	开启分组讨论房间功能

ENABLE_SIMULCAST 是很多人忽略但特别重要的配置。开启后，媒体桥会接收同一路视频的多层编码流，根据每个接收端的带宽情况选择合适的一层转发。画质和流畅度之间的平衡就靠它来调。不开的话，所有参会者接收到的码率几乎一样，网络差的人和网络好的人互相拖累。

JVB_OPTS 里设置 -Xmx2g 是给 Jitsi Videobridge 的 Java 进程分配内存。默认值可能偏小，并发人数上来以后容易出现频繁 GC 导致的卡顿，甚至直接 OOM。建议 4G 内存的服务器给到 2G，8G 内存给到 4G。

4.3 并发与性能规划建议

关于并发数，官方没有给出特别严格的数字，因为服务器配置、带宽、是否开启视频、分辨率设置都会影响最终性能。我实测下来的经验是：2 核 4G 内存的机器，纯音频能扛住 100 人；开启视频并保持 720p 分辨率，20 到 30 人比较稳妥；4 核 8G 内存，视频并发可以到 50 到 80 人。

这里有一个核心瓶颈需要单独强调：带宽。媒体桥转发视频流时，上行带宽的消耗是“参会人数×每路上行码率”。如果 20 个人都开摄像头，每人按 1Mbps 算，媒体桥需要约 20Mbps 的上行带宽。这是很多人部署完后发现“CPU 不高但视频一直卡”的根本原因。

如果确实需要支撑大并发，横向扩展是一个值得考虑的方向。Jitsi 支持部署多台 Videobridge 节点，通过 Colibri 协议由 Jicofo 统一调度，把不同会议分散到不同媒体桥上。配置上需要安装 jitsi-videobridge 节点并修改 Prosody 配置，让会议焦点组件感知到新节点，这比单机调优的收益大得多，但复杂度也会明显上升。

5. 常见问题与排查实录

最后分享一些实际部署和运行中常见的问题，以及我的排查思路。这些坑如果不提前了解，出问题时很容易让人手足无措。

5.1 典型故障速查

现象	可能原因	排查方法
网页能打开，但进入会议后一直转圈	Prosody 或 Jicofo 异常	查看 docker compose logs 中 prosody、jicofo 日志
有画面没声音，或者声音断断续续	UDP 10000-20000 端口未放行	检查云服务器安全组，确认 UDP 端口范围
别人加入后直接在会议中消失	STUN/TURN 配置缺失或网络 NAT 类型严格	检查 .env 中 ENABLE_IPV6、TURN 相关配置
视频画面模糊，网络好也模糊	码率限制过低或未开启 SIMULCAST	检查 ENABLE_SIMULCAST=1，提高码率配置
连接经常掉线，需要重新加入	媒体桥内存不足或带宽打满	查看 JVB 日志和系统带宽监控
证书未自动续期，访问提示不安全	DNS 未指向服务器或 443 端口不通	用 curl 和 dig 检查域名解析与端口连通性

这里面最常见的还是 UDP 端口问题。很多云厂商的安全组默认只放行 TCP，UDP 全被挡在外面。WebRTC 的音视频传输默认走 UDP，端口一挡，媒体流就传不过去。表现症状很容易和“服务器性能不行”混淆，其实换一台高配服务器也解决不了。

5.2 一次真实排障过程

我印象比较深的一次故障是这样的：客户反馈视频会议到了十个人左右就开始卡顿，主持人说话断断续续，共享屏幕干脆花屏。我第一反应是媒体桥扛不住，登录服务器一看 CPU 只有 30%，内存也很健康，明显不是性能瓶颈。

继续看网络，云主机带宽显示一直跑满在 5Mbps 附近，而上行带宽的消耗恰恰是主要问题。十个人同时开摄像头，按每路 500Kbps 的码率算，媒体桥上行就需要 5Mbps，已经顶到带宽上限。共享屏幕一开，带宽瞬间被打爆。

解决办法分两步：第一步在服务端开启 SIMULCAST 并调整码率上限，让媒体桥按接收端情况分发不同质量的流；第二步把云主机带宽从 5Mbps 提升到 20Mbps，给会议留出冗余空间。调整后问题立刻消失，二十多人的会议也一直稳定。

还有一次更隐蔽的问题，PC 端能正常开会，手机端进去就白屏。查了半天发现是 Nginx 容器里的 WebSocket 配置和移动端网络代理有冲突。后来检查发现，手机端走的是蜂窝网络，网络运营商对 UDP 做了严格限制，但 TCP 4443 回退端口之前没配置好，导致媒体连接一直建不起来。配置好 TCP 回退后，移动端也能正常开会了。

排查这套系统的问题，我总结了一个比较实用的顺序：先确认服务状态，再看端口连通性，然后看带宽，最后才考虑性能调优。大部分问题都出在前三层。

最后说一点个人感受吧。Colibri 这名字起得确实很贴切，蜂鸟看起来小巧，但翅膀一秒钟能扇几十下，这台媒体桥在开会时就是这么高频地在处理各路音视频流的转发。第一次部署我盯着日志看了半小时，才真正理解它为什么是整条链路里最不能倒的一环。如果你也准备自建一套会议系统，建议先把 Colibri 的日志和端口行为摸清楚，再上生产。这套系统跑起来之后，后期维护会轻松很多。