说到局域网里自建一套音视频通信服务我首先想到的是 liveKit。它是一套开源的实时音视频基础设施信令走 WebSocket媒体走 WebRTC部署起来比直接用 Janus 或 mediasoup 要省心不少。最近我在模拟项目X里需要在一个完全隔离的局域网环境中跑一套多端视频通话的 Demo评估了几个方案之后最终选择用 liveKit 搭服务并做了完整的联调测试。这篇文章就记录整个过程的思路、操作细节以及踩过的坑给同样需要在局域网环境下手搓音视频服务的朋友一个参考。这篇内容适合两类人看一类是第一次接触 liveKit想快速搭一套可用的服务另一类是自己已经部署成功但遇到连接不稳定、画面打不开、鉴权失败这类问题想找排查方向。我会从架构选型、服务端搭建、客户端联调、断网重连、排障技巧几个维度展开尽量把每一步的“为什么”也讲清楚而不是丢一堆命令让你复制就完事。1. 在局域网搭 liveKit 之前先搞懂这套架构1.1 为什么是 liveKit而不是其他方案做实时音视频摆在桌面上的开源方案其实不少。以我个人的评估习惯会先看三件事部署复杂度、客户端 SDK 覆盖度、以及信令和媒体层的耦合程度。先说部署复杂度。liveKit 的服务端是单个 Go 二进制配合一个配置文件就能跑起来依赖的只有 Redis 可选用于多实例场景。如果你只是单机部署Redis 都可以先不装。这一点特别适合局域网内快速落地因为不需要引入一堆微服务组件。对比 Janus它是一个 C 语言编写的媒体服务器需要编译一堆插件配置也比较繁琐而 mediasoup 虽然灵活但它的 Node.js 集成方式意味着你需要自己写一层信令服务工作量直接上了一个台阶。再说 SDK 覆盖度。liveKit 官方提供了 Web、iOS、Android、Flutter、React Native 等平台的 SDK而且 API 设计比较统一都是围绕 Room、LocalTrack、RemoteTrack 这几个核心概念。局域网内常用的联调场景无非是网页端和手机端互连这个覆盖度绰绰有余。我在这次测试里主要用了 Web SDK辅助用了一个简单的命令行推流工具做压力验证整个接入过程非常顺。最后是信令和媒体层的耦合。liveKit 把信令封装在服务端客户端只需要通过 WebSocket 连接并携带 JWT 令牌服务端会自动完成房间管理、媒体路由和转发决策。你不需要自己维护一套信令服务器来处理 offer/answer 交换这对只想快速看到画面的人来说非常友好。当然选型没有绝对的好坏。如果你需要深度定制 SFU 的转发逻辑或者想完全掌控信令协议那 mediasoup 可能更合适。但就“在局域网搭一套能用的服务并测试”这个目标而言liveKit 是在搭建成本和维护成本之间最平衡的选择。1.2 liveKit 的两个关键角色服务端与客户端要理解 liveKit 的工作方式先分清楚两个角色服务端负责房间管理和媒体转发客户端负责采集、编码、渲染音视频流。服务端在 liveKit 里叫 livekit-server它本身是一个 SFUSelective Forwarding Unit也就是选择性转发单元。SFU 是一种媒体服务器架构客户端之间不会直接传输媒体流而是把所有媒体流先发给服务器再由服务器根据订阅关系转发给其他客户端。这和 Mesh 架构完全不同Mesh 是每个客户端直接互相推流人数一多上行带宽和编码压力会指数级上涨而 SFU 只需要每个客户端和服务器建立一路连接服务器负责分发能支撑的人数规模就大得多。可以用一个生活化类比来理解Mesh 架构相当于开一场圆桌讨论每个人都对着所有人说话十几个人还能忍受几十个人就完全乱套了SFU 架构则像一个电话会议总机所有声音汇聚到总机总机再按需转给参会者压力集中在总机但也正因为集中才更容易控制和扩展。客户端角色则主要由各端 SDK 承担。以 Web 端为例SDK 内部会完成 getUserMedia 采集麦克风和摄像头、编码成 Opus 音频和 VP8/VP9/H264 视频、通过 WebRTC 建立 PeerConnection、与服务端进行 DTLS 协商等一系列操作。你写的业务代码其实只是“遥控”这些底层能力加入房间、发布本地轨道、订阅远端轨道、控制麦克风开关等。在实际测试中理解这两层角色的分工很重要。很多连接问题其实出在“客户端以为自己在直连另一个客户端”但 liveKit 的媒体流默认必须经过服务器如果客户端的网络策略不允许访问服务器的媒体端口画面就会黑屏或卡顿。这个后面我会专门讲。1.3 网络拓扑为什么“局域网”反而要更小心很多人觉得局域网内搭服务很简单没有公网带宽限制没有防火墙穿透随便跑起来就能用。但实际联调时我踩了不少网络层面的坑这里先梳理清楚。局域网拓扑通常是这样一台服务器电脑一个无线路由器若干客户端设备通过 WiFi 或网线接入同一个网段。服务端启动后监听某个端口客户端通过服务器的局域网 IP 连接。听起来简单但有几个隐藏细节第一个是绑定地址。服务器可能有多张网卡比如有线网卡、无线网卡、Docker 虚拟网卡甚至 VMware 之类的虚拟网卡。如果服务端默认绑定到 0.0.0.0理论上所有网卡都能访问但有些配置模式下它可能只监听了某个地址导致客户端连接超时。我建议启动时直接用--bind指定局域网网卡的 IP减少不确定性。第二个是端口放行。liveKit 主要涉及两组端口信令端口默认是 7880媒体流量使用的 UDP 端口范围默认在 50000 到 60000 之间。如果服务器开了防火墙这两组都要放行。我遇到过的情况是信令能连上房间也建立了但对方看不到画面查了半天才发现是防火墙只放行了 TCP 7880UDP 段全部被挡了。第三个是网络隔离。有些公司或学校的局域网会做 AP 隔离也就是无线客户端之间不能直接通信但客户端和服务器之间的通信可能也受影响。这种环境里即使服务端部署成功客户端也容易频繁断连。排查时要先确认客户端是否能稳定 ping 通服务器的局域网 IP这个基础网络连通性测试能过滤掉大量伪故障。2. 搭建前的环境准备与参数规划2.1 服务端部署的两种方式二进制与 DockerliveKit 服务端的部署方式很灵活官方推荐两种直接下载编译好的二进制或者使用 Docker 镜像。我这次搭建用的是直接二进制方式原因是内网环境往往不方便拉取 Docker 镜像二进制拷贝进去就能跑依赖非常干净。如果你是在有外网的环境里准备Docker 方式会更省事docker run --rm -p 7880:7880 \ -p 50000-60000:50000-60000/udp \ -e LIVEKIT_KEYSdevkey: secret123 \ -e LIVEKIT_SECRETsecret123 \ livekit/livekit-server --dev注意开发模式下--dev会自动生成一个临时密钥也可以手动指定密钥。生产环境一定不要用这种方式但局域网测试完全够用。二进制方式也很简单# 下载对应平台的 release 包并解压 curl -LO https://github.com/livekit/livekit/releases/download/v1.5.0/livekit_1.5.0_linux_amd64.tar.gz tar xzf livekit_1.5.0_linux_amd64.tar.gz sudo mv livekit-server /usr/local/bin/之后需要准备一个配置文件。liveKit 的配置是 YAML 格式核心字段如下port: 7880 bind_addresses: - 0.0.0.0 rtc: tcp_port: 7881 port_range_start: 50000 port_range_end: 60000 use_external_ip: false keys: devkey: secret123这里有一个容易被忽略的点use_external_ip这个字段。默认情况下liveKit 会尝试探测公网 IP 并把它写入 SDP 的候选地址里。但在局域网环境外网探测可能会失败或者探测到的地址根本不可达。测试时我把它显式设置为false让服务端只汇报局域网 IP客户端才能正确建立媒体连接。如果你的服务端只有一个局域网地址也可以用node_ip字段直接指定rtc: node_ip: 192.168.1.100这个字段在某些版本里会覆盖绑定的意图建议以官方文档为准。整体配置的思路是先保证信令端口可访问再保证媒体端口段可访问最后确保 SDP 里携带的地址是客户端能到达的地址。2.2 生成 API Key 与 Secret别在鉴权上省事liveKit 的鉴权模型是 JWT客户端加入房间时必须携带一个由 API Key 和 Secret 签名生成的令牌。服务端启动配置文件里的keys区块就是用来校验这个令牌的。Key 和 Secret 的关系类似用户名和密码Key 是公开标识Secret 是签名密钥。客户端 SDK 初始化时通常只需要传入 Key 和 Secret 来生成令牌但如果你用的是官方推荐的 token 生成方式Secret 应该只保存在服务端或可信的代理服务里不应该下发到客户端。我在测试中踩过这样的坑为了方便前端直接把 Secret 写在代码里生成令牌。这在局域网内问题不大但一旦客户端代码泄露任何人都能伪造管理员身份。更合理的方式是单独写一个简单的 Token 生成接口客户端请求时传入房间名和身份标识由后端生成并返回令牌。生成 Token 的代码逻辑其实不复杂用伪代码表示就是header { alg: HS256, typ: JWT } payload { iss: devkey, nbf: now - 10, exp: now 3600, video: { room: test-room, identity: user-a } } token HMAC_SHA256(base64(header) . base64(payload), secret)如果你不想自己写签名逻辑可以直接用官方提供的 token 生成工具或者用各语言 SDK 里内置的方法。关键是确保服务端配置的 Key 和生成令牌时使用的 Key 完全一致否则连接会直接返回 401。2.3 规划端口、房间名与测试身份在实际测试之前建议先规划好三件事端口段、房间命名规则、测试身份。端口段方面7880 是默认的信令端口媒体端口范围越大能够支撑的同时连接数越多。单机测试时 50000-60000 已经覆盖 10000 个端口足够日常并发。要注意的是媒体端口使用的是 UDP而不是 TCP虽然 liveKit 也支持 TCP 媒体通道作为降级方案但默认首选还是 UDP端口不通时画面会异常。房间命名规则其实没什么硬性要求但建议用带业务语义的格式比如meeting-room-a、classroom-01。在局域网测试中我习惯把房间名、测试密码、服务端地址写在一个配置 JSON 里避免重复修改代码。测试身份则需要提前规划。liveKit 的身份相当于用户的唯一标识同一个房间里不允许出现重复的身份否则后加入的端会把先加入的踢掉。我测试双人通话时用的是user-a和user-b多端测试时会在身份后面加序号比如user-a-1、user-a-2这样日志里能清楚看到每个连接。3. 实测过程从启动服务到双端通话3.1 启动服务并验证基础状态配置写好之后启动服务很简单livekit-server --config /path/to/config.yaml启动成功的日志里会看到类似这样的输出服务监听在 7880 端口Redis 未启用API key 已加载。如果配置文件里填了无效的 YAML启动会直接报错并根据报错位置去定位字段格式问题。这时候先用浏览器访问http://192.168.1.100:7880如果返回一段提示文字或者一个空白 JSON说明 HTTP 服务已经起来了。liveKit 的信令走的是 WebSocket路径通常是/rtc所以直接访问根路径并不会返回什么有意义的信息只要能连通就算正常。更靠谱的验证方式是先在服务器本机跑一个 WebSocket 连接测试检查 7880 端口是否能完成协议握手。这一步能区分“服务没起来”和“网络不通”。3.2 客户端联调加入房间与发布订阅客户端我用的是 Web SDK方式是在一个静态页面里引入 livekit-client。流程分三步生成 Token、建立连接、发布本地音视频轨。生成 Token 这一步我直接用服务端脚本生成粘贴到前端页面里。页面代码大致结构如下import { Room, LocalTrack } from livekit-client; const room new Room(); await room.connect(ws://192.168.1.100:7880, token); const localTracks await LocalTrack.createLocalTracks({ audio: true, video: true, }); localTracks.forEach(track room.localParticipant.publishTrack(track));这里的重点是连接地址。Web SDK 的 connect 方法传入的是 WebSocket 地址格式是ws://服务器IP:7880不是http://。因为 liveKit 的信令层基于 WebSocket这一点很容易被忽略。如果填成 httpSDK 会尝试进行非 WebSocket 协议的 HTTP 升级结果通常直接报错。发布本地轨道后远端参与者会自动收到一个trackPublished事件然后可以订阅。官方 SDK 提供了自动订阅配置默认是打开所以你不需要手写订阅逻辑但我也建议在实际项目中显式管理订阅状态方便后续做按需拉流。3.3 双人通话与静音开关的验证为了验证真实通话效果我在同一台服务器上起了两个浏览器标签页分别以不同身份加入同一个房间。一页摄像头打开另一页能看到画面。这里需要提醒一下同一台电脑的两个标签页可以共用摄像头但音频采集会出现回声测试时最好戴耳机或者直接把其中一页的麦克风静音。验证内容包括三块画面是否清晰、声音是否延迟、静音开关是否同步。画面清晰度和网络带宽强相关局域网内通常 720P 没有问题声音延迟在局域网环境下小于 200 毫秒如果明显高于这个值就要检查是不是没有走局域网而是走了公网中转这种问题通常是 SDP 候选地址错误导致的。静音开关的验证则涉及状态同步机制。liveKit 的静音状态是通过信令通道广播的而不是媒体流本身。也就是说即使一个参与者完全断开发布其他端也能收到静音状态变更事件。这个机制的好处是状态同步不依赖媒体流是否通畅但坏处是如果你的业务逻辑依赖“麦克风开/关”来决定是否显示 UI 状态必须显式监听事件而不是轮询本地轨道状态。3.4 断网重连与弱网模拟局域网测试不能只看理想状态还得验证断网重连。我做的第一组测试是直接断开客户端所在设备的 WiFi5 秒后重新连上观察页面是否自动恢复。liveKit 客户端内置了自动重连机制大致逻辑是检测到连接断开后会进入重连状态期间持续尝试重新建立 WebSocket 连接如果媒体传输层断开而信令层还活着则只重建 PeerConnection。这一套机制在正常网络抖动时表现不错但我在测试中也发现一个问题如果服务端配置的媒体端口被防火墙静默丢弃客户端会一直卡在“连接中”状态不会主动报错。第二组测试是弱网模拟。我用了一个简单的网络损伤工具给服务器的 7880 端口加延迟和丢包观察视频表现。局域网内加 50ms 延迟时几乎无感加 200ms 延迟时画面会出现明显卡顿但音频还能保持连续。这符合 WebRTC 的拥塞控制预期。如果你的测试环境里没有现成的损伤工具也可以在客户端一侧用开发者工具的网络面板拦截部分数据但这样做对 WebSocket 和 UDP 流量的模拟不太准确更容易出问题。更靠谱的做法是在路由器或服务器上通过流量控制命令模拟丢包这样能还原真实网络场景。3.5 用命令行工具做多端压力冒烟在浏览器联调通过之后我还用 liveKit 的 CLI 工具做了一次简单的多端冒烟测试。CLI 可以模拟一路 WebRTC 推流和拉流适合在没有摄像头和麦克风的环境里验证服务端转发能力。livekit-cli join-room --url ws://192.168.1.100:7880 \ --api-key devkey --api-secret secret123 \ --room test-room --identity bot-a --publish-demo--publish-demo参数会自动推入一路测试音视频流。然后我再用另一个终端跑一个--subscribe模式的实例验证这一路流能否被正常订阅。如果 CLI 能成功订阅说明服务端的媒体转发链路是通的浏览器连不上大概率是浏览器权限或 SDP 候选问题而不是服务端故障。这个冒烟测试帮我省了很多事。后续我在排查前端问题时始终先用 CLI 确认服务端健康再回头检查代码排错效率明显提升。4. 局域网测试中遇到的问题与排查清单4.1 信令通了但画面黑屏优先查媒体端口这是我在测试过程中遇到最多的一个问题。现象非常典型两个客户端都能加入房间能看到对方的名字但画面始终是黑色并有等待状态标识。出现这种情况首先要意识到信令和媒体是两条不同的通道。信令走 TCP 7880媒体走 UDP 50000-60000两者独立。信令通了只代表客户端与服务器之间的控制通道正常媒体通道可能完全不可达。排查步骤可以按顺序走在服务器上执行ss -ulnp | grep 50000确认 UDP 端口确实在监听。从客户端设备上执行nc -uz 192.168.1.100 50000测试 UDP 端口是否可达。注意nc的 UDP 测试对某些环境不准确但能粗略判断。检查服务器防火墙状态确认 UDP 50000-60000 段没有被挡。在客户端 SDK 里开启日志查看 ICE candidate 是否成功选到了服务器地址。我这次测试就是因为服务器防火墙默认只放行了 TCP 22、80、443 和 7880UDP 全部丢弃所以信令正常、媒体完全不通。放行之后画面立刻恢复。4.2 JWT 鉴权失败与时钟偏差还有一类常见问题是加入房间时直接返回 401日志里会看到类似invalid token的提示。除了 Key 和 Secret 配置不一致之外我遇到过一个很隐蔽的问题服务器系统和客户端设备之间的时间偏差过大。JWT 的有效期验证依赖nbf和exp这两个时间戳是和签发时的系统时间绑定的。如果签发令牌的服务端时间比验证令牌的服务端时间快了几分钟令牌可能还在签发端看来有效但验证端已经开始拒绝。解决办法很直接在服务器上执行时间同步确保所有参与端的时间偏差在几秒以内。另外还需要确认令牌里的video字段是否包含了正确的room和identity。有些 SDK 提供了便捷方法但也允许自定义 payload一旦字段名拼写错误liveKit 会解析不到房间名报错信息也比较隐晦。4.3 客户端频繁断开先查绑定地址和 AP 隔离局域网内客户端频繁断连通常有两个方向一是服务端绑定的地址不对二是无线网络的 AP 隔离策略启用。绑定地址的问题在服务器上最容易排查。用ip addr查看本机所有 IP再用ss -lntp | grep 7880确认服务实际监听在哪个地址。我在有一次测试中发现服务默认监听在 Docker 网桥的 IP 上局域网客户端根本访问不到但偏偏信令偶尔能通就很迷惑。显式在配置中设置bind_addresses指向局域网网卡后问题才彻底解决。AP 隔离的问题则更隐蔽。有些路由器在开启访客网络或多人 WiFi 时默认启用客户端隔离导致同一 WiFi 下的设备无法互访。判断方法是在客户端设备上 ping 服务器 IP如果 ping 不通但其他网络设备能 ping 通就基本能确定是隔离策略。此时可以关闭 AP 隔离或者把服务器改为有线接入问题通常随之消失。4.4 排查问题时的日志利器livekit-cli 与服务端日志最后分享一个排障习惯。liveKit 服务端默认会打印详细的日志包括连接建立、房间创建、参与者加入、发布轨道、订阅确认等信息。当问题发生时先看服务端日志往往能最快定位。还可以用 livekit-cli 的list-rooms和get-participants命令实时查看房间内状态。比如客户端认为自己在房间里但看不到人用 CLI 查看该房间的参与者列表就能判断是客户端订阅异常还是服务端根本没有人。livekit-cli list-rooms --url ws://192.168.1.100:7880 \ --api-key devkey --api-secret secret123这个命令会列出所有活跃房间和参与者数量。配合服务端日志能覆盖大部分排障场景。最后分享一点实操心得整个流程最容易被忽略的其实是权限与端口这两层很多问题翻来覆去查代码结果只是防火墙规则没放行。建议把端口清单、JWT 密钥、绑定 IP 这三个信息提前写在笔记里动手前先对一遍能省掉大量排障时间。liveKit 这套东西配置量不大但任何一个环节的细节错位都会让联调变得煎熬。希望这篇记录能帮你少走一些弯路。
