第一次在抓包里看到 http://jitsi.org/protocol/colibri 这个命名空间时，我正盯着一场四十多人的线上评审会：画面在轮播到第三个人的时候卡成幻灯片，声音却一直是通的。那一刻我意识到，问题大概率不在编解码器，也不在带宽——而在 colibri 这一层：它是整套实时音视频系统里那个"发号施令"的控制平面，决定了谁该收到几路流、每一路该发多大的分辨率、哪一路该被丢掉。很多人调了半年参数，却从没真正打开过 colibri 的报文看一眼，这就是卡顿反复出现的根源。

colibri 不是编解码器，也不是传输协议，它更像一个"调度台"。它跑在会议控制服务和媒体转发服务之间，用一套结构化的指令完成三件事：给每个参会者分配音频、视频、数据的通道；告诉转发服务每个通道的方向、码率和层级；在会议规模变化时动态收回或扩容这些通道。理解它之后，你会发现很多"玄学卡顿"其实都能被解释——比如为什么十个人的会议很稳、二十个人就开始糊，为什么移动端用户总是被降级，为什么某些人上不来画面但声音正常。这篇内容适合三类人：自己搭建过实时音视频服务、想搞懂参数背后逻辑的运维和开发；被线上会议质量问题反复折磨、想系统性排查的技术负责人；以及想深入理解 SFU 架构的控制面设计的工程师。下面我按"概念—报文—调参—排查"的顺序，把我踩过的坑和验证过的取值一次讲透。

1. Colibri 到底是什么：从一次四十人会议的卡顿说起

1.1 名字背后的设计取向：蜂鸟式的"轻"

colibri 这个名字取自蜂鸟，含义很直白：体积小、振翅快、能耗低。把这个取向放到实时音视频系统里，它对应的是控制面的三条设计原则。第一是 指令要小 ，控制消息不能和媒体流抢带宽，所以整套协议基于结构化的短报文而非长连接流式推送；第二是 状态要可过期 ，每一个通道都带有效期，端点异常掉线时不需要额外的清理逻辑，超时自动回收；第三是 决策要集中、执行要分布 ，谁来看哪几路流这种全局最优问题交给一个中心节点算，具体怎么转发交给媒体服务自己处理。

这三条原则直接决定了它和传统方案的分野。早期多点会议用的是 MCU 模式，服务器把所有流混成一路再发下去，控制面很简单，但服务器 CPU 被编解码吃干，十路以上就撑不住，而且无法做个性化的布局。SFU 模式改成"服务器只转发不混合"，控制面立刻变得复杂：同一个发布者的视频要同时以三种分辨率存在，不同接收者拿到的组合完全不同。colibri 就是为这种复杂度准备的——它不解决"怎么编码"，只解决"谁该拿到什么"。我在实际项目里最直观的感受是：MCU 时代的瓶颈是 CPU，SFU 时代的瓶颈是控制决策和带宽，而 colibri 恰好站在后者的正中央。

1.2 控制平面与数据平面：Colibri 到底管什么

把整套系统拆成两层会清晰很多。 数据平面 负责搬字节：音频的 RTP 包、视频的 RTP 包、RTCP 反馈包，以及需要可靠传输时的数据通道，它们在媒体服务里只是被转发，不做解码。 控制平面 负责下命令：创建会议、分配通道、指定层级、销毁通道。colibri 的全部工作都在控制平面，它本身不搬运任何一个媒体包。

这个边界非常重要，因为它决定了排查方向。当你遇到"声音忽大忽小"这种连续性问题时，八成是数据平面的事——网络抖动、拥塞控制、丢包重传，去看 colibri 报文基本没有收获。但如果是"某人一直只看到最低清晰度""切到全屏之后五秒才变清楚""三十人以上会议大面积降级"这类 离散的、与个体相关的 问题，那几乎一定能在 colibri 的指令里找到答案：要么是层级选择被限制住了，要么是通道压根没分配成功，要么是约束条件下发得太保守。

