LiveKit 自托管完全指南：4 个关键配置打通 WebRTC 实时音视频服务器

LiveKit 自托管完全指南4 个关键配置打通 WebRTC 实时音视频服务器【免费下载链接】livekitEnd-to-end realtime stack for connecting humans and AI项目地址: https://gitcode.com/GitHub_Trending/li/livekitLiveKit 是一个用 Go 编写的开源 WebRTC 媒体服务器SFU负责在多个客户端之间转发音频、视频与数据流。自托管它时绝大多数故障都集中在同一处进程到底监听了哪些端口、客户端能不能真正到达这些端口。本文不堆参数表而是从一个进程要打通的网络面讲起带你从 5 分钟开发模式跑通一路推进到 Redis 分布式生产集群与可观测性每个环节都给出「前置条件 → 操作步骤 → 验证方式」的可执行路径。先想清楚一个 LiveKit 进程到底监听哪些端口连不上十有八九是端口没放行。LiveKit 同时承担信令和媒体两种角色它们用不同的端口承载混在一起讲只会越理越乱。下面这张图先建立「一个进程 三类端口」的心智模型。port信令默认 7880。这是唯一可以安全地放在负载均衡器 TLS 后面的端口。rtc.port_range_start/rtc.port_range_end媒体默认 50000 / 60000共一万条 UDP 端口。生产环境务必在防火墙上对整个入站区间放行只放行单个端口会导致打洞失败。rtc.tcp_port备用媒体默认 7881。当客户端网络封禁 UDP 时走这条 TCP 回退注意它不能经过负载均衡器或 TLS且小于 1024 时只允许用 80/443。验证方式用livekit-server ports子命令让进程自己打印它实际配置的端口再与防火墙规则逐一比对。5 分钟跑通开发模式 最小配置本节解决「怎么最快看到它在跑」的问题。LiveKit 内置了开发模式会替你填好大部分默认值适合本地验证与调试。前置条件安装好二进制或通过上一节的源码构建得到bin/livekit-server并确认本机 7880/7881 未被占用。操作步骤直接以开发模式启动不传任何配置文件。./bin/livekit-server --dev开发模式会自动完成三件事把日志级别提到debug、使用devkey/secret这对占位密钥、并把监听地址绑定到回环127.0.0.1与::1。如果启动时发现没配密钥进程会打印一行提示告诉你当前用的是占位密钥——这是预期行为生产环境不要这样做。需要自定义时再写一份最小配置。默认值 → 作用 → 生产怎么改的顺序如下port: 7880 keys: mykey: mysecret # 默认无生产用 generate-keys 生成的强密钥对 rtc: port_range_start: 50000 # 默认 50000按防火墙能力调整 port_range_end: 60000 # 默认 60000区间越大并发连接越稳 tcp_port: 7881 # 默认 7881无需 TCP 回退可留空 use_external_ip: false # 默认 false云上内网 IP 映射公网时改为 true用livekit-server --config dev-config.yaml启动。验证方式生成一个访问令牌再连一个房间。令牌是 JWT编码了用户身份与权限用官方 CLI 快速签发一个即可。lk token create \ --api-key mykey --api-secret mysecret \ --join --room my-first-room --identity user1 --valid-for 24h再用lk room join发布一路演示视频浏览器端能看到画面即代表信令与媒体都通了。仓库根目录的 config-sample.yaml 是一份带完整注释的参考配置字段语义以它为准。从源码构建改核心代码的开发者看这里本节解决「想改 LiveKit 内部逻辑怎么编译出一个可运行的二进制」。构建走的是 Mage 任务系统bootstrap.sh负责准备工具链。前置条件安装 Go 1.23并确认go env GOPATH/bin 在PATH中bootstrap.sh会检测mage是否存在缺失时会提示你补 PATH。操作步骤git clone https://gitcode.com/GitHub_Trending/li/livekit cd livekit ./bootstrap.sh # 安装 mage 并拉取依赖 mage build # 产物落在 bin/livekit-server验证方式mage默认目标就是Build再执行mage build若输出up to date说明增量校验生效、源码未变化。要跑单测用mage test跑集成测试用mage testall。构建目标与产物路径见 magefile.go。调试层面--dev之外还支持--cpuprofile/--memprofile落盘 pprof 文件--dev会额外开启/debug/pprof端点。定位房间与参与者行为时livekit-server list-nodes能列出当前所有已注册节点。容器化镜像怎么构建、怎么喂配置本节解决「容器里 LiveKit 的配置从哪来」的问题。仓库自带的 Dockerfile 采用多阶段构建Go 环境负责编译运行期只拷一个静态二进制进 Alpine构建前先用go mod download缓存依赖让源码改动不必反复拉依赖。FROM golang:1.26.6-alpine3.24 AS builder WORKDIR /workspace COPY go.mod go.mod COPY go.sum go.sum RUN go mod download COPY cmd/ cmd/ COPY pkg/ pkg/ COPY test/ test/ COPY version/ version/ RUN CGO_ENABLED0 GOOSlinux GOARCH$TARGETARCH go build -a -o livekit-server ./cmd/server FROM alpine:3.24.1 RUN apk upgrade --no-cache COPY --frombuilder /workspace/livekit-server /livekit-server ENTRYPOINT [/livekit-server]禁用 CGO 换来纯静态二进制Alpine 基础镜像再叠加apk upgrade补齐安全补丁最终镜像只含一个可执行文件。前置条件本地或 CI 有 Docker 与 buildx多架构构建时TARGETPLATFORM/TARGETARCH由 buildx 注入。操作步骤构建并运行。配置不必挂文件——--config-body参数对应环境变量LIVEKIT_CONFIG可以直接接收一段内联 YAML这对容器场景更省事。docker build -t livekit-server . docker run -d --name livekit \ -p 7880:7880 -p 7881:7881 -p 50000-60000:50000-60000/udp \ -e LIVEKIT_CONFIGport: 7880 keys: mykey: mysecret rtc: use_external_ip: true \ livekit-server验证方式docker exec livekit livekit-server ports打印容器内实际端口再从宿主机对 UDP 区间做一次打洞验证确认媒体通道可达。注意容器里默认use_external_ip应设为true因为容器看到的是内网 IP需要通过 STUN 发现公网地址。生产集群Redis 分布式 节点选择 TURN本节解决「单机扛不住了怎么横向扩展还保持路由正确」。一旦配置了 RedisLiveKit 就自动进入全分布式模式客户端可连到任意节点再由节点把房间路由到正确的机器上。前置条件一套可用的 Redis单机、哨兵或集群三选一配置里用不同字段表达。操作步骤在配置里声明 Redis 后集群的其余决策交给node_selector。redis: address: redis:6379 # 单机模式哨兵改用 sentinel_*集群改用 cluster_addresses password: mypassword node_selector: kind: sysload # any / sysload / cpuload / regionaware 四选一 sort_by: sysload # 多候选节点时的排序依据 sysload_limit: 0.7 # 每核负载超过该值就不再分配房间 region: us-west-2 # 使用 regionaware 时必填node_selector.kind决定房间如何挑节点sysload按系统负载、regionaware按地理就近。跨地域高可用时把region与各区域坐标写入配置配合regionaware让参与者就近落地。多节点路由与负载选择的实现集中在 pkg/routing/selector/。对于部分客户端所在网络如封禁打洞的办公网启用内嵌 TURN 兜底turn: enabled: true udp_port: 3478 # 默认 3478未跑 HTTP3 时可推荐用 443 tls_port: 5349 # 默认 5349无负载均衡时须改为 443 domain: turn.example.com验证方式多节点起好后用livekit-server list-nodes确认每个节点都已注册且负载分布合理livekit-server ports核对每台的 UDP 区间一致。可观测性Prometheus 指标、pprof 与日志采样本节解决「线上出问题时我怎么先看见问题」。LiveKit 默认把 Prometheus 指标暴露在:6789/metrics需要时通过prometheus段启用并可加鉴权。prometheus: port: 6789 # 默认 6789不配置则不暴露 logging: level: info # 默认 info生产建议 info 而非 debug json: true # 默认 false生产开 JSON 便于采集 sample: true # 默认 false高日志量时启用采样算法日志三件套的取舍很直接json: true让日志可被结构化采集sample: true在日志洪峰时按采样算法降频避免把磁盘写爆level保留info就能满足排障debug只留给开发。配置字段与默认值定义在 pkg/config/config.go严格模式下拼写错误的字段会直接启动失败这其实帮你挡掉了不少静默错误。前置条件有 Prometheus 抓取:6789的能力deploy/目录附带了现成的 Grafana 仪表盘 JSON。操作步骤让 Prometheus 抓取 metrics 端点导入 deploy/grafana/livekit-server-overview.json 作为仪表板。核心关注三类信号房间与参与者规模、每节点 CPU/内存、媒体包收发速率。验证方式仪表板里房间数应随lk room join的测试流量即时上涨再用--cpuprofile/--memprofile落一份 pprofgo tool pprof打开即可看热点函数。部署形态VM 或 Kubernetes的详细指引见 deploy/README.md。下一步按这个顺序把生产跑起来用livekit-server generate-keys生成强密钥对替换开发占位密钥并写入keys或key_file。在防火墙一次性放行整个 UDP 区间、7880 与 7881用livekit-server ports复核。接入 Redis 并选定node_selector.kind用list-nodes验证多节点注册。启用prometheus与logging.sample接入 Grafana把房间规模与节点负载设为首要告警。客户端网络复杂时再打开turn并用tcp_port作为 UDP 不可用时的最后回退。做到这些一个既能横向扩展、又能被持续观测的 LiveKit 生产集群就落地了。【免费下载链接】livekitEnd-to-end realtime stack for connecting humans and AI项目地址: https://gitcode.com/GitHub_Trending/li/livekit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考