LiveKit实战指南：从本地5分钟跑通到公网分布式部署

LiveKit实战指南：从本地5分钟跑通到公网分布式部署

【免费下载链接】livekitEnd-to-end realtime stack for connecting humans and AI项目地址: https://gitcode.com/GitHub_Trending/li/livekit

LiveKit 是一个用 Go 写的开源 WebRTC 媒体服务器。所谓媒体服务器（SFU，Selective Forwarding Unit），你可以理解为"转发站"：每个人的音视频流先到服务器，再由服务器转发给房间里其他人，这样 N 个人开会只需要 N 条上行而不是 N×(N-1) 条连接，带宽和兼容性都省得多。LiveKit 把转发、信令、JWT 认证、节点间路由这些最麻烦的部分打包进一个二进制，你只需要写业务逻辑。适合做视频房间、直播连麦、AI 语音通话的开发者，以及要评估"自研 vs 自建"的架构师。

五分钟跑通：先让浏览器进一个房间

LiveKit 的启动门槛是这几个开源实时项目里最低的——开发模式一条命令，不需要配置文件、不需要 Redis。

livekit-server --dev

这条命令会自动做三件事：API 密钥对设为devkey/secret、日志切到 debug、开启/debug/pprof（生产环境别用--dev，密钥是占位的）。服务起来后监听7880（信令）和7881（TCP 回退），UDP 用50000-60000。

客户端连房间需要一个 JWT 访问令牌，里面编码了用户身份和房间权限，用 LiveKit 自带的 CLI 生成：

lk token create \ --api-key devkey --api-secret secret \ --join --room my-first-room --identity user1

拿这个 token 进官方的示例应用页面（在 README 的 Getting Started 一节有入口），输入 token 就能进房、看到自己和测试机器人bot-user1的视频。想验证转发链路通不通，用 CLI 模拟一个发布者：

lk room join --url ws://localhost:7880 \ --api-key devkey --api-secret secret \ --identity bot-user1 --publish-demo my-first-room

浏览器里出现机器人的 demo 视频流，说明 SFU 转发链路已经通了。5 分钟，从启动到看到画面。

能力拆解：这个服务器到底替你做了什么

按功能模块看，LiveKit 主要替你扛了四件事，每件事对应一组关键参数。

媒体转发：50000-60000 的 UDP 端口段是命脉

SFU 转发媒体走 UDP，端口范围由rtc.port_range_start/end控制，默认 50000 到 60000。⚠️ 这个范围必须在防火墙上放开入站 UDP，否则客户端要么连不上、要么被降级到 TCP。想减少端口占用可以改用rtc.udp_port指定单一 mux 端口（官方建议端口数不少于 vCPU 数），配置完直接看仓库里的注释示例最清楚：配置样例 config-sample.yaml。

认证：API key 对签发 JWT

配置里的keys是一段"key: secret"映射，客户端进房、调 RoomService API 都靠它签 JWT。支持配多组密钥，方便轮换。生产环境有个硬约束：secret 短于 32 字符会触发安全告警，这条校验逻辑在 配置校验源码 里，非development模式才生效。

多节点协同：一行 Redis 配置切换集群模式

单机模式下所有房间锁在本地；一旦配上redis.address，LiveKit 自动进入全分布式模式——任意客户端连到任意节点，都能被路由到同一个房间，房间状态、信令消息、节点选择全部走 Redis。没有"先单机后改集群"的代码改动，这是它的分布式设计里最省心的部分。

可观测性：Prometheus 指标一个端口开启

prometheus_port: 6789一行配置，服务就在:6789/metrics暴露房间数、参与者数、节点 CPU/内存等指标，接你的 Prometheus + Grafana 即可。指标定义在 telemetry 模块，房间级指标在prometheus/rooms.go。

四个模块对应的核心参数速查：

三种常见部署方式，按网络环境选

场景一：本机或内网体验

内网最省事，--dev直接跑。想留配置文件就用最小配置：

development: true keys: devkey: secret rtc: tcp_port: 7881

内网环境下use_external_ip保持默认的 false 就行，STUN 探测公网 IP 反而没意义。

场景二：局域网内多人使用的长驻服务

把密钥换成真值（32 字符以上）、日志切到 JSON 方便采集，Redis 先不加：

