LiveKit Python SDK 连接超时问题排查指南

问题现象

在使用LiveKit Python SDK连接自建LiveKit服务器时，开发者遇到了连接超时的问题。具体表现为：

1. 客户端能够成功获取访问令牌
2. 随后进入连接重试循环，显示"wait_pc_connection timed out"警告
3. 服务器端日志显示RTC会话已启动，但连接未能成功建立
4. Caddy服务器日志显示TLS证书验证错误

问题分析

从日志信息来看，问题涉及多个层面的网络连接：

1. WebRTC连接层面：客户端无法与服务器建立PeerConnection，这通常与ICE候选交换或网络配置有关
2. 信令层面：虽然WebSocket连接似乎已建立（显示连接URL），但后续的WebRTC协商失败
3. TLS层面：Caddy服务器报告了证书验证错误，这可能是导致连接失败的根源之一

解决方案

经过排查，最终发现问题的根本原因是服务器未开放必要的UDP端口范围。LiveKit的WebRTC通信需要以下端口配置：

1. 基础端口：

   • 443 (HTTPS/WebSocket)
   • 3478 (STUN)
   • 5349 (STUN over TLS)
   • 7881 (默认RTC端口)

2. 关键补充配置：

   • UDP 30000-40000：这是WebRTC媒体传输使用的端口范围，必须开放才能建立音视频流传输通道

配置建议

对于自建LiveKit服务器，建议检查以下配置项：

1. 防火墙设置：

   • 确保上述所有端口在服务器防火墙中开放
   • 特别注意UDP协议的放行

2. 证书配置：

   • 确保证书链完整，包括中间证书
   • 检查证书是否被客户端信任（特别是自签名证书情况）

3. TURN服务器：

   • 如果使用TURN服务，确保相关端口和认证配置正确

最佳实践

1. 部署完成后，使用LiveKit官方提供的连接测试工具进行全面验证
2. 对于生产环境，建议使用受信任的CA颁发的证书
3. 监控服务器日志，特别是与ICE候选交换相关的信息
4. 在客户端实现适当的错误处理和重试机制

总结

LiveKit作为实时音视频通信平台，其连接建立涉及复杂的网络协商过程。当遇到连接问题时，应系统性地检查信令通道、证书验证和媒体传输通道三个关键环节。本例中的UDP端口范围配置是一个容易被忽视但至关重要的设置项，开发者在部署自建LiveKit服务器时应特别注意。