凌晨两点零七分我盯着满屏滚动的日志第一次认真打量 colibri 这个词。那时候我对这套会议系统的理解还停留在这是一个跑在服务器上的 Java 服务这个粗浅层面只知道它负责把大家的音视频转发出去。直到那天晚上一个二十多人的会议突然集体卡顿我才顺着日志里反复出现的 colibri 字样一路挖到了这套开源会议方案里最核心、也最少被讲清楚的一层Colibri——Conference Link Bridge会议链路桥接层。这篇内容不打算复述官方文档里那些干巴巴的接口定义而是把我自己从自建、压测到排障踩过的路径完整写出来。它适合已经跑通基础部署、想让会议质量再稳一档的运维和音视频方向的开发者看如果你只是想快速搭个能用的会议环境前面几节也能帮你建立正确的认知框架避免后面调参时抓瞎。1. Colibri 不是蜂鸟它是 Jitsi 里管链路的那层第一次听到 Colibri 这个名字很多人会以为是某个独立产品或者干脆联想到西班牙语里的蜂鸟。这个联想其实不算错——项目组取名时确实借了蜂鸟小、快、悬停精准的意象但它的正式含义是Conference Link Bridge会议链路桥接。它不是一个你能单独下载运行的软件而是这套会议系统内部的一层抽象负责描述这场会议里谁和谁之间需要建立什么样的媒体链路以及这条链路现在是什么状态。1.1 三个角色管人的、管流的、和它们之间的语言要理解 Colibri先得把会议系统里三个角色摆清楚。我用一张表把它们的分工列出来这张表是我自己排障时画在纸上的比任何架构文档都管用。角色职责我常用的类比会议控制组件Focus决定谁能进会、谁在发言、给每个端下发哪些流会议主持人兼调度员视频桥Videobridge简称 JVB真正转发音视频 RTP 包、做带宽估计和选层会议室里的调音台Colibri前两者之间的协议与控制层调度员和调音台之间的对讲机关键在于控制组件自己不碰媒体流它只发指令视频桥自己不做该给谁看谁的决策它只执行。两者之间靠 XMPP 上的 Colibri 协议通信。控制组件发出给这个端点分配一条音频通道、两条视频通道的消息视频桥回一条通道建好了这是 ICE 参数和 DTLS 指纹然后媒体才真正开始流动。这里有个新手特别容易搞混的点Colibri 既是协议XMPP 上的一组消息扩展命名空间是http://jitsi.org/protocol/colibri也是视频桥内部的一层实现早年代码里叫ColibriConference、ColibriEndpoint这些类。所以在日志里看到 colibri 前缀可能是协议消息也可能是内部状态变更得结合上下文判断。我一开始就吃过这个亏把内部日志当成了协议交互去分析白白浪费了一个多小时。1.2 一次真实排障为什么日志里全是 colibri回到那个二十多人的会议。用户反馈是人一多画面就糊声音也开始断续。我当时的第一反应是带宽不够但服务器出口带宽明明很富余CPU 占用也不高。于是我去翻视频桥的日志。日志里高频出现的几类 colibri 相关记录事后复盘看每一条都有明确含义通道创建和过期记录对应某个端点加入或离开会议通道参数更新记录通常伴随选层变化说明视频桥在给某个端下调清晰度带宽估计相关记录反映的是端上报上来的可用带宽变化一小批超时和重传指向传输层而不是媒体层。我把这几类按时间轴对齐之后问题就浮出来了并不是带宽不够而是下行方向给每个端点的选层策略出了问题——视频桥在某些时刻把高码率层推给了带宽并不够的端点导致这些端的下行拥塞反过来又影响了它们自己的上行反馈形成一个小循环。这个结论如果只看 CPU 和带宽曲线是永远得不出来的。这也是我想把 Colibri 单独拿出来讲的原因它是一层中间语言你不懂这层语言排障时就只能看外部指标猜懂了这层语言才能从日志直接读到系统在想什么。2. 拆开一条 ChannelColibri 协议的最小工作单元Colibri 协议里最核心的概念叫Channel中文一般翻成通道。理解它的最好方式是把它当成一条单向的媒体管道音频一个方向一条视频一个方向一条屏幕共享再一条。一个端点在会议里可能同时拥有好几条通道上行下行分开算。2.1 一条通道的两副面孔RTP 面和传输面我见过不少人在配置文档里看到通道这个词就默认它是个网络连接其实不对。Colibri 里的通道是分两层的这两层经常被混淆我把它们列清楚层面描述的内容典型字段RTP 层这条管道运什么格式的媒体、怎么标识、怎么反馈载荷类型、SSRC、RTP 头扩展、RTCP 反馈参数传输层这条管道的包怎么从 A 走到 BICE 候选、ufrag、pwd、DTLS 指纹、SRTP 参数举个具体的例子。当控制组件要求为某个端点建一条视频接收通道时视频桥需要回给它一整套信息这条通道用哪些载荷类型比如 VP8、VP9、H.264 各对应什么编号、这条通道的同步源标识是多少、需要协商哪些 RTP 头扩展比如音频电平、绝对时间戳以及这条通道走哪个传输通道——ICE 用什么用户名和密码、DTLS 用什么指纹。这里最容易踩的坑是很多人以为一个端点一个传输通道就够了实际上视频桥会把同一端点的所有通道打包在一个 bundle 里共享同一套 ICE 和 DTLS 传输。这个设计是为了减少连接数和握手开销。我第一次看协议消息时被channel-bundle这个结构绕晕了后来才明白它就是个打包盒。2.2 从分配请求到过期一条通道的完整生命一条通道的生命周期用协议里的词叫分配allocate和过期expire。这个过程的完整链路大致是这样控制组件发出一条请求里面包含会议标识、通道归属的端点、通道方向是接收还是发送以及一个过期时间视频桥收到后检查资源、生成传输参数返回一个打包盒里面含 ICE 和 DTLS 信息端拿到这些参数后直接和视频桥建立 ICE 连接、完成 DTLS 握手媒体开始流动端点离开或切换时控制组件发过期指令视频桥释放通道资源。过期机制是 Colibri 里一个很值得琢磨的设计。请求里带的那个过期时间不是说时间一到通道就断而是给了控制组件一个缓冲窗口——在这个窗口内如果端点又回来了通道可以复用省掉一次完整的 ICE/DTLS 握手。我在自建环境里调过这个窗口实测下来对用户刷新页面这种场景的体验提升很明显重连时间从接近一秒压到了两三百毫秒。提示不要为了更快重连把这个过期窗口调得过大。窗口越长视频桥占着不放的资源就越多大规模会议下会明显拉高内存占用。我的经验值是够覆盖一次页面刷新的时间就足够了。2.3 SCTP 为什么被塞进了传输层还有一个有意思的细节Colibri 的传输层里除了音视频用的 RTP还塞了一路基于 SCTP 的数据通道。这路通道跑的是会议里的文本消息、举手状态、端到端加密的辅助信息这些东西。为什么值得单独提因为 SCTP 的控制参数和 RTP 完全不同它有自己的流数量、缓冲区、重传策略。我遇到过好几次音视频都正常但聊天消息发不出去的诡异现象最后定位就是因为 SCTP 这一路的配置被单独改动了或者 MTU 设置导致数据包被分片后丢弃。排查时你能想到去翻传输层的 SCTP 参数能省掉大量时间。视频桥在近几年的重构里把这部分内部类名从 colibri 前缀换成了更直观的会议/端点命名但协议层的 channel 概念没变。所以如果你看到新旧两套文档别慌它们说的是同一件事。3. 自建环境里动 Colibri先分清你要调的是哪一支很多人一上来就问Colibri 的参数怎么调。这问题问得像汽车怎么开一样宽——你得先说清楚要调哪一块。在我实际操作的经验里和 Colibri 强相关的调优大致分成三支带宽估计、选层策略、以及传输本身。三支混在一起调基本上就是给自己挖坑。3.1 带宽估计、选层策略、传输三件事别混着调先把这三支的边界讲清楚因为这直接决定了你改哪个配置项带宽估计视频桥怎么判断某个端现在能承受多少码率。它依赖端上报的反馈比如接收端估计类反馈和传输层拥塞控制反馈。选层策略已知某个端只能承受低码率后视频桥从可选的多个清晰度层里挑哪一层给它。这一支涉及同时转发多少路、是否固定某路等策略。传输ICE 候选、UDP/TCP 端口、DTLS 这些纯粹的连通性问题。我踩过最典型的一个坑就是试图用调传输参数的方式去解决选层问题。当时的现象是部分用户画面糊我以为是端口或者连通性改了一圈 ICE 配置毫无改善。后来才明白用户是连上了只是视频桥主动给他降了清晰度——那是选层在起作用跟传输半毛钱关系没有。判断方法其实很简单如果用户能听到声音、能看到画面只是糊那是选层如果完全连不上、一直在重连那才是传输。3.2 端口与传输UDP 范围怎么定为什么要留 TCP自建场景里传输层最直接的配置就是端口。视频桥默认走 UDP端口通常是 10000 起。很多人会顺手把 TCP 也开上端口习惯用 443 之类的常见端口。我建议开着但要理解代价。先说 UDP 端口范围。视频桥在 ICE 阶段会从配置的范围里挑端口每个端点会话占用一对。理论上你能支持的并发端点数受端口数量限制。这里的计算不复杂假设你配了从 10000 到 10100那就是 100 个端口按每个会话占一个端口算大致能支撑上百个并发端点。但要注意端口回收是有延迟的尤其是异常断线的情况下。所以我在生产环境里从来不把端口范围压到刚好够用通常留出三到五倍余量。再说 TCP。开 TCP 的价值在于有些网络环境会拦截 UDP这时候 TCP 就成了兜底。代价是 TCP 的传输特性不适合实时媒体——它的重传和拥塞控制是为可靠传输设计的遇到丢包会越传越慢导致画面卡顿加剧。所以我的策略是TCP 只作兜底不作主力。配置上开一个独立端口但不要在负载均衡或防火墙策略上给它额外权重。还有一个容易被忽略的细节如果视频桥部署在 NAT 后面ICE 候选地址的收集需要额外配置。我见过有人把视频桥放在云主机上但没配公网地址映射结果所有端点都只能通过中继走延迟凭空多了几十毫秒。配置形如videobridge { ice { udp { port 10000 } tcp { enabled true port 4443 } nat { # 这里配置公网映射后的地址 } } }注意新版视频桥已经从传统的键值对配置迁移到这种分层配置格式如果你手上是旧文档会发现键名完全对不上。我的做法是先在测试环境跑一遍新格式确认生效后再推到生产不要凭旧经验硬改。3.3 Colibri WebSocket 为什么值得单独开一条线这是 Colibri 里我认为最值得单独讲的一个设计。除了 XMPP 上的通道管理消息视频桥和端点之间还有一条基于 WebSocket 的旁路通道专门用来快速传递选层相关的控制消息。为什么要单独开一条因为 XMPP 那条路要经过控制组件中转链路长、延迟相对高。而选层决策是随带宽变化高频波动的比如用户从 Wi-Fi 切换到移动网络的那一两秒内可选层可能连续变好几次。如果走 XMPP 中转等你消息到了网络状况早就变了。这条 WebSocket 通道的配置要和前端部署的域名对上证书也得匹配否则浏览器会直接拒绝连接。我第一次配的时候就是因为域名对不上导致选层消息发不出去现象是画面永远停在一个较低的清晰度从不自动变清。这个现象很有迷惑性因为音视频链路本身是通的。videobridge { websockets { enabled true domain meet.example.com:443 tls true } }排查这类问题我有个笨但有效的办法打开浏览器开发者工具直接看 WebSocket 帧。如果这条连接根本没建起来或者建起来但帧里没有选层消息那基本可以锁定是这条旁路的问题而不是媒体传输本身。4. 压测现场三个把会议搞糊的坑前面讲的是原理和配置这一节我讲实际踩到的坑。我特意把排查链路完整写出来因为排障的价值不在于答案是哪个参数而在于我是怎么一步步缩小范围的。直接给答案的文章你换一个环境就又不会了。4.1 坑一上行清晰度层全开下行集体崩盘现象描述我自己压测时让一个端点上推最高清晰度同时另外五个端点接收。结果五个接收端同时出现明显卡顿而发送端自己一切正常。我的第一反应是服务器转发能力不够但监控显示视频桥的 CPU 和出口带宽都远没到瓶颈。于是我把方向转到下行。排查链路是这样的。第一步确认接收端到底收到了几路视频。我从视频桥的统计里读每个接收端的通道状态发现每路接收端都在同时接收多路视频流而不是只接收那一路高清晰度的。第二步确认码率总和。把每一路的码率加起来明显超过了我预估的接收端下行能力。第三步确认选层策略是否在起作用。答案是在这个测试规模下选层策略没有预期中那么积极。根因就清楚了接收端下行能力有限但视频桥并没有及时把不必要的高码率层降下来导致下行拥塞进而触发接收端的反馈反馈又影响了整个会议的稳定性。修复方向有两个。一是收紧下行路数的上限让视频桥在接收端数量多时更主动地只转发少数几路二是调高视频桥对带宽反馈的敏感度让它更快响应。我两个都做了先调敏感度因为它是渐进式的风险小再调路数上限这个是硬约束效果立竿见影但需要评估用户体验。这里有个经验值可以分享在普通办公网络环境下我一般把下行视频路数上限控制在个位数同时确保被固定的那一路优先级最高。这样既能看清主要发言人又不会把下行带宽吃光。4.2 坑二固定端点和路数上限打架第二个坑更隐蔽。前面说到被固定的那一路优先级最高——这就是固定端点。用户在界面上点了某个参会者的视频放大期望这个人一直是高清的。但如果同时开启了下行路数上限并且上限设得很紧就可能出现固定端点被挤出去的情况。现象是用户点了放大某个人结果过几秒又自己缩回去了。用户当然会认为是 bug。排查起来很有意思。我一开始怀疑是前端的固定状态没同步查了半天前端逻辑没问题。后来去翻视频桥的日志发现固定指令是发出去了、也收到了但紧接着选层决策把这一路的清晰度降了。也就是说固定端点和路数上限两个策略在互相覆盖。根因是这两个策略的优先级没有理顺。修复方式很直接调整配置让固定端点在路数上限之外单独占一个名额也就是上限之外再加固定路。这样固定端点永远有位置。提示固定端点数量是有配置上限的默认一般是个较小的值。如果你的场景里用户喜欢同时固定好几个人的画面记得把这个上限相应调大否则后固定的人会顶掉先固定的人。4.3 坑三TCP 兜底开着但防火墙只放了一半这个坑在自建环境里极其常见而且极难从应用层看出来。现象绝大多数用户正常只有少数几个用户连不上或者只能听声音看不到画面。这些用户分布在不同网络环境里。排查链路。第一步看这些用户的连接方式。从视频桥日志里能看出他们是在走 UDP 还是 TCP。第二步对比成功和失败的连接方式发现失败的都走了 TCP。第三步直接测 TCP 端口连通性。结果发现防火墙规则里UDP 端口放行了TCP 端口只放行了入方向出方向或者返回路径没有正确配置。根因就是防火墙规则不完整。修复是补齐规则这里没什么巧劲就是把 UDP 和 TCP 两个端口、入和出两个方向都覆盖到。这个坑教给我一个习惯每次部署新环境我一定先用一个模拟受限网络的客户端手动测一遍兜底路径。因为主路径太顺了兜底路径的问题往往要等到真实用户报告才发现。5. 让 Colibri 的状态可见观测与端到端验证调参最怕的就是两眼一抹黑。Colibri 这层如果不做观测你改完配置只能靠感觉好像快了点来判断这在生产环境里是不可接受的。这一节讲我怎么做观测和验证。5.1 统计接口怎么开先看哪几个数视频桥本身能暴露统计信息可以推给监控系统。开启方式大致是在配置里打开统计开关并指定推送的目标地址和间隔。我的习惯是间隔不要太密十秒一次足够太密了自己给自己制造压力。打开之后先不要贪多盯住三组数就够了观测维度关注什么异常信号端点与会话当前会议数、端点数、通道数通道数增长但端点数不增可能是泄漏带宽与码率每路通道的实际码率、估计带宽实际码率长期贴着实测带宽上限传输质量丢包率、抖动、重传丢包率持续高于正常水平我最先盯的永远是通道数 vs 端点数这个比值。因为通道泄漏是 Colibri 这层最典型的一类问题——端点异常退出时过期流程没走完通道资源就挂在那里了。表现就是比值缓慢上升跑几天后内存吃紧。5.2 几组关键指标和它们的合理区间具体数值因环境而异我给出的是我自己在普通办公网环境下的经验区间你可以作为起点再调整下行丢包率稳定在很低的水平是正常的比如千分之几。一旦持续超过百分之一接收端就会明显感知卡顿。端到端延迟同城环境下几十毫秒是合理的。如果超过一百五十毫秒用户会开始抱怨像打电话一样抢话。带宽估计与实际码率的比值正常情况实际码率应该低于估计带宽留有余量。如果长期贴着估计值跑说明没有余量网络稍微一抖就会掉层。我给自己设的告警阈值是下行丢包率持续超过百分之一达一分钟就告警。这个阈值不是拍脑袋定的是我反复看用户投诉和指标曲线对齐后得出的比任何理论最优值都准。5.3 用 WebSocket 消息做一次端到端验证最后一招也是我最喜欢的验证方法直接在浏览器开发者工具里看那条 WebSocket 通道上的消息。为什么说它是端到端验证因为它能同时告诉你三件事选层决策有没有下发、下发得对不对、端点有没有响应。这三个环节任何一环断了你从 WebSocket 帧里都能看出来。具体做法是打开一个测试会议在开发者工具里过滤 WebSocket 连接观察帧的内容。正常情况下你应该能看到随着网络状况变化选层消息在动态调整。如果网络状况明显变差但消息纹丝不动说明决策没触发如果消息发了但画面没变化说明端点侧没响应。这套方法不需要任何额外的抓包工具成本极低我强烈建议每个做这块的人都掌握。6. 什么时候不该动 Colibri边界与常见误操作写到这里我想反过来讲一句Colibri 这层的参数能不调就不调。绝大多数会议体验不好的问题根因不在这一层盲目调参只会把一个可复现的问题变成一个不可复现的问题。6.1 先排除这三类非 Colibri 问题在动手改任何 Colibri 相关配置之前我要求自己先排除这三类前端编解码能力问题低端设备解码高清晰度视频本身就吃力这时候降清晰度是对的不是配置错了。用户终端网络问题单独某几个用户有问题大概率是他们自己的网络不是服务器。部署拓扑问题视频桥和控制组件之间的网络质量很多时候比视频桥到用户的链路更关键而且更容易被忽略。我有一次折腾了一整晚的选层参数最后发现是视频桥和控制组件之间的网络抖动导致控制消息延迟选层指令晚到了几秒。这种问题你在视频桥内部怎么调都没用。6.2 改动前必须留下的两样东西如果你确定要调那请务必留下两样东西改动前的基线数据和可一键回滚的配置版本。基线数据是为了对比。没有基线你改完之后凭感觉说好像好点了等于没改。我的做法是改动前至少采集一段完整的会议指标最好覆盖高峰时段。可回滚的配置则是保命。Colibri 相关的参数之间耦合度不低改一个可能连带影响另一个。我现在的习惯是所有配置都走版本管理改之前先提交一版改完观察二十四小时再决定是否保留。6.3 适合大规模会议的取值思路最后说一个思路性的东西不涉及具体数字。当会议规模从几个人涨到几十人时Colibri 这层的策略应该从尽量让每个人看清转向保证主要发言人清楚、其他人能看个大概。这不是妥协而是资源分配的必然。我自己的取值心法是先确定必须高清的人有几个把这块资源预留死剩下的资源再按人数均摊。按这个思路去调你会发现很多参数一下子就有方向了不再是凭感觉试数字。这套东西我前前后后踩了大概半年才理顺中间推翻过好几次自己的判断。真正让我进步的不是记住了哪个参数设多少而是学会了从日志和指标里读出系统在做什么决策。Colibri 这层之所以值得花时间就是因为它把决策过程都写在了你能看到的地方只是需要你先学会它的语言。 Jitsi Colibri 会议链路桥接：原理、排障与调优实战
凌晨两点零七分我盯着满屏滚动的日志第一次认真打量 colibri 这个词。那时候我对这套会议系统的理解还停留在这是一个跑在服务器上的 Java 服务这个粗浅层面只知道它负责把大家的音视频转发出去。直到那天晚上一个二十多人的会议突然集体卡顿我才顺着日志里反复出现的 colibri 字样一路挖到了这套开源会议方案里最核心、也最少被讲清楚的一层Colibri——Conference Link Bridge会议链路桥接层。这篇内容不打算复述官方文档里那些干巴巴的接口定义而是把我自己从自建、压测到排障踩过的路径完整写出来。它适合已经跑通基础部署、想让会议质量再稳一档的运维和音视频方向的开发者看如果你只是想快速搭个能用的会议环境前面几节也能帮你建立正确的认知框架避免后面调参时抓瞎。1. Colibri 不是蜂鸟它是 Jitsi 里管链路的那层第一次听到 Colibri 这个名字很多人会以为是某个独立产品或者干脆联想到西班牙语里的蜂鸟。这个联想其实不算错——项目组取名时确实借了蜂鸟小、快、悬停精准的意象但它的正式含义是Conference Link Bridge会议链路桥接。它不是一个你能单独下载运行的软件而是这套会议系统内部的一层抽象负责描述这场会议里谁和谁之间需要建立什么样的媒体链路以及这条链路现在是什么状态。1.1 三个角色管人的、管流的、和它们之间的语言要理解 Colibri先得把会议系统里三个角色摆清楚。我用一张表把它们的分工列出来这张表是我自己排障时画在纸上的比任何架构文档都管用。角色职责我常用的类比会议控制组件Focus决定谁能进会、谁在发言、给每个端下发哪些流会议主持人兼调度员视频桥Videobridge简称 JVB真正转发音视频 RTP 包、做带宽估计和选层会议室里的调音台Colibri前两者之间的协议与控制层调度员和调音台之间的对讲机关键在于控制组件自己不碰媒体流它只发指令视频桥自己不做该给谁看谁的决策它只执行。两者之间靠 XMPP 上的 Colibri 协议通信。控制组件发出给这个端点分配一条音频通道、两条视频通道的消息视频桥回一条通道建好了这是 ICE 参数和 DTLS 指纹然后媒体才真正开始流动。这里有个新手特别容易搞混的点Colibri 既是协议XMPP 上的一组消息扩展命名空间是http://jitsi.org/protocol/colibri也是视频桥内部的一层实现早年代码里叫ColibriConference、ColibriEndpoint这些类。所以在日志里看到 colibri 前缀可能是协议消息也可能是内部状态变更得结合上下文判断。我一开始就吃过这个亏把内部日志当成了协议交互去分析白白浪费了一个多小时。1.2 一次真实排障为什么日志里全是 colibri回到那个二十多人的会议。用户反馈是人一多画面就糊声音也开始断续。我当时的第一反应是带宽不够但服务器出口带宽明明很富余CPU 占用也不高。于是我去翻视频桥的日志。日志里高频出现的几类 colibri 相关记录事后复盘看每一条都有明确含义通道创建和过期记录对应某个端点加入或离开会议通道参数更新记录通常伴随选层变化说明视频桥在给某个端下调清晰度带宽估计相关记录反映的是端上报上来的可用带宽变化一小批超时和重传指向传输层而不是媒体层。我把这几类按时间轴对齐之后问题就浮出来了并不是带宽不够而是下行方向给每个端点的选层策略出了问题——视频桥在某些时刻把高码率层推给了带宽并不够的端点导致这些端的下行拥塞反过来又影响了它们自己的上行反馈形成一个小循环。这个结论如果只看 CPU 和带宽曲线是永远得不出来的。这也是我想把 Colibri 单独拿出来讲的原因它是一层中间语言你不懂这层语言排障时就只能看外部指标猜懂了这层语言才能从日志直接读到系统在想什么。2. 拆开一条 ChannelColibri 协议的最小工作单元Colibri 协议里最核心的概念叫Channel中文一般翻成通道。理解它的最好方式是把它当成一条单向的媒体管道音频一个方向一条视频一个方向一条屏幕共享再一条。一个端点在会议里可能同时拥有好几条通道上行下行分开算。2.1 一条通道的两副面孔RTP 面和传输面我见过不少人在配置文档里看到通道这个词就默认它是个网络连接其实不对。Colibri 里的通道是分两层的这两层经常被混淆我把它们列清楚层面描述的内容典型字段RTP 层这条管道运什么格式的媒体、怎么标识、怎么反馈载荷类型、SSRC、RTP 头扩展、RTCP 反馈参数传输层这条管道的包怎么从 A 走到 BICE 候选、ufrag、pwd、DTLS 指纹、SRTP 参数举个具体的例子。当控制组件要求为某个端点建一条视频接收通道时视频桥需要回给它一整套信息这条通道用哪些载荷类型比如 VP8、VP9、H.264 各对应什么编号、这条通道的同步源标识是多少、需要协商哪些 RTP 头扩展比如音频电平、绝对时间戳以及这条通道走哪个传输通道——ICE 用什么用户名和密码、DTLS 用什么指纹。这里最容易踩的坑是很多人以为一个端点一个传输通道就够了实际上视频桥会把同一端点的所有通道打包在一个 bundle 里共享同一套 ICE 和 DTLS 传输。这个设计是为了减少连接数和握手开销。我第一次看协议消息时被channel-bundle这个结构绕晕了后来才明白它就是个打包盒。2.2 从分配请求到过期一条通道的完整生命一条通道的生命周期用协议里的词叫分配allocate和过期expire。这个过程的完整链路大致是这样控制组件发出一条请求里面包含会议标识、通道归属的端点、通道方向是接收还是发送以及一个过期时间视频桥收到后检查资源、生成传输参数返回一个打包盒里面含 ICE 和 DTLS 信息端拿到这些参数后直接和视频桥建立 ICE 连接、完成 DTLS 握手媒体开始流动端点离开或切换时控制组件发过期指令视频桥释放通道资源。过期机制是 Colibri 里一个很值得琢磨的设计。请求里带的那个过期时间不是说时间一到通道就断而是给了控制组件一个缓冲窗口——在这个窗口内如果端点又回来了通道可以复用省掉一次完整的 ICE/DTLS 握手。我在自建环境里调过这个窗口实测下来对用户刷新页面这种场景的体验提升很明显重连时间从接近一秒压到了两三百毫秒。提示不要为了更快重连把这个过期窗口调得过大。窗口越长视频桥占着不放的资源就越多大规模会议下会明显拉高内存占用。我的经验值是够覆盖一次页面刷新的时间就足够了。2.3 SCTP 为什么被塞进了传输层还有一个有意思的细节Colibri 的传输层里除了音视频用的 RTP还塞了一路基于 SCTP 的数据通道。这路通道跑的是会议里的文本消息、举手状态、端到端加密的辅助信息这些东西。为什么值得单独提因为 SCTP 的控制参数和 RTP 完全不同它有自己的流数量、缓冲区、重传策略。我遇到过好几次音视频都正常但聊天消息发不出去的诡异现象最后定位就是因为 SCTP 这一路的配置被单独改动了或者 MTU 设置导致数据包被分片后丢弃。排查时你能想到去翻传输层的 SCTP 参数能省掉大量时间。视频桥在近几年的重构里把这部分内部类名从 colibri 前缀换成了更直观的会议/端点命名但协议层的 channel 概念没变。所以如果你看到新旧两套文档别慌它们说的是同一件事。3. 自建环境里动 Colibri先分清你要调的是哪一支很多人一上来就问Colibri 的参数怎么调。这问题问得像汽车怎么开一样宽——你得先说清楚要调哪一块。在我实际操作的经验里和 Colibri 强相关的调优大致分成三支带宽估计、选层策略、以及传输本身。三支混在一起调基本上就是给自己挖坑。3.1 带宽估计、选层策略、传输三件事别混着调先把这三支的边界讲清楚因为这直接决定了你改哪个配置项带宽估计视频桥怎么判断某个端现在能承受多少码率。它依赖端上报的反馈比如接收端估计类反馈和传输层拥塞控制反馈。选层策略已知某个端只能承受低码率后视频桥从可选的多个清晰度层里挑哪一层给它。这一支涉及同时转发多少路、是否固定某路等策略。传输ICE 候选、UDP/TCP 端口、DTLS 这些纯粹的连通性问题。我踩过最典型的一个坑就是试图用调传输参数的方式去解决选层问题。当时的现象是部分用户画面糊我以为是端口或者连通性改了一圈 ICE 配置毫无改善。后来才明白用户是连上了只是视频桥主动给他降了清晰度——那是选层在起作用跟传输半毛钱关系没有。判断方法其实很简单如果用户能听到声音、能看到画面只是糊那是选层如果完全连不上、一直在重连那才是传输。3.2 端口与传输UDP 范围怎么定为什么要留 TCP自建场景里传输层最直接的配置就是端口。视频桥默认走 UDP端口通常是 10000 起。很多人会顺手把 TCP 也开上端口习惯用 443 之类的常见端口。我建议开着但要理解代价。先说 UDP 端口范围。视频桥在 ICE 阶段会从配置的范围里挑端口每个端点会话占用一对。理论上你能支持的并发端点数受端口数量限制。这里的计算不复杂假设你配了从 10000 到 10100那就是 100 个端口按每个会话占一个端口算大致能支撑上百个并发端点。但要注意端口回收是有延迟的尤其是异常断线的情况下。所以我在生产环境里从来不把端口范围压到刚好够用通常留出三到五倍余量。再说 TCP。开 TCP 的价值在于有些网络环境会拦截 UDP这时候 TCP 就成了兜底。代价是 TCP 的传输特性不适合实时媒体——它的重传和拥塞控制是为可靠传输设计的遇到丢包会越传越慢导致画面卡顿加剧。所以我的策略是TCP 只作兜底不作主力。配置上开一个独立端口但不要在负载均衡或防火墙策略上给它额外权重。还有一个容易被忽略的细节如果视频桥部署在 NAT 后面ICE 候选地址的收集需要额外配置。我见过有人把视频桥放在云主机上但没配公网地址映射结果所有端点都只能通过中继走延迟凭空多了几十毫秒。配置形如videobridge { ice { udp { port 10000 } tcp { enabled true port 4443 } nat { # 这里配置公网映射后的地址 } } }注意新版视频桥已经从传统的键值对配置迁移到这种分层配置格式如果你手上是旧文档会发现键名完全对不上。我的做法是先在测试环境跑一遍新格式确认生效后再推到生产不要凭旧经验硬改。3.3 Colibri WebSocket 为什么值得单独开一条线这是 Colibri 里我认为最值得单独讲的一个设计。除了 XMPP 上的通道管理消息视频桥和端点之间还有一条基于 WebSocket 的旁路通道专门用来快速传递选层相关的控制消息。为什么要单独开一条因为 XMPP 那条路要经过控制组件中转链路长、延迟相对高。而选层决策是随带宽变化高频波动的比如用户从 Wi-Fi 切换到移动网络的那一两秒内可选层可能连续变好几次。如果走 XMPP 中转等你消息到了网络状况早就变了。这条 WebSocket 通道的配置要和前端部署的域名对上证书也得匹配否则浏览器会直接拒绝连接。我第一次配的时候就是因为域名对不上导致选层消息发不出去现象是画面永远停在一个较低的清晰度从不自动变清。这个现象很有迷惑性因为音视频链路本身是通的。videobridge { websockets { enabled true domain meet.example.com:443 tls true } }排查这类问题我有个笨但有效的办法打开浏览器开发者工具直接看 WebSocket 帧。如果这条连接根本没建起来或者建起来但帧里没有选层消息那基本可以锁定是这条旁路的问题而不是媒体传输本身。4. 压测现场三个把会议搞糊的坑前面讲的是原理和配置这一节我讲实际踩到的坑。我特意把排查链路完整写出来因为排障的价值不在于答案是哪个参数而在于我是怎么一步步缩小范围的。直接给答案的文章你换一个环境就又不会了。4.1 坑一上行清晰度层全开下行集体崩盘现象描述我自己压测时让一个端点上推最高清晰度同时另外五个端点接收。结果五个接收端同时出现明显卡顿而发送端自己一切正常。我的第一反应是服务器转发能力不够但监控显示视频桥的 CPU 和出口带宽都远没到瓶颈。于是我把方向转到下行。排查链路是这样的。第一步确认接收端到底收到了几路视频。我从视频桥的统计里读每个接收端的通道状态发现每路接收端都在同时接收多路视频流而不是只接收那一路高清晰度的。第二步确认码率总和。把每一路的码率加起来明显超过了我预估的接收端下行能力。第三步确认选层策略是否在起作用。答案是在这个测试规模下选层策略没有预期中那么积极。根因就清楚了接收端下行能力有限但视频桥并没有及时把不必要的高码率层降下来导致下行拥塞进而触发接收端的反馈反馈又影响了整个会议的稳定性。修复方向有两个。一是收紧下行路数的上限让视频桥在接收端数量多时更主动地只转发少数几路二是调高视频桥对带宽反馈的敏感度让它更快响应。我两个都做了先调敏感度因为它是渐进式的风险小再调路数上限这个是硬约束效果立竿见影但需要评估用户体验。这里有个经验值可以分享在普通办公网络环境下我一般把下行视频路数上限控制在个位数同时确保被固定的那一路优先级最高。这样既能看清主要发言人又不会把下行带宽吃光。4.2 坑二固定端点和路数上限打架第二个坑更隐蔽。前面说到被固定的那一路优先级最高——这就是固定端点。用户在界面上点了某个参会者的视频放大期望这个人一直是高清的。但如果同时开启了下行路数上限并且上限设得很紧就可能出现固定端点被挤出去的情况。现象是用户点了放大某个人结果过几秒又自己缩回去了。用户当然会认为是 bug。排查起来很有意思。我一开始怀疑是前端的固定状态没同步查了半天前端逻辑没问题。后来去翻视频桥的日志发现固定指令是发出去了、也收到了但紧接着选层决策把这一路的清晰度降了。也就是说固定端点和路数上限两个策略在互相覆盖。根因是这两个策略的优先级没有理顺。修复方式很直接调整配置让固定端点在路数上限之外单独占一个名额也就是上限之外再加固定路。这样固定端点永远有位置。提示固定端点数量是有配置上限的默认一般是个较小的值。如果你的场景里用户喜欢同时固定好几个人的画面记得把这个上限相应调大否则后固定的人会顶掉先固定的人。4.3 坑三TCP 兜底开着但防火墙只放了一半这个坑在自建环境里极其常见而且极难从应用层看出来。现象绝大多数用户正常只有少数几个用户连不上或者只能听声音看不到画面。这些用户分布在不同网络环境里。排查链路。第一步看这些用户的连接方式。从视频桥日志里能看出他们是在走 UDP 还是 TCP。第二步对比成功和失败的连接方式发现失败的都走了 TCP。第三步直接测 TCP 端口连通性。结果发现防火墙规则里UDP 端口放行了TCP 端口只放行了入方向出方向或者返回路径没有正确配置。根因就是防火墙规则不完整。修复是补齐规则这里没什么巧劲就是把 UDP 和 TCP 两个端口、入和出两个方向都覆盖到。这个坑教给我一个习惯每次部署新环境我一定先用一个模拟受限网络的客户端手动测一遍兜底路径。因为主路径太顺了兜底路径的问题往往要等到真实用户报告才发现。5. 让 Colibri 的状态可见观测与端到端验证调参最怕的就是两眼一抹黑。Colibri 这层如果不做观测你改完配置只能靠感觉好像快了点来判断这在生产环境里是不可接受的。这一节讲我怎么做观测和验证。5.1 统计接口怎么开先看哪几个数视频桥本身能暴露统计信息可以推给监控系统。开启方式大致是在配置里打开统计开关并指定推送的目标地址和间隔。我的习惯是间隔不要太密十秒一次足够太密了自己给自己制造压力。打开之后先不要贪多盯住三组数就够了观测维度关注什么异常信号端点与会话当前会议数、端点数、通道数通道数增长但端点数不增可能是泄漏带宽与码率每路通道的实际码率、估计带宽实际码率长期贴着实测带宽上限传输质量丢包率、抖动、重传丢包率持续高于正常水平我最先盯的永远是通道数 vs 端点数这个比值。因为通道泄漏是 Colibri 这层最典型的一类问题——端点异常退出时过期流程没走完通道资源就挂在那里了。表现就是比值缓慢上升跑几天后内存吃紧。5.2 几组关键指标和它们的合理区间具体数值因环境而异我给出的是我自己在普通办公网环境下的经验区间你可以作为起点再调整下行丢包率稳定在很低的水平是正常的比如千分之几。一旦持续超过百分之一接收端就会明显感知卡顿。端到端延迟同城环境下几十毫秒是合理的。如果超过一百五十毫秒用户会开始抱怨像打电话一样抢话。带宽估计与实际码率的比值正常情况实际码率应该低于估计带宽留有余量。如果长期贴着估计值跑说明没有余量网络稍微一抖就会掉层。我给自己设的告警阈值是下行丢包率持续超过百分之一达一分钟就告警。这个阈值不是拍脑袋定的是我反复看用户投诉和指标曲线对齐后得出的比任何理论最优值都准。5.3 用 WebSocket 消息做一次端到端验证最后一招也是我最喜欢的验证方法直接在浏览器开发者工具里看那条 WebSocket 通道上的消息。为什么说它是端到端验证因为它能同时告诉你三件事选层决策有没有下发、下发得对不对、端点有没有响应。这三个环节任何一环断了你从 WebSocket 帧里都能看出来。具体做法是打开一个测试会议在开发者工具里过滤 WebSocket 连接观察帧的内容。正常情况下你应该能看到随着网络状况变化选层消息在动态调整。如果网络状况明显变差但消息纹丝不动说明决策没触发如果消息发了但画面没变化说明端点侧没响应。这套方法不需要任何额外的抓包工具成本极低我强烈建议每个做这块的人都掌握。6. 什么时候不该动 Colibri边界与常见误操作写到这里我想反过来讲一句Colibri 这层的参数能不调就不调。绝大多数会议体验不好的问题根因不在这一层盲目调参只会把一个可复现的问题变成一个不可复现的问题。6.1 先排除这三类非 Colibri 问题在动手改任何 Colibri 相关配置之前我要求自己先排除这三类前端编解码能力问题低端设备解码高清晰度视频本身就吃力这时候降清晰度是对的不是配置错了。用户终端网络问题单独某几个用户有问题大概率是他们自己的网络不是服务器。部署拓扑问题视频桥和控制组件之间的网络质量很多时候比视频桥到用户的链路更关键而且更容易被忽略。我有一次折腾了一整晚的选层参数最后发现是视频桥和控制组件之间的网络抖动导致控制消息延迟选层指令晚到了几秒。这种问题你在视频桥内部怎么调都没用。6.2 改动前必须留下的两样东西如果你确定要调那请务必留下两样东西改动前的基线数据和可一键回滚的配置版本。基线数据是为了对比。没有基线你改完之后凭感觉说好像好点了等于没改。我的做法是改动前至少采集一段完整的会议指标最好覆盖高峰时段。可回滚的配置则是保命。Colibri 相关的参数之间耦合度不低改一个可能连带影响另一个。我现在的习惯是所有配置都走版本管理改之前先提交一版改完观察二十四小时再决定是否保留。6.3 适合大规模会议的取值思路最后说一个思路性的东西不涉及具体数字。当会议规模从几个人涨到几十人时Colibri 这层的策略应该从尽量让每个人看清转向保证主要发言人清楚、其他人能看个大概。这不是妥协而是资源分配的必然。我自己的取值心法是先确定必须高清的人有几个把这块资源预留死剩下的资源再按人数均摊。按这个思路去调你会发现很多参数一下子就有方向了不再是凭感觉试数字。这套东西我前前后后踩了大概半年才理顺中间推翻过好几次自己的判断。真正让我进步的不是记住了哪个参数设多少而是学会了从日志和指标里读出系统在做什么决策。Colibri 这层之所以值得花时间就是因为它把决策过程都写在了你能看到的地方只是需要你先学会它的语言。