Add WebRTC TURN configuration and related enhancements

- Introduce a new `.env.example` file for environment variable setup, including `PUBLIC_IP`, `TURN_SECRET`, and `TURN_URLS` for WebRTC TURN server configuration.
- Update `docker-compose.yaml` to support TURN server deployment with necessary environment variables and commands.
- Enhance backend configuration and routes to include WebRTC ICE server settings, allowing for STUN/TURN server integration.
- Implement a new service for managing WebRTC ICE server configurations, providing credentials for TURN when configured.
- Modify frontend API to fetch ICE server configurations dynamically, improving support for cross-network voice preview.

backend/.env.example

@@ -31,5 +31,12 @@ DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/postgres
 # ---- 服务监听 & 跨域 ----
 HOST=0.0.0.0
 PORT=8000
-# 前端开发地址,允许跨域
+# 前端开发地址,允许跨域(公网部署时加上实际前端 origin)
 CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+
+# ---- WebRTC TURN(公网跨网语音预览;本地开发留空) ----
+# 与 docker compose --profile remote 的 coturn 配套。云安全组需放行 UDP 3478 与 49152-49200。
+# PUBLIC_IP 填云主机公网 IP(compose 里给 coturn --external-ip 用,见项目根 .env)。
+# TURN_URLS=turn:182.92.86.220:3478?transport=udp,turn:182.92.86.220:3478?transport=tcp
+# TURN_SECRET=your-turn-secret
+# TURN_CREDENTIAL_TTL=86400

backend/app.py

@@ -9,6 +9,7 @@
   /api/model-resources 模型资源 CRUD
   /ws/voice            WebRTC 输出(浏览器)
   /ws/stream           WS 输出(裸音频流)
+  /api/webrtc/ice-servers  WebRTC STUN/TURN 配置
 """
 
 from contextlib import asynccontextmanager

backend/config.py

@@ -43,3 +43,13 @@ PORT = int(os.getenv("PORT", "8000"))
 CORS_ORIGINS = _split(
     os.getenv("CORS_ORIGINS", "http://localhost:3000,http://127.0.0.1:3000")
 )
+
+# ---- WebRTC TURN(公网跨网语音预览;本地开发留空即可) ----
+# TURN_URLS 示例:turn:182.92.86.220:3478?transport=udp,turn:182.92.86.220:3478?transport=tcp
+TURN_URLS = _split(os.getenv("TURN_URLS", ""))
+# coturn --use-auth-secret 时与 --static-auth-secret 一致;后端据此签发短时凭证
+TURN_SECRET = os.getenv("TURN_SECRET", "")
+# 不用 secret 时可改静态账号(需 coturn --user=...)
+TURN_USERNAME = os.getenv("TURN_USERNAME", "")
+TURN_PASSWORD = os.getenv("TURN_PASSWORD", "")
+TURN_CREDENTIAL_TTL = int(os.getenv("TURN_CREDENTIAL_TTL", "86400"))

backend/routes/voice_webrtc.py

@@ -17,17 +17,17 @@ from models import AssistantConfig, SignalingOffer
 from services.config_resolver import resolve_runtime_config
 from starlette.websockets import WebSocketDisconnect, WebSocketState
 
-# 注意:pipecat / aiortc 都是重依赖(语音才用),改成函数内"惰性导入",
-# 这样不装 pipecat 也能启动后端、验证 CRUD。语音真正用到时才加载。
+from services.webrtc_ice import aiortc_ice_servers, client_ice_servers
 
-router = APIRouter()
+# 注意:pipecat 是重依赖(语音才用),在 _handle_offer 等处惰性导入。
+
+router = APIRouter(tags=["voice"])
 
 
-def _ice_servers():
-    from aiortc import RTCIceServer
-
-    # 本地只用 STUN;公网部署在此追加 TURN(参考 dograh get_ice_servers)
-    return [RTCIceServer(urls="stun:stun.l.google.com:19302")]
+@router.get("/api/webrtc/ice-servers")
+async def ice_servers():
+    """Browser fetches STUN/TURN config (with ephemeral TURN creds when configured)."""
+    return {"iceServers": client_ice_servers()}
 
 
 @router.websocket("/ws/voice")
@@ -87,7 +87,7 @@ async def _handle_offer(websocket, payload, peers):
         await pc.renegotiate(sdp=offer.sdp, type=offer.type, restart_pc=False)
     else:
         cfg = await _resolve_config(offer)  # 解析放在建连前,配置错就别建连
-        pc = SmallWebRTCConnection(ice_servers=_ice_servers())
+        pc = SmallWebRTCConnection(ice_servers=aiortc_ice_servers())
         if pc_id:
             pc._pc_id = pc_id
         await pc.initialize(sdp=offer.sdp, type=offer.type)

backend/services/webrtc_ice.py

@@ -0,0 +1,60 @@
+"""WebRTC ICE server config: STUN + optional TURN for cross-network voice preview."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import time
+
+import config
+
+STUN_URL = "stun:stun.l.google.com:19302"
+
+
+def _turn_credentials() -> tuple[str, str] | None:
+    """Return (username, credential) for TURN, or None when TURN is not configured."""
+    if not config.TURN_URLS:
+        return None
+    if config.TURN_SECRET:
+        expiry = int(time.time()) + config.TURN_CREDENTIAL_TTL
+        username = f"{expiry}:ai-video"
+        credential = base64.b64encode(
+            hmac.new(
+                config.TURN_SECRET.encode("utf-8"),
+                username.encode("utf-8"),
+                hashlib.sha1,
+            ).digest()
+        ).decode("utf-8")
+        return username, credential
+    if config.TURN_USERNAME and config.TURN_PASSWORD:
+        return config.TURN_USERNAME, config.TURN_PASSWORD
+    return None
+
+
+def client_ice_servers() -> list[dict]:
+    """ICE servers for browser RTCPeerConnection (JSON-serializable)."""
+    servers: list[dict] = [{"urls": STUN_URL}]
+    creds = _turn_credentials()
+    if not creds:
+        return servers
+    username, credential = creds
+    for url in config.TURN_URLS:
+        servers.append({"urls": url, "username": username, "credential": credential})
+    return servers
+
+
+def aiortc_ice_servers() -> list:
+    """ICE servers for backend SmallWebRTCConnection / aiortc."""
+    from aiortc import RTCIceServer
+
+    servers = [RTCIceServer(urls=STUN_URL)]
+    creds = _turn_credentials()
+    if not creds:
+        return servers
+    username, credential = creds
+    for url in config.TURN_URLS:
+        servers.append(
+            RTCIceServer(urls=url, username=username, credential=credential)
+        )
+    return servers