我自己总结的一条经验是： 连续变化的问题往数据平面找，突变和分化的问题往控制平面找 。这句话帮我省了无数个小时。colibri 的报文本身信息量很大，一次完整的会议分配指令里带着会议标识、端点标识、通道方向、负载类型、同步源编号、层级结构、传输参数，把它完整读一遍，基本能还原出"服务端此刻是怎么看这场会议的"。

2. 核心概念拆解：把 Conference、Channel、SSRC 三层抽象理清

2.1 Conference 与 Endpoint：会议的两级抽象

colibri 的模型是标准的两级结构： Conference（会议） 是最外层容器，对应一个房间； Endpoint（端点） 是容器里的成员，对应一个参会者的一次连接。这里有个容易被忽略的细节：端点标识通常绑定的是"这一次连接"而不是"这个人"。同一个人用手机进来、又用电脑进来，就是两个端点；刷新页面重连一次，也会拿到新的端点标识。这一点直接影响日志排查——你按人名去搜日志经常搜不到，得按端点标识搜。

为什么这么设计？因为媒体转发服务的资源分配单位就是连接本身。一个端点的上行走一路、下行可能走十几路，这些通道的生命周期必须和连接严格绑定。如果按"人"去做抽象，重连时的资源回收会变得极其麻烦——你不知道旧连接是真的断了还是只是网络抖动，也不知道新的连接是不是要继承旧的通道。用端点做单位，"过期即回收"这一条就够了。

注意：端点标识在同一个会议内唯一，但跨会议不唯一。做日志关联时一定要带上会议标识，否则会撞车。

2.2 Content / Channel / Transport：媒体怎么被"分包"管理

在 Conference 和 Endpoint 之下，colibri 用 Content 把通道按用途分组，最常见的是音频组、视频组、数据组。每一组里挂着若干 Channel（通道） ，通道才是真正描述"一路媒体"的实体。一个通道上会标注这些关键属性：

属性	含义	实际影响
通道标识	该通道在本会议内的唯一编号	日志检索的主键
端点标识	归属的参会连接	判断是谁的流
方向	发送、接收或双向	决定通道是否需要建立下行
有效期	多久不续期就回收	影响掉线后的资源释放速度
负载类型	编码格式与采样参数	不匹配会直接导致无声无画
同步源编号	媒体流的身份标识	下行选层时的核心依据
通道捆绑	是否复用同一组传输	影响连接数和握手开销
中继方式	转发还是混合	决定服务端 CPU 开销

通道捆绑 这一项值得单独说。现代方案普遍把音频、视频、数据塞进同一组传输通道，只做一次连接协商。好处是握手次数从"每个流一次"降到"每个端点一次"，在几十人的会议里，这个差距是几百次协商和几十次协商的区别。代价是耦合度变高：传输层一旦出问题，音频、视频、数据会同时受影响。我在生产环境里遇到过一次"声音断断续续同时屏幕共享也卡"的故障，最后定位到就是这组共享传输的某个路径出了问题，而不是三条独立的通道各自故障——如果不知道捆绑机制，很容易往三个方向同时排查，白白浪费时间。

2.3 SSRC、Simulcast 与 LastN：三个真正决定观感的旋钮

如果只能记住三个概念，就是这三个。

同步源编号 是媒体流的身份证。同一个发布者的摄像机原始流有一个编号，经过多层编码之后，每一层都会有自己的编号。转发服务不关心"这是张三的视频"，它只认编号，收到下行的选层指令时说"请给我编号 X 这一路"。这解释了为什么发布者刷新页面之后，接收端会短暂黑一下——编号变了。

Simulcast（多层同播） 是发布端同时发出多路不同分辨率的视频。常见配置是三档，大致对应低、中、高三个清晰度档位。发布端把三层同时上送，转发端按需下发其中一层。这里的关键是 上送的总带宽是三层之和 ，很多人只算了高层的码率，结果发现上行总是超限，就是这个原因。

LastN 是接收端同时接收的视频路数上限。它不是"最多看到几个人"，而是"最多同时接收几路视频数据"——超出这个数的参会者不会黑屏，而是退化成只发静帧或直接不接收，界面上通常表现为头像占位。这个参数是整套系统里性价比最高的旋钮：把它从 50 降到 8，服务器出向带宽能直接砍掉大半，代价只是看不到后排同学的表情。