port: 7880 rtc: port_range_start: 50000 port_range_end: 60000 tcp_port: 7881 keys: mykey: <生成一个32位以上的随机串> logging: level: info json: true prometheus_port: 6789

容器化时用-e LIVEKIT_KEYS="key: secret"或把 YAML 直接传进LIVEKIT_CONFIG环境变量（服务端有--config-body标志接收它），比挂载文件更适合 12-factor 式的部署。

场景三：公网多台机器组成集群

跨机器的要点只有两条：让每个节点正确"报出自己的公网 IP"，以及所有节点指向同一个 Redis。

redis: address: "redis-host:6379" password: "<密码>" rtc: use_external_ip: true # 云主机内网IP映射公网时靠STUN自发现 port_range_start: 50000 port_range_end: 60000 keys: prodkey: "<32位以上secret>" logging: level: info json: true prometheus_port: 6789

use_external_ip: true让节点用 STUN 发现自己的公网 IP 并广播给客户端；如果 STUN 探出的 IP 不对（比如经过了一层 NAT），改成显式配rtc.node_ip。K8s 环境里 Pod 的 IP 会漂移，通常用node-ip环境变量注入或结合hostNetwork处理 UDP 端口段——UDP 范围端口是 LiveKit 上 K8s 最特殊的地方，每个 Pod 都要能暴露这段端口。

新手必踩的三个坑，各配一条排查命令

坑一：UDP 端口没放通，连接静默劣化。症状是连上但画面卡、或只能走 TCP。WebRTC 有 TCP 回退，问题会被"能连上"掩盖住。排查：ss -lun | grep -E '5[0-9]{4}|60000'看本地监听，再看防火墙/云安全组是否放了 50000-60000 入站 UDP。

坑二：把 tcp_port 塞进负载均衡或 TLS 后面。rtc.tcp_port是裸 TCP 的 ICE 回退通道，服务端注释明确写了它cannot放在 LB 或 TLS 后面，只允许裸 80/443 或高位端口直连。放进 Nginx 后回退链路必断。排查：curl -v telnet://<节点IP>:7881应能直接 TCP 握手。

坑三：没配 keys 服务起不来，或者 secret 太短。不配任何keys，服务端直接报ErrKeysNotSet退出；生产模式下短 secret 会打 error 级告警。排查：启动日志里搜secret is too short，或者用--dev先确认链路再上正式密钥。

💡 顺带一提，所有配置项都能用LIVEKIT_前缀环境变量覆盖（配置名大写、点号转下划线，如LIVEKIT_REDIS_ADDRESS），这套逻辑在 配置加载源码 的GenerateCLIFlags里生成，容器部署时基本靠它。

什么场景选它，什么场景别选

先说该用的场景：需要多人对音视频、且客户端网络环境复杂（公司内网、弱网、移动端频繁切网）时，自建 P2P 方案很难覆盖的 TURN/ICE 场景，LiveKit 的 SFU + 拥塞控制 + TCP 回退是现成的；房间人数超过 3-4 人后 P2P 带宽不现实，SFU 是刚需。它的分布式模式不引入额外组件（只多一个 Redis），从单台到多台的扩展成本很低，团队规模小也能运维。

不适合的场景：只有两个人偶尔通话、或者流量极小且完全可控的 P2P 场景——为这个体量自运维一套 UDP 端口段和 Redis 集群不划算，直接用托管的 LiveKit Cloud 或云厂商的 RTC 服务更合适；如果你的业务只是单向拉流（看直播，不互动），WebRTC SFU 的复杂度也过剩，RTMP/FLV 加 HLS 分发更简单。

下一步建议：先用--dev模式跑通上面的"五分钟"流程，确认客户端能进房再谈部署形态；生产上线前重点核对三件事——UDP 端口段放通、tcp_port未被代理、密钥对已换成 32 位以上的正式值。想深入媒体转发逻辑，从 RTC 核心模块 的sfu.go和forwarder.go入手；需要录制、导流、AI 参与者这类能力，走 LiveKit 生态的 Egress/Ingress/Agents 扩展而不是改服务端。

【免费下载链接】livekitEnd-to-end realtime stack for connecting humans and AI项目地址: https://gitcode.com/GitHub_Trending/li/livekit