feat(webrtc): add configurable STUN and TURN servers

Add backend config, RPC handlers, and an HTTP endpoint for WebRTC ICE servers. Replace hardcoded frontend STUN usage with server-provided ICE server configuration, and add access settings UI for STUN and TURN entries.
2026-05-27 08:35:10 +02:00 · 2026-05-03 16:43:29 +08:00
parent d5bfaffd86
commit f1a6c75fc0
12 changed files with 354 additions and 31 deletions
--- a/ui/src/components/Macro/Combobox.tsx
+++ b/ui/src/components/Macro/Combobox.tsx
@@ -27,7 +27,7 @@ const comboboxVariants = cva({
  variants: { size: sizes },
 });

-type BaseProps = React.ComponentProps<typeof HeadlessCombobox>;
+type BaseProps = React.ComponentProps<typeof HeadlessCombobox<ComboboxOption>>;

 interface ComboboxProps extends Omit<BaseProps, "displayValue"> {
  displayValue: (option: ComboboxOption) => string;
--- a/ui/src/components/Macro/MacroStepCard.tsx
+++ b/ui/src/components/Macro/MacroStepCard.tsx
@@ -205,7 +205,8 @@ export function MacroStepCard({
          )}
          <div className="relative w-full">
            <Combobox
-              onChange={(value: { value: string; label: string }) => {
+              onChange={value => {
+                if (!value) return;
                onKeySelect(value);
                onKeyQueryChange('');
              }}
@@ -239,4 +240,4 @@ export function MacroStepCard({
      </div>
    </Card>
  );
-} 
+} 
--- a/ui/src/layout/components_setting/access/AccessContent.tsx
+++ b/ui/src/layout/components_setting/access/AccessContent.tsx
@@ -23,6 +23,7 @@ import { LogDialog } from "@components/LogDialog";
 import { Dialog } from "@/layout/components_setting/access/auth";
 import AutoHeight from "@components/AutoHeight";
 import FirewallSettings from "./FirewallSettings";
+import WebRtcServersSettings from "./WebRtcServers";

 export interface TailScaleResponse {
  state: string;
@@ -997,6 +998,20 @@ function AccessContent({ setOpenDialog }: { setOpenDialog: (open: boolean) => vo
        </>
      )}

+      <div className="space-y-4">
+        <SettingsSectionHeader
+          title={$at("WebRTC Servers")}
+          description={$at("STUN and TURN servers used for peer connections")}
+        />
+        <GridCard>
+          <AutoHeight>
+            <div className="space-y-4 p-4">
+              <WebRtcServersSettings />
+            </div>
+          </AutoHeight>
+        </GridCard>
+      </div>
+
      <div className="space-y-4">
        <SettingsSectionHeader
          title={$at("Remote")}
--- a/ui/src/layout/components_setting/access/WebRtcServers.tsx
+++ b/ui/src/layout/components_setting/access/WebRtcServers.tsx
@@ -0,0 +1,159 @@
+import { useEffect, useState } from "react";
+import { useReactAt } from "i18n-auto-extractor/react";
+
+import { useJsonRpc } from "@/hooks/useJsonRpc";
+import notifications from "@/notifications";
+import { Button } from "@components/Button";
+import { InputField } from "@components/InputField";
+import { SettingsItem } from "@components/Settings/SettingsView";
+
+interface TurnServer {
+  url: string;
+  username: string;
+  credential: string;
+}
+
+interface RtcServersConfig {
+  stun: string;
+  defaultStun: string;
+  turnServers: TurnServer[] | null;
+}
+
+export default function WebRtcServersSettings() {
+  const { $at } = useReactAt();
+  const [send] = useJsonRpc();
+
+  const [stun, setStun] = useState("");
+  const [defaultStun, setDefaultStun] = useState("");
+  const [turnServers, setTurnServers] = useState<TurnServer[]>([]);
+
+  useEffect(() => {
+    send("getRtcServersConfig", {}, resp => {
+      if ("error" in resp) {
+        notifications.error(`${$at("Failed to load WebRTC servers")}: ${resp.error.data || $at("Unknown error")}`);
+        return;
+      }
+
+      const cfg = resp.result as RtcServersConfig;
+      setDefaultStun(cfg.defaultStun);
+      setStun(cfg.stun || cfg.defaultStun);
+      setTurnServers(cfg.turnServers ?? []);
+    });
+  }, [send]);
+
+  const saveStun = (value: string) => {
+    send("setStunServer", { stun: value }, resp => {
+      if ("error" in resp) {
+        notifications.error(`${$at("Failed to save STUN")}: ${resp.error.data || $at("Unknown error")}`);
+        return;
+      }
+
+      setStun(value);
+      notifications.success($at("STUN server saved"));
+    });
+  };
+
+  const persistTurnServers = (servers: TurnServer[]) => {
+    send("setTurnServers", { params: { servers } }, resp => {
+      if ("error" in resp) {
+        notifications.error(`${$at("Failed to save TURN")}: ${resp.error.data || $at("Unknown error")}`);
+        return;
+      }
+
+      setTurnServers(servers);
+      notifications.success($at("TURN servers saved"));
+    });
+  };
+
+  const updateTurnRow = (index: number, field: keyof TurnServer, value: string) => {
+    setTurnServers(prev => prev.map((server, i) => (i === index ? { ...server, [field]: value } : server)));
+  };
+
+  const addTurnRow = () => {
+    setTurnServers(prev => [...prev, { url: "", username: "", credential: "" }]);
+  };
+
+  const deleteTurnRow = (index: number) => {
+    persistTurnServers(turnServers.filter((_, i) => i !== index));
+  };
+
+  return (
+    <div className="space-y-6">
+      <SettingsItem
+        title={$at("STUN Server")}
+        description={$at("Public STUN server for NAT traversal")}
+        noCol
+      >
+        <div className="flex w-full max-w-2xl flex-col gap-2 sm:flex-row">
+          <InputField
+            value={stun}
+            onChange={e => setStun(e.target.value)}
+            placeholder={defaultStun}
+            className="min-w-0"
+          />
+          <div className="flex shrink-0 gap-2">
+            <Button size="MD" theme="primary" text={$at("Save")} onClick={() => saveStun(stun)} />
+            <Button
+              size="MD"
+              theme="light"
+              text={$at("Restore Default")}
+              onClick={() => saveStun(defaultStun)}
+            />
+          </div>
+        </div>
+      </SettingsItem>
+
+      <div className="space-y-0.5">
+        <div className="text-base font-semibold text-black dark:text-white">
+          {$at("TURN Servers")}
+        </div>
+        <div className="text-sm text-slate-700 dark:text-slate-300">
+          {$at("Used as relay when direct peer-to-peer connection fails")}
+        </div>
+      </div>
+
+      <div className="space-y-3">
+        {turnServers.length === 0 && (
+          <div className="text-sm text-slate-500 dark:text-slate-400">{$at("No TURN servers configured")}</div>
+        )}
+
+        {turnServers.map((server, index) => (
+          <div key={index} className="grid gap-2 lg:grid-cols-[minmax(220px,1fr)_minmax(120px,180px)_minmax(120px,180px)_auto]">
+            <InputField
+              value={server.url}
+              onChange={e => updateTurnRow(index, "url", e.target.value)}
+              placeholder="turn:turn.example.com:3478"
+            />
+            <InputField
+              value={server.username}
+              onChange={e => updateTurnRow(index, "username", e.target.value)}
+              placeholder={$at("Username")}
+            />
+            <InputField
+              value={server.credential}
+              onChange={e => updateTurnRow(index, "credential", e.target.value)}
+              placeholder={$at("Credential")}
+              type="password"
+            />
+            <Button
+              size="MD"
+              theme="lightDanger"
+              text={$at("Delete")}
+              onClick={() => deleteTurnRow(index)}
+            />
+          </div>
+        ))}
+
+        <div className="flex flex-wrap gap-2">
+          <Button size="MD" theme="light" text={$at("Add TURN Server")} onClick={addTurnRow} />
+          <Button
+            size="MD"
+            theme="primary"
+            text={$at("Save TURN Servers")}
+            onClick={() => persistTurnServers(turnServers)}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
--- a/ui/src/layout/index.mobile.tsx
+++ b/ui/src/layout/index.mobile.tsx
@@ -33,6 +33,7 @@ import {
  useSettingsStore,
 useVpnStore } from "@/hooks/stores";
 import { JsonRpcRequest, useJsonRpc, resetHttpSessionId } from "@/hooks/useJsonRpc";
+import api from "@/api";
 import Modal from "@components/Modal";
 import { useDeviceUiNavigation } from "@/hooks/useAppNavigation";
 import {
@@ -351,6 +352,18 @@ export default function MobileHome() {
    try {
      console.log("[setupPeerConnection] Creating peer connection");
      setLoadingMessage("Creating peer connection...");
+      let fetchedIceServers: RTCIceServer[] = [];
+      if (!iceConfig?.iceServers) {
+        try {
+          const res = await api.GET("/api/ice-servers");
+          const data = await res.json();
+          fetchedIceServers = data.iceServers ?? [];
+        } catch (e) {
+          console.error("failed to fetch ICE servers, fallback", e);
+          fetchedIceServers = [{ urls: ["stun:stun.l.google.com:19302"] }];
+        }
+      }
+
      pc = new RTCPeerConnection({
        // We only use STUN or TURN servers if we're in the cloud
        //...(isInCloud && iceConfig?.iceServers
@@ -358,13 +371,7 @@ export default function MobileHome() {
        //  : {}),
        ...(iceConfig?.iceServers
          ? { iceServers: [iceConfig?.iceServers] }
-          : {
-            iceServers: [
-              {
-                urls: ['stun:stun.l.google.com:19302']
-              }
-            ]
-          }),
+          : { iceServers: fetchedIceServers }),
      });

      setPeerConnectionState(pc.connectionState);
--- a/ui/src/layout/index.pc.tsx
+++ b/ui/src/layout/index.pc.tsx
@@ -363,6 +363,18 @@ export default function PCHome() {
    try {
      console.log("[setupPeerConnection] Creating peer connection");
      setLoadingMessage("Creating peer connection...");
+      let fetchedIceServers: RTCIceServer[] = [];
+      if (!iceConfig?.iceServers) {
+        try {
+          const res = await api.GET("/api/ice-servers");
+          const data = await res.json();
+          fetchedIceServers = data.iceServers ?? [];
+        } catch (e) {
+          console.error("failed to fetch ICE servers, fallback", e);
+          fetchedIceServers = [{ urls: ["stun:stun.l.google.com:19302"] }];
+        }
+      }
+
      pc = new RTCPeerConnection({
        // We only use STUN or TURN servers if we're in the cloud
        //...(isInCloud && iceConfig?.iceServers
@@ -370,13 +382,7 @@ export default function PCHome() {
        //  : {}),
        ...(iceConfig?.iceServers
          ? { iceServers: [iceConfig?.iceServers] }
-          : {
-            iceServers: [
-              {
-                urls: ['stun:stun.l.google.com:19302']
-              }
-            ]
-          }),
+          : { iceServers: fetchedIceServers }),
      });

      setPeerConnectionState(pc.connectionState);
--- a/ui/src/locales/en.json
+++ b/ui/src/locales/en.json
@@ -571,5 +571,23 @@
  "65f1314580": "Confirm your password",
  "af21497286": "Set Password",
  "c3f88872d6": "This password will be used to secure your device data and protect against unauthorized access.",
-  "06a7b3bf6e": "All data remains on your local device."
-}
+  "06a7b3bf6e": "All data remains on your local device.",
+  "d6d56d5972": "WebRTC Servers",
+  "8bea04c48e": "STUN and TURN servers used for peer connections",
+  "4cd48aed7f": "STUN server saved",
+  "f6f10b4517": "TURN servers saved",
+  "d235995f96": "STUN Server",
+  "fc1bd2c935": "Public STUN server for NAT traversal",
+  "289929755b": "Restore Default",
+  "0268827609": "TURN Servers",
+  "b3c14a0273": "Used as relay when direct peer-to-peer connection fails",
+  "bbc48fb751": "No TURN servers configured",
+  "f6039d44b2": "Username",
+  "03bc142e64": "Credential",
+  "ca3e8baee9": "Add TURN Server",
+  "0acde1b3e3": "Save TURN Servers",
+  "6f20995c95": "Failed to load WebRTC servers",
+  "6ef7ce5b80": "Failed to save STUN",
+  "4b5d050e51": "Failed to save TURN",
+  "aee9784c03": "Unknown error"
+}
--- a/ui/src/locales/zh.json
+++ b/ui/src/locales/zh.json
@@ -571,5 +571,23 @@
  "65f1314580": "确认您的密码",
  "af21497286": "设置密码",
  "c3f88872d6": "此密码将用于保护您的设备数据并防止未经授权的访问。",
-  "06a7b3bf6e": "所有数据保留在您的本地设备上。"
-}
+  "06a7b3bf6e": "所有数据保留在您的本地设备上。",
+  "d6d56d5972": "WebRTC 服务器",
+  "8bea04c48e": "用于点对点连接的 STUN 和 TURN 服务器",
+  "4cd48aed7f": "STUN 服务器已保存",
+  "f6f10b4517": "TURN 服务器已保存",
+  "d235995f96": "STUN 服务器",
+  "fc1bd2c935": "用于 NAT 穿透的公共 STUN 服务器",
+  "289929755b": "恢复默认",
+  "0268827609": "TURN 服务器",
+  "b3c14a0273": "当直接点对点连接失败时用作中继",
+  "bbc48fb751": "未配置 TURN 服务器",
+  "f6039d44b2": "用户名",
+  "03bc142e64": "凭据",
+  "ca3e8baee9": "添加 TURN 服务器",
+  "0acde1b3e3": "保存 TURN 服务器",
+  "6f20995c95": "加载 WebRTC 服务器失败",
+  "6ef7ce5b80": "保存 STUN 失败",
+  "4b5d050e51": "保存 TURN 失败",
+  "aee9784c03": "未知错误"
+}