提示：LastN 和"舞台上的人"是两套机制。通常舞台成员会被强制保留在接收列表里，剩余名额才按活跃度分配。调参时别只改 LastN，忘了舞台相关配置。

3. 协议交互实操：完整拆解一次频道分配

3.1 一次分配请求的报文逐字段解读

colibri 的指令走的是结构化的 XML 消息（在 Jitsi 系技术栈里通过 XMPP 传递），下面是我在实际抓包基础上简化过的一段分配请求。字段做了删减，但结构是真实的：

<conference xmlns="http://jitsi.org/protocol/colibri"
            id="8f3c9a2e7b41"
            name="review-room@conference.example.internal"
            create="true">
  <content name="audio">
    <channel id="a17" endpoint="7e2f4d19" initiator="true" expire="20">
      <payload-type id="111" name="opus" clockrate="48000" channels="2"/>
      <ssrc>1837462910</ssrc>
    </channel>
  </content>
  <content name="video">
    <channel id="v17" endpoint="7e2f4d19" initiator="true" expire="20">
      <channel-bundle id="bundle-7e2f4d19">
        <transport xmlns="urn:xmpp:jingle:transports:ice-udp:1">
          <!-- 传输候选、凭据等参数省略 -->
        </transport>
      </channel-bundle>
    </channel>
  </content>
</conference>

逐层看：最外层 conference 上的 id 是会议在转发服务里的内部编号， name 是房间的可读名称， create="true" 表示这次请求顺带创建会议——如果会议已存在，这个标志会被忽略，不会重复创建。这一条是我在排查"重复建会"问题时的重要线索：日志里如果反复出现带创建标志的请求，说明控制服务认为会议不存在，通常是内部状态不同步。

content 层按用途分组，一个端点通常会同时出现在音频组和视频组里，这也解释了为什么"只有声音没有画面"是一种很常见的故障形态——音频通道建立成功了，视频通道失败了，两条路径是独立的。

channel 层是核心。 initiator="true" 表示这个端点主动发起了传输协商，需要由它提供传输参数； expire="20" 是有效期秒数，意味着这个通道如果没有在二十秒内被续期，转发服务就会把它回收。这个设计让整个系统对异常掉线极其宽容：客户端崩溃、网络消失、进程被杀，都不需要额外的清理动作。

payload-type 描述负载格式，音频一般是 48kHz 采样的 opus，编码标识在双方之间必须一致，否则会出现"信令显示连接成功但完全没声音"的现象。 ssrc 就是前面说的媒体流编号。 channel-bundle 把音频和视频挂在同一个传输上，配合内部的传输参数完成一次连接协商。

3.2 Colibri WebSocket：桥到端点的那条反向通道

只有"分配"这一半是不够的。转发服务还需要在运行中把一些信息推给端点：某个人的网络状态变了、当前生效的接收路数改了、舞台成员列表更新了。这些消息走的是另一条路径—— Colibri WebSocket 。它不是用来传媒体的，媒体永远走 RTP，这条通道只传控制消息，通常是 JSON 格式。

下面是一条客户端向上报接收约束的消息，这个格式在生产环境的抓包里非常常见：

{
  "colibriClass": "ReceiverVideoConstraints",
  "lastN": 25,
  "selectedEndpoints": ["7e2f4d19"],
  "onStageEndpoints": ["7e2f4d19", "a91c3b55"],
  "defaultConstraints": { "maxHeight": 360 },
  "constraints": {
    "7e2f4d19": { "maxHeight": 720 }
  }
}

这条消息的信息量极大。 lastN 覆盖当前接收路数； onStageEndpoints 声明哪些人必须保留； defaultConstraints 给所有普通参会者设了清晰度上限； constraints 单独给舞台上的人开了 720 的口子。 这就是"舞台上的人更清晰"这个产品体验的技术实现 ——不是转发服务猜的，是客户端明确告诉它的。

