若workbuddy音视频通话黑屏无声，大概率是turn服务器未正确配置或不可达；需依次检查coturn服务状态与端口监听、客户端iceservers中turn地址与凭据、coturn配置文件的auth-secret/realm/external-ip、用trickle ice工具验证relay候选、以及防火墙/安全组是否放行3478/5349/49152-65535端口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您已完成WorkBuddy安装并尝试发起音视频通话，但始终无法建立媒体连接或出现黑屏无声现象，则很可能是由于TURN服务器未正确配置或不可达，导致WebRTC在对称NAT等复杂网络环境下无法完成中继通信。以下是排查与修复该问题的具体步骤：
一、验证coturn服务是否已启动并监听指定端口
WorkBuddy依赖外部coturn服务器提供UDP/TCP中继能力；若服务未运行、端口被占用或绑定地址错误，所有需中继的音视频流将直接失败。
1、在部署coturn的服务器上执行命令：sudo systemctl status coturn，确认服务状态为“active (running)”。
2、若服务未运行，执行：sudo systemctl start coturn 并检查日志：sudo journalctl -u coturn -n 50 --no-pager，确认无“Failed to bind”或“Address already in use”报错。
3、使用netstat验证端口监听情况：sudo netstat -tuln | grep -E ':(3478|5349|49152-65535)'，确保3478（STUN/TURN）、5349（TLS TURN）及分配的RTP端口段（如49152–65535）均处于LISTEN状态。
二、检查WorkBuddy客户端iceServers配置是否指向有效TURN地址
客户端必须明确声明TURN服务器URL、凭证及传输协议；若配置缺失、格式错误或凭据过期，RTCPeerConnection将跳过TURN候选收集，仅依赖不可靠的STUN映射。
1、打开WorkBuddy安装目录下的config.json或application.yml文件。
2、定位webrtc.iceServers数组，确认至少包含一项形如：{"urls":"turn:your-turn-domain.com:3478","username":"workbuddy","credential":"valid-secret"} 的TURN条目。
3、检查urls字段是否使用turn:而非stun:前缀，且端口与coturn实际监听端口一致；credential值须与coturn配置文件（如/etc/turnserver.conf）中static-auth-secret完全相同。
三、确认coturn配置文件中关键参数已启用并匹配客户端需求
coturn需显式开启长期凭证机制、允许匿名用户（若适用）、正确设置realm和外网IP映射，否则客户端获取的TURN token将被拒绝或无法路由到真实终端。
1、编辑/etc/turnserver.conf，逐项核对以下参数：
2、确认存在且未被注释：use-auth-secret 和 static-auth-secret=valid-secret（值须与客户端配置一致）。
WorkBuddy 桌宠工厂 —— 给一张角色图、一个 codex.pet 链接、一条 codex-pets.net 下载 URL、或一份现成的精灵表，就能自动创建一只可联动 WorkBuddy 状态的桌面宠物。当用户说"创建桌宠"、"做一只桌宠"、"用这张图做桌宠"、"从 codex.pet 安装桌宠"、"导入 codex 桌宠 XX"、"装一下 codex-pets.net 上的 XX&quo
3、检查realm=your-turn-domain.com 是否与客户端请求中的realm匹配；若未设realm，客户端需省略realm字段，但建议显式配置。
4、确认external-ip=公网IP或域名 已正确填写，且该IP可被WorkBuddy客户端网络访问；若部署于内网，需配置端口转发并填写映射后的公网地址。
5、保存后执行：sudo systemctl restart coturn 使配置生效。
四、使用Trickle ICE工具独立测试TURN连通性
绕过WorkBuddy直接验证TURN服务可用性，可排除客户端集成逻辑干扰，快速定位是服务端问题还是配置传递问题。
1、访问在线测试页：https://test.webrtc.org/ 或 https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/。
2、在“STUN/TURN URIs”输入框中粘贴完整TURN URL，例如：turn:your-turn-domain.com:3478?transport=udp，并填入对应username与credential。
3、点击“Add Server”后点击“Gather candidates”，观察结果列表中是否出现类型为relay且状态为Succeeded的候选地址；若全部为failed或无relay条目，则TURN服务不可用或凭据错误。
五、检查防火墙与安全组策略是否放行TURN必需端口
即使coturn进程运行正常，若系统防火墙（iptables/nftables）、云服务商安全组或企业网关拦截了UDP/TCP流量，TURN通信仍会静默中断。
1、Linux服务器执行：sudo ufw status verbose（若启用ufw），确认3478、5349及RTP端口段（如49152–65535）的UDP/TCP规则为ALLOW。
2、云服务器（如阿里云、腾讯云）控制台中，进入“安全组”页面，检查入方向规则是否开放：UDP:3478,5349,49152-65535 及 TCP:3478,5349,49152-65535。
3、若使用企业级防火墙（如FortiGate、深信服），需额外确认其未启用SIP/RTSP ALG（应用层网关）功能，该功能会破坏WebRTC的ICE协商包。
