如何部署 LiveKit从本地到 K8s 集群的完整指南含避坑清单【免费下载链接】livekitEnd-to-end realtime stack for connecting humans and AI项目地址: https://gitcode.com/GitHub_Trending/li/livekitLiveKit 是一个高性能的 WebRTC 实时音视频媒体服务器SFU负责媒体流的转发、拥塞控制和房间管理。这篇文章把 LiveKit 部署拆成三个真实场景——本地跑通、单机上生产、多节点集群——每段都直接给可复制的命令和最小配置最后附一份高频故障的避坑清单帮你在上线前把问题踩完。先说两个最常见的翻车现场看看你有没有中招信令能连上房间也建好了但视频一直黑屏/没声音——十有八九是 UDP 媒体端口没放行客户端的 ICE 握手根本走不通。单机撑住演示上线后并发一上来就卡——LiveKit 的转发能力跟 CPU 核数强相关单机扛不住不是配置问题是到了该上集群的时候。带着这两个问题往下看你就能快速定位自己属于哪个场景。先判断你处在哪一档LiveKit 部署选型决策表这一节帮你 30 秒定位「该读哪一段」避免一上来就被参数淹没。你的情况部署形态关键动作看哪一节本地开发 / Demo 验证二进制 --dev模式一条命令启动不用写配置场景一小团队生产、单台云主机Docker 单容器 Redis 可选放开 UDP 端口段、配keys、TLS 交给 LB场景二多机房 / 高并发 / 要扩缩容K8s 或 Docker Compose 多节点必须接 Redis考虑节点选择策略场景三判断依据很简单只要超过一个节点Redis 就是必选项——LiveKit 配了redis.address后自动进入全分布式模式客户端连到任何节点都会被路由到同一个房间。单节点则完全不需要。场景一本地最小配置3 分钟跑起 LiveKit这一节解决「我要马上看到服务跑起来」的问题。结论先行开发阶段不需要任何配置文件。一条命令启动livekit-server --dev--dev模式下 LiveKit 会自动做三件事日志级别调到 debug、使用内置占位密钥devkey/secret、并且只绑定 127.0.0.1这也是后面「远程连不上」类问题的根源之一。没有现成二进制从源码构建git clone https://gitcode.com/GitHub_Trending/li/livekit cd livekit ./bootstrap.sh # 安装 mage 构建工具链 mage build # 产出 bin/livekit-server ./bin/livekit-server --dev构建系统就是 Mage入口在 magefile.go改核心代码的同学可以直接看 pkg/sfu/转发核心和 pkg/rtc/房间与参与者逻辑。验证它真的活着livekit-server ports --config /dev/stdin port: 7880 # 7880 - HTTP service # 7881 - ICE/TCP # 50000-60000 - ICE/UDP rangeports子命令会把当前配置实际用到的端口全部打印出来是部署后第一件该做的事。场景二Docker 单机生产部署要点这一节解决「在一台云主机上用容器跑生产」的问题。关键只有四件事密钥、UDP 端口段、TLS 位置、公网 IP 发现。先换掉开发密钥生产上第一件事是生成正式密钥对别再让devkey出门livekit-server generate-keys # API Key: xxxxxxx # API Secret: xxxxxxx把这对 key/secret 写进配置的keys段客户端所有 join token 都用它签 JWT。密钥配错或客户端和服务端不一致症状就是 401。生产最小配置下面是砍到最少的生产配置只保留影响上线的四组参数其余照 config-sample.yaml 按需调整port: 7880 redis: address: redis.host:6379 # 单机可整段删掉多节点必填 rtc: port_range_start: 50000 # UDP 媒体端口段防火墙必须全量放行 port_range_end: 60000 tcp_port: 7881 # WebRTC 的 TCP 回退端口见下方注意 use_external_ip: true # 云服务器必开通过 STUN 发现公网 IP keys: my_api_key: my_secret⚠️ 两个容易踩的点tcp_port7881不能挂在负载均衡器或 TLS 后面它必须直接暴露到公网——WebRTC 传输本身已加密加一层 LB 反而会破坏 ICE over TCP。use_external_ip: true在 AWS/GCP 这类「内网 IP NAT 映射公网」的环境必须开否则服务端会把私网 IP 当候选地址发给客户端ICE 永远打不通。容器运行官方 Dockerfile 是多阶段构建golang 编译 alpine 运行CGO_ENABLED0拉现成镜像即可。运行命令的关键在端口映射一段 UDP 范围要整体暴露docker run -d --name livekit \ -p 7880:7880 \ -p 7881:7881 \ -p 50000-60000:50000-60000/udp \ -v ./config.yaml:/config.yaml \ livekit/livekit-server --config /config.yamlTLS 的推荐做法只对 7880信令 RoomService API做 TLS 终结放在 Nginx 或云 LB 后面即可媒体面UDP 段和 7881保持明文直达它们自带 DTLS/SRTP 加密。不想维护 YAML用环境变量覆盖LiveKit 的每个配置项都能用LIVEKIT_前缀的环境变量覆盖规则见 pkg/config/config.go 中的GenerateCLIFlagsdocker run -e LIVEKIT_REDIS_ADDRESSredis:6379 \ -e LIVEKIT_RTC_TCP_PORT7881 \ livekit/livekit-server这对 K8s 里不想挂 ConfigMap 的场景非常顺手。场景三多节点 / 集群部署Redis、扩缩容、监控这一节解决「单机扛不住了」的问题。集群化的核心就三根支柱Redis 做共享状态、节点选择做负载均衡、Prometheus 做可观测。Redis从单机切换到分布式只需给所有节点配上同一个 Redisredis: address: redis-host:6379 password: your_password # 哨兵模式则改用 sentinel_master_name sentinel_addresses生效后任意节点都能接收任意客户端的连接并路由到正确的房间。多节点部署的验证方式livekit-server list-nodes --config ./config.yaml它会以表格列出每个节点的 CPU、内存、房间数、在途轨道和丢包率——排障时这是第一现场。K8s 部署UDP 端口是唯一的大坑LiveKit 需要 50000-60000 一整段 UDP 直达客户端而 K8s 的 Service 对 UDP 端口段的支持很弱。实践中最稳的做法是hostNetworkspec: template: spec: hostNetwork: true # 直接用宿主机网络 dnsPolicy: ClusterFirstWithHostNet containers: - name: livekit image: livekit/livekit-server:latest # 7880 / 7881 / 50000-60000 直接落在宿主机⚠️ 由此推出两条硬规则同一台宿主机只能跑一个 LiveKit Pod否则 UDP 端口段互相冲突不要用privileged: true硬凑hostNetwork已经拿到了它需要的网络能力。信令面7880再叠一层普通 Service Ingress 做负载均衡和 TLS 即可UDP 面完全绕过它。扩缩容策略两层配合Pod 层HPA 按 CPU 利用率扩缩媒体服务器是 CPU 密集型用 CPU 比内存准minReplicas: 2起步。房间层LiveKit 自带节点选择器控制「新房间落到哪个节点」node_selector: kind: sysload # any / sysload / cpuload / regionaware sort_by: sysload sysload_limit: 0.7 # 单核负载超 0.7 就不再往这个节点塞房间跨地域部署时改用regionaware并给每个区域配经纬度房间会优先落在离用户最近的区域选项细节都在 config-sample.yaml 的注释里。容量预估参考limit段的默认值是每 CPU 核最多 400 条进出轨道上限 8000、整机 1 GB/s。粗略换算一场 10 人会议1 路视频 10 路音频约占 2 核一台 8 核机器大概能扛 20~30 场这样的会议。压测时用list-nodes的 CPU 列对照即可。LiveKit 部署避坑清单高频故障与排查这一节集中回答「我明明都配了为什么还不行」。全部按「现象 → 原因 → 解法」组织对照你的症状查。1. 能建房间但媒体流黑屏或单向无声现象信令 WebSocket 正常chrome://webrtc-internals里 ICE 卡在 checking。原因UDP 50000-60000 没在云安全组/防火墙放行入站或use_external_ip没开导致服务端把私网 IP 发给了客户端。解法全量放行 UDP 段云服务器开启use_external_ip: true手动指定公网 IP 则用node_ip。2. 服务起不来报端口占用现象address already in use。原因另一个实例占着 7880或旧容器没退干净还占着 UDP 段。解法ss -lntp | grep 7880找占用者K8s 里检查是否同节点跑了两个hostNetworkPod。3. 客户端 401 / token 无效现象join 直接被拒。原因签 token 用的 key 不在服务端keys里或本地还在用--dev的devkey而生产已换密钥。解法用livekit-server generate-keys重新生成确认服务端配置与客户端签发用同一对。4. 开发机能连换台机器就连不上现象--dev模式一切正常别的机器访问超时。原因dev 模式默认只绑定127.0.0.1/::1。解法去掉--dev或显式设置bind_addresses: [0.0.0.0]。5. K8s Pod 就绪了但客户端 ICE 超时现象HTTP 健康检查全绿媒体面全断。原因没开hostNetworkUDP 段被封装在 Pod 网段里NAT 根本透不出去。解法启用hostNetwork并接受「一节点一 Pod」的约束。6. 加了 LB 之后部分用户连不上现象信令正常但 TCP 回退路径失效。原因tcp_port被挂到了 L7 LB / TLS 终结后面。解法7881 必须走四层直连或独立暴露TLS 只终结 7880。进阶阅读按需指标、日志与调优这一节只在你要做长期运维或压测时看日常部署可以跳过。Prometheus 指标配置里打开一行即可指标暴露在:6789/metricsprometheus_port: 6789指标实现分布在 pkg/telemetry/prometheus/覆盖节点 CPU/内存、房间与参与者数、码率、NACK 重传等维度。仓库自带一块现成的 Grafana 面板deploy/grafana/livekit-server-overview.json直接导入。日志logging: level: info # debug / info / warn / error json: true # 生产开 JSON方便采集 sample: true # 高流量下采样防止日志风暴 pion_level: error # WebRTC 底层库的日志级别性能剖析livekit-server --cpuprofile cpu.pprof --memprofile mem.pprof配合go tool pprof定位热点另可开debug_handler_port把/debug/pprof挂到独立端口默认 7070不用每次重启取 profile。值得按需调整的参数参数默认什么时候动它rtc.udp_port关端口段不够/想收敛端口可用7882-7892这类小范围替代大段rtc.use_ice_litefalse确认服务器不在 NAT 后面时开启ICE 连接更快rtc.packet_buffer_size_video/audio500 / 200弱网多丢包场景调大代价是内存turn.enableddomainfalse有企业网络/移动网络用户时启用内置 TURNroom.empty_timeout/departure_timeout300s / 20s控制空房间何时回收LiveKit 部署行动清单照做即可最后给一份可直接勾选的 checklist按你的目标形态选一段执行本地开发5 分钟安装 Go 环境git clone后./bootstrap.sh mage build或直接下 release 二进制./bin/livekit-server --dev启动日志出现 starting in development mode用占位密钥devkey/secret签发 token客户端能进房间livekit-server ports核对实际使用的端口单机生产livekit-server generate-keys生成正式密钥替换keys段防火墙/安全组放行7880/tcp、7881/tcp、50000-60000/udp云服务器开启use_external_ip: trueDocker 运行时确认 UDP 端口段整体映射-p 50000-60000:50000-60000/udp7880 挂到 LB/Ingress 后做 TLS 终结7881 保持四层直连打开prometheus_port: 6789并接入监控多节点集群部署高可用 Redis单实例至少开appendonly正式上哨兵或集群模式每个节点指向同一 Redislivekit-server list-nodes能看到全部节点K8sPod 用hostNetwork 一节点一 Pod或等效的 hostPort 方案配置node_selectorsysload或regionaware与sysload_limitHPA 按 CPU 利用率设置minReplicas 2导入仓库自带的 Grafana 面板确认 NACK 重传率、CPU 负载两条曲线正常按这份清单走完你的 LiveKit 就从「能跑」走到「能扛」了。【免费下载链接】livekitEnd-to-end realtime stack for connecting humans and AI项目地址: https://gitcode.com/GitHub_Trending/li/livekit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何部署 LiveKit：从本地到 K8s 集群的完整指南（含避坑清单）
如何部署 LiveKit从本地到 K8s 集群的完整指南含避坑清单【免费下载链接】livekitEnd-to-end realtime stack for connecting humans and AI项目地址: https://gitcode.com/GitHub_Trending/li/livekitLiveKit 是一个高性能的 WebRTC 实时音视频媒体服务器SFU负责媒体流的转发、拥塞控制和房间管理。这篇文章把 LiveKit 部署拆成三个真实场景——本地跑通、单机上生产、多节点集群——每段都直接给可复制的命令和最小配置最后附一份高频故障的避坑清单帮你在上线前把问题踩完。先说两个最常见的翻车现场看看你有没有中招信令能连上房间也建好了但视频一直黑屏/没声音——十有八九是 UDP 媒体端口没放行客户端的 ICE 握手根本走不通。单机撑住演示上线后并发一上来就卡——LiveKit 的转发能力跟 CPU 核数强相关单机扛不住不是配置问题是到了该上集群的时候。带着这两个问题往下看你就能快速定位自己属于哪个场景。先判断你处在哪一档LiveKit 部署选型决策表这一节帮你 30 秒定位「该读哪一段」避免一上来就被参数淹没。你的情况部署形态关键动作看哪一节本地开发 / Demo 验证二进制 --dev模式一条命令启动不用写配置场景一小团队生产、单台云主机Docker 单容器 Redis 可选放开 UDP 端口段、配keys、TLS 交给 LB场景二多机房 / 高并发 / 要扩缩容K8s 或 Docker Compose 多节点必须接 Redis考虑节点选择策略场景三判断依据很简单只要超过一个节点Redis 就是必选项——LiveKit 配了redis.address后自动进入全分布式模式客户端连到任何节点都会被路由到同一个房间。单节点则完全不需要。场景一本地最小配置3 分钟跑起 LiveKit这一节解决「我要马上看到服务跑起来」的问题。结论先行开发阶段不需要任何配置文件。一条命令启动livekit-server --dev--dev模式下 LiveKit 会自动做三件事日志级别调到 debug、使用内置占位密钥devkey/secret、并且只绑定 127.0.0.1这也是后面「远程连不上」类问题的根源之一。没有现成二进制从源码构建git clone https://gitcode.com/GitHub_Trending/li/livekit cd livekit ./bootstrap.sh # 安装 mage 构建工具链 mage build # 产出 bin/livekit-server ./bin/livekit-server --dev构建系统就是 Mage入口在 magefile.go改核心代码的同学可以直接看 pkg/sfu/转发核心和 pkg/rtc/房间与参与者逻辑。验证它真的活着livekit-server ports --config /dev/stdin port: 7880 # 7880 - HTTP service # 7881 - ICE/TCP # 50000-60000 - ICE/UDP rangeports子命令会把当前配置实际用到的端口全部打印出来是部署后第一件该做的事。场景二Docker 单机生产部署要点这一节解决「在一台云主机上用容器跑生产」的问题。关键只有四件事密钥、UDP 端口段、TLS 位置、公网 IP 发现。先换掉开发密钥生产上第一件事是生成正式密钥对别再让devkey出门livekit-server generate-keys # API Key: xxxxxxx # API Secret: xxxxxxx把这对 key/secret 写进配置的keys段客户端所有 join token 都用它签 JWT。密钥配错或客户端和服务端不一致症状就是 401。生产最小配置下面是砍到最少的生产配置只保留影响上线的四组参数其余照 config-sample.yaml 按需调整port: 7880 redis: address: redis.host:6379 # 单机可整段删掉多节点必填 rtc: port_range_start: 50000 # UDP 媒体端口段防火墙必须全量放行 port_range_end: 60000 tcp_port: 7881 # WebRTC 的 TCP 回退端口见下方注意 use_external_ip: true # 云服务器必开通过 STUN 发现公网 IP keys: my_api_key: my_secret⚠️ 两个容易踩的点tcp_port7881不能挂在负载均衡器或 TLS 后面它必须直接暴露到公网——WebRTC 传输本身已加密加一层 LB 反而会破坏 ICE over TCP。use_external_ip: true在 AWS/GCP 这类「内网 IP NAT 映射公网」的环境必须开否则服务端会把私网 IP 当候选地址发给客户端ICE 永远打不通。容器运行官方 Dockerfile 是多阶段构建golang 编译 alpine 运行CGO_ENABLED0拉现成镜像即可。运行命令的关键在端口映射一段 UDP 范围要整体暴露docker run -d --name livekit \ -p 7880:7880 \ -p 7881:7881 \ -p 50000-60000:50000-60000/udp \ -v ./config.yaml:/config.yaml \ livekit/livekit-server --config /config.yamlTLS 的推荐做法只对 7880信令 RoomService API做 TLS 终结放在 Nginx 或云 LB 后面即可媒体面UDP 段和 7881保持明文直达它们自带 DTLS/SRTP 加密。不想维护 YAML用环境变量覆盖LiveKit 的每个配置项都能用LIVEKIT_前缀的环境变量覆盖规则见 pkg/config/config.go 中的GenerateCLIFlagsdocker run -e LIVEKIT_REDIS_ADDRESSredis:6379 \ -e LIVEKIT_RTC_TCP_PORT7881 \ livekit/livekit-server这对 K8s 里不想挂 ConfigMap 的场景非常顺手。场景三多节点 / 集群部署Redis、扩缩容、监控这一节解决「单机扛不住了」的问题。集群化的核心就三根支柱Redis 做共享状态、节点选择做负载均衡、Prometheus 做可观测。Redis从单机切换到分布式只需给所有节点配上同一个 Redisredis: address: redis-host:6379 password: your_password # 哨兵模式则改用 sentinel_master_name sentinel_addresses生效后任意节点都能接收任意客户端的连接并路由到正确的房间。多节点部署的验证方式livekit-server list-nodes --config ./config.yaml它会以表格列出每个节点的 CPU、内存、房间数、在途轨道和丢包率——排障时这是第一现场。K8s 部署UDP 端口是唯一的大坑LiveKit 需要 50000-60000 一整段 UDP 直达客户端而 K8s 的 Service 对 UDP 端口段的支持很弱。实践中最稳的做法是hostNetworkspec: template: spec: hostNetwork: true # 直接用宿主机网络 dnsPolicy: ClusterFirstWithHostNet containers: - name: livekit image: livekit/livekit-server:latest # 7880 / 7881 / 50000-60000 直接落在宿主机⚠️ 由此推出两条硬规则同一台宿主机只能跑一个 LiveKit Pod否则 UDP 端口段互相冲突不要用privileged: true硬凑hostNetwork已经拿到了它需要的网络能力。信令面7880再叠一层普通 Service Ingress 做负载均衡和 TLS 即可UDP 面完全绕过它。扩缩容策略两层配合Pod 层HPA 按 CPU 利用率扩缩媒体服务器是 CPU 密集型用 CPU 比内存准minReplicas: 2起步。房间层LiveKit 自带节点选择器控制「新房间落到哪个节点」node_selector: kind: sysload # any / sysload / cpuload / regionaware sort_by: sysload sysload_limit: 0.7 # 单核负载超 0.7 就不再往这个节点塞房间跨地域部署时改用regionaware并给每个区域配经纬度房间会优先落在离用户最近的区域选项细节都在 config-sample.yaml 的注释里。容量预估参考limit段的默认值是每 CPU 核最多 400 条进出轨道上限 8000、整机 1 GB/s。粗略换算一场 10 人会议1 路视频 10 路音频约占 2 核一台 8 核机器大概能扛 20~30 场这样的会议。压测时用list-nodes的 CPU 列对照即可。LiveKit 部署避坑清单高频故障与排查这一节集中回答「我明明都配了为什么还不行」。全部按「现象 → 原因 → 解法」组织对照你的症状查。1. 能建房间但媒体流黑屏或单向无声现象信令 WebSocket 正常chrome://webrtc-internals里 ICE 卡在 checking。原因UDP 50000-60000 没在云安全组/防火墙放行入站或use_external_ip没开导致服务端把私网 IP 发给了客户端。解法全量放行 UDP 段云服务器开启use_external_ip: true手动指定公网 IP 则用node_ip。2. 服务起不来报端口占用现象address already in use。原因另一个实例占着 7880或旧容器没退干净还占着 UDP 段。解法ss -lntp | grep 7880找占用者K8s 里检查是否同节点跑了两个hostNetworkPod。3. 客户端 401 / token 无效现象join 直接被拒。原因签 token 用的 key 不在服务端keys里或本地还在用--dev的devkey而生产已换密钥。解法用livekit-server generate-keys重新生成确认服务端配置与客户端签发用同一对。4. 开发机能连换台机器就连不上现象--dev模式一切正常别的机器访问超时。原因dev 模式默认只绑定127.0.0.1/::1。解法去掉--dev或显式设置bind_addresses: [0.0.0.0]。5. K8s Pod 就绪了但客户端 ICE 超时现象HTTP 健康检查全绿媒体面全断。原因没开hostNetworkUDP 段被封装在 Pod 网段里NAT 根本透不出去。解法启用hostNetwork并接受「一节点一 Pod」的约束。6. 加了 LB 之后部分用户连不上现象信令正常但 TCP 回退路径失效。原因tcp_port被挂到了 L7 LB / TLS 终结后面。解法7881 必须走四层直连或独立暴露TLS 只终结 7880。进阶阅读按需指标、日志与调优这一节只在你要做长期运维或压测时看日常部署可以跳过。Prometheus 指标配置里打开一行即可指标暴露在:6789/metricsprometheus_port: 6789指标实现分布在 pkg/telemetry/prometheus/覆盖节点 CPU/内存、房间与参与者数、码率、NACK 重传等维度。仓库自带一块现成的 Grafana 面板deploy/grafana/livekit-server-overview.json直接导入。日志logging: level: info # debug / info / warn / error json: true # 生产开 JSON方便采集 sample: true # 高流量下采样防止日志风暴 pion_level: error # WebRTC 底层库的日志级别性能剖析livekit-server --cpuprofile cpu.pprof --memprofile mem.pprof配合go tool pprof定位热点另可开debug_handler_port把/debug/pprof挂到独立端口默认 7070不用每次重启取 profile。值得按需调整的参数参数默认什么时候动它rtc.udp_port关端口段不够/想收敛端口可用7882-7892这类小范围替代大段rtc.use_ice_litefalse确认服务器不在 NAT 后面时开启ICE 连接更快rtc.packet_buffer_size_video/audio500 / 200弱网多丢包场景调大代价是内存turn.enableddomainfalse有企业网络/移动网络用户时启用内置 TURNroom.empty_timeout/departure_timeout300s / 20s控制空房间何时回收LiveKit 部署行动清单照做即可最后给一份可直接勾选的 checklist按你的目标形态选一段执行本地开发5 分钟安装 Go 环境git clone后./bootstrap.sh mage build或直接下 release 二进制./bin/livekit-server --dev启动日志出现 starting in development mode用占位密钥devkey/secret签发 token客户端能进房间livekit-server ports核对实际使用的端口单机生产livekit-server generate-keys生成正式密钥替换keys段防火墙/安全组放行7880/tcp、7881/tcp、50000-60000/udp云服务器开启use_external_ip: trueDocker 运行时确认 UDP 端口段整体映射-p 50000-60000:50000-60000/udp7880 挂到 LB/Ingress 后做 TLS 终结7881 保持四层直连打开prometheus_port: 6789并接入监控多节点集群部署高可用 Redis单实例至少开appendonly正式上哨兵或集群模式每个节点指向同一 Redislivekit-server list-nodes能看到全部节点K8sPod 用hostNetwork 一节点一 Pod或等效的 hostPort 方案配置node_selectorsysload或regionaware与sysload_limitHPA 按 CPU 利用率设置minReplicas 2导入仓库自带的 Grafana 面板确认 NACK 重传率、CPU 负载两条曲线正常按这份清单走完你的 LiveKit 就从「能跑」走到「能扛」了。【免费下载链接】livekitEnd-to-end realtime stack for connecting humans and AI项目地址: https://gitcode.com/GitHub_Trending/li/livekit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考