反向下发的消息类型也值得熟悉，我用得最多的有三种：端点连通状态变化，用来判断某个人是否掉线；接收路数变更通知，用来确认服务端是否接受了我上报的约束；舞台成员变更通知，用来确认布局切换是否生效。当界面表现和预期不一致时，我第一件事就是看这三类消息有没有按预期到达，这一招比翻转发服务的日志快得多。

注意：这条控制通道和媒体通道是相互独立的。它会断，断了之后媒体可能还在继续走。表现就是"画面和声音都在，但布局切换、静音状态、举手提示全部失灵"。看到这种组合症状，先查控制通道，别去查网络质量。

3.3 从进房到出画：一条完整的时间线

把前面的概念串成一条线，一次加入会议大致是这样走的：

1. 端点连上信令服务，拿到房间信息和转发服务地址；
2. 控制服务向选定的转发服务发出创建会议的指令，带上会议标识；
3. 控制服务为这个端点分配音频通道和视频通道，带有效期，同时挂上传输参数；
4. 端点完成传输协商，开始上送多层视频；
5. 转发服务上送成功后，把每个层级的媒体流编号回报给控制服务；
6. 端点通过控制通道上报它想接收哪些人、什么清晰度；
7. 控制服务据此向转发服务下发选层指令，转发服务按编号取层下发；
8. 会议进行中，通道被周期性续期，约束条件随布局变化不断更新。

这八步里， 第五步是最容易被忽视但最关键的一环 。多层视频的每一个层级编号只有在转发服务真正收到码流之后才有意义。如果某一层始终没有到达，那么即使前四步全部成功、界面显示一切正常，接收端也永远拿不到那一层。我见过好几次"最高清晰度永远出不来"的案例，最后都指向第五步——不是选层逻辑错了，是发布端把高层送丢了。排查方法很朴素：直接对比发布端统计里的编码层数和转发服务记录的层级编号数量，对不上就是上送环节的问题。

4. 自建调优：把 Colibri 参数调到"够用又不浪费"

4.1 基础部署与端口规划

自建之前先把端口算清楚，这一步没做好的话后面会出现各种"信令通了但媒体不通"的迷惑现象。下面是我在单机部署时的规划，实际生产环境会拆成多机：

端口	协议	用途	是否对外开放
443	TCP	网页与控制通道入口	是
80	TCP	跳转与证书校验	是
10000	UDP	媒体主通道	是
4443	TCP	媒体回退通道	是
5222	TCP	内部信令连接	否
5347	TCP	组件间注册与指令下发	否
8080	TCP	转发服务本地管理与统计接口	否
9090	TCP	指标导出	否

配置分两个文件，转发服务侧我当前用的写法是这样：

videobridge {
  ice {
    udp {
      port = 10000
    }
    tcp {
      enabled = true
      port = 4443
    }
  }
  apis {
    rest {
      enabled = true
    }
  }
  websockets {
    enabled = true
    domain = "meet.example.internal:443"
    server-id = "jvb-1"
  }
}

控制服务侧的桥接选择策略是另一个关键项：

jicofo {
  bridge {
    selection-strategy = SplitBridgeSelectionStrategy
    # 其余策略：RegionBasedBridgeSelectionStrategy / IntraRegionBridgeSelectionStrategy
  }
}

选择策略怎么选？ 单机部署随便，多机就有讲究了。让所有人挤到一台桥上的策略（ IntraRegionBridgeSelectionStrategy ）延迟最低，因为参会者之间的转发路径最短，但一旦这台桥出问题就是整场会议全挂。把参会者拆到不同桥上的策略（ SplitBridgeSelectionStrategy ）容错更好，代价是跨桥转发会多一跳延迟，而且桥之间的互联带宽要单独规划。我自己的取舍标准是： 二十人以下的内部会议优先低延迟，跨地域的大型直播优先容错 。别指望一个策略通吃。

4.2 带宽、simulcast 与 lastN 的取值逻辑

这三个参数是一组的，必须一起调。先做一道算术题。假设多层视频配置为三档，通俗说就是低、中、高，经验码率大约分别是 0.2、0.6、1.6 Mbps 这个量级（实际会随画面复杂度上下浮动 30% 以上）。那么：

• 发布端上行 = 三档之和 ≈ 2.4 Mbps。这是每个参会者的上行门槛。上行只有 2 Mbps 的用户，你逼他发三层就是在制造丢包，正确的做法是砍掉最高层，只发两级。
• 接收端下行 = 每一路被选中的层级的码率之和。如果一个人接收 5 路，其中 1 路是高层、4 路是中层，下行 ≈ 1.6 + 0.6×4 = 4.0 Mbps。
• 转发服务总流量 = 所有人的下行之和，这也是真正压垮服务器的那个数字。

按这个模型，一场二十人的会议，假设平均每人在舞台上待一小段时间、平均接收 5 路（1 高 4 中），出向流量大约是 20 × 4 = 80 Mbps，入向是 20 × 2.4 = 48 Mbps，合计约 128 Mbps。这个估算肯定不精确，但足够做容量判断了。

LastN 怎么定？ 我的取值经验是：纯语音会议场景设 0 到 2；普通讨论会设 8 到 12，此时界面上大约能看到 8 到 12 个活动画面，其余用头像占位；需要看大量参会者状态的场景（课堂、大规模评审）设 25 到 30；再往上就没什么收益了，人的注意力本来就分不了那么多块，带宽却会线性涨。

层数怎么定？ 带宽紧张的环境下砍掉最高层是最划算的一刀——两档配置能把每人的上行从 2.4 降到 0.8 Mbps，降幅接近三分之二。我的建议是给低带宽用户默认下发两档，把第三档做成"用户主动开启的高清模式"，也不要指望它自动出现。

还有一个参数值得开： 层级挂起 。它的作用是当没有任何接收者需要最高层时，让发布端暂停编码这一层，省下上行带宽和端侧 CPU。开与不开的差别在小型会议里不明显，但在"很多人都只看舞台、不看其他人"的场景下，上行能省掉三成左右。我最初没开这个开关，直到有一次发现手机端参与者的发烫问题很严重，查到最后是这个原因。

4.3 压测与容量估算：一台桥能扛多少人

先说结论： 人数不是容量指标，流量和流的条数才是 。一台 1 Gbps 网卡的机器，按前面二十人会议约 128 Mbps 的估算，理论上能装 5 到 6 场这样的会议，但我只会安排 2 到 3 场。原因有三点：媒体流量是突发型的，画面剧烈变化时码率会瞬间翻倍；RTCP 反馈包和控制消息会额外占用一部分；以及一旦接近网卡上限，丢包带来的重传和降级会形成恶性循环，体验断崖式下跌。

压测我用的是最土的办法：用脚本模拟若干端点加入同一场会议，逐步增加数量，同时记录三项指标—— 转发服务的出向流量、丢包率、以及被降级的端点占比 。降级占比这个指标最有用，它直接反映用户体验；当它开始超过 10%，我就认为这台桥到顶了。这个阈值是我自己定的，不同业务能接受的程度不一样，但有个明确的数字比凭感觉强太多。

工具有两个我常用：一个是专门做实时通信压力测试的合成客户端工具，能模拟大量端点收发；另一个是通用的 UDP 流量生成工具，用来单纯压网卡。前者测端到端体验，后者测网络上限，两个结果一对比就知道瓶颈在软件还是网络。

提示：压测时一定要同时看发布端和接收端的统计，只看一边很容易得出错误结论。我踩过一次坑：服务端流量上不去，一度以为是转发性能不行，结果是模拟客户端本身编码能力不足，压根发不出来那么大的码流。

5. 常见问题与排查实录

5.1 典型故障速查表

下面这些是我这几年的高频问题，按"症状—可能原因—验证方法"整理，可以直接当速查表用：

症状	优先怀疑	验证方法
有声音无画面	视频通道未分配成功或负载类型不匹配	比对音频与视频通道的分配记录
最高清晰度永远出不来	高层码流未上送，或层级编号未回报	比对发布端编码层数与服务端记录的层数
布局切换无效、静音失灵	控制通道断开	检查控制通道连接状态，观察是否仍有心跳
大量用户被降级	LastN 或清晰度上限设置过保守	抓取上报的约束消息，看下发值
掉线后资源长时间不释放	有效期设置过长	检查通道有效期与续期日志
三十人以上会议整体变糊	转发服务出向带宽见顶	观察出向流量曲线与丢包率
跨桥参会者延迟明显偏高	桥接选择策略导致跨区域转发	检查会议成员分布在哪几台桥
移动端发烫、耗电快	层级挂起未开，端侧持续编码高层	检查该开关状态与端侧上行流量

这张表我用了两年多，覆盖了大概八成现场问题。剩下的两成通常需要抓完整报文，那就得把第 3 章的报文结构背熟。

5.2 我是怎么用日志把问题逼到角落的

排查这类问题有个顺序千万别搞反： 先看控制面，再看数据面，最后才看网络 。我见过太多人一上来就抓包看丢包率和抖动，折腾两小时才发现是通道压根没分配成功——数据面本来就没数据，谈什么网络质量。

具体到日志，我关注的顺序是这样的。第一，看这次会议有没有成功创建，重连频繁的会议经常在这里出问题；第二，看目标端点的通道有没有分配记录，包括音频、视频、数据三类，缺哪类就对应哪类症状；第三，看层级编号的回报记录，数量对不对、有没有缺层；第四，看约束条件的下发和上报，是不是存在"客户端要了但服务端没给"或者"服务端给了但客户端没收到"；第五，才轮到统计接口里的丢包、抖动、码率曲线。

有一个信号特别好用：如果"端点连通状态"这条消息反复在同一个端点上出现"断开—恢复"的交替，那基本可以确定是这个端点的网络在抖，而不是服务端的问题。这类消息比任何流量图表都直接，因为它反映的是转发服务自己的判断。

我印象最深的一次故障是"某个会议室每逢整点前后就会集体降级"。日志里看不出任何异常，最后是把它和定时任务表对照才发现：整点有一批数据同步任务在跑，把出口带宽吃掉了。这种问题不是 colibri 能解决的，但通过观察降级是"集体的、同步发生的"而不是"个体的、随机的"，就能快速把方向从控制面转到基础设施侧。 群体性、同步性的事件，往往和代码无关；个体性、随机性的事件，才更可能是参数和协议层面的问题。 这条判断准则帮我省了很多时间。

5.3 几个文档里不会写的细节

最后说几个我觉得最值钱的经验，都是文档里不会明说的。

第一，别在生产环境直接调 LastN 做实验。 这个参数的影响是全局的、瞬时的，一改所有在线会议立刻重新选层，画面上会有一次明显的清晰度跳变。真要调，先在一场只有自己的测试会议里验证，再考虑灰度。

第二，通道有效期的续期节奏比数值本身更重要。 有效期设得太短、续期间隔又没跟上，会出现"周期性断流再恢复"的诡异现象，看起来像网络抖动，其实是自己有节奏地回收了通道。我的做法是让续期间隔保持在有效期的三分之一左右，留足两到三次重试机会。

第三，控制通道和媒体通道的健康检查要分开做。 它们可能一个通一个断，合并成一个健康检查会让你永远定位不到问题。

第四，容量规划要按"峰值叠加"算，不能按平均值算。 上午十点和下午三点的两场大会如果可能重叠，就必须按叠加后的流量准备，否则其中一个会议的质量一定会被另一个拖累。我吃过这个亏，事后复盘发现所有单场会议的容量都是够的，问题出在时间重叠。

第五，多层视频的档位不要设得太密。 三档已经足够，五档意味着发布端要多编两路，端侧 CPU 和上行带宽的代价远大于那点清晰度提升。我试过四档，实测观感提升几乎察觉不到，反而让低端设备的参与率明显下降。

如果后续还要继续深挖，我建议的方向是把这个控制面和端侧的拥塞控制反馈结合起来看——控制面决定"给不给"，拥塞控制决定"能不能到"，两者之间的时序错配才是很多疑难问题的真正来源。我自己现在的做法是在排查笔记里同时记录这两类事件的时间戳，对比几次之后，很多原本说不清的抖动就有了合理的解释。