共享与远程访问¶

VoiceStudio 默认仅限本机运行 — 后端绑定到 127.0.0.1，其他机器无法访问任何内容。当你希望从另一台设备使用同一个运行中的实例（相同的已加载模型、相同的项目和任务）时，有两种可选方式。两者都不会重启后端或中断正在进行的工作。

局域网共享（同一 Wi-Fi / 以太网）¶

适用于同一网络上的另一台设备 — 例如在手机或第二台笔记本电脑上打开 Web UI。

1. 在页脚中，点击 Local（本机）胶囊按钮 → 确认 Network（网络）。
2. 将出现一个面板，列出此机器的每个可达地址（http://<ip>:<port>），每个地址都带有：
3. QR code（二维码） — 用手机/平板扫描即可打开已预认证的 UI，
4. copy（复制） 和 open-in-browser（在浏览器中打开） 按钮，
5. access PIN（访问 PIN）。
6. 在另一台设备上，扫描二维码（或打开 URL 并在提示时输入 PIN）。请使用面板显示的 IP 地址：类似 mypc.lan 的路由器 DNS 名称会被拒绝，除非它被列入 OMNIVOICE_ALLOWED_HOSTS（参见 主机名）。
7. 点击 Stop sharing（停止共享）（或切回 Local）以再次关闭网络套接字。

你也可以在 Settings → Sharing & Remote Access（设置 → 共享与远程访问）中操作。

地址列表按最佳优先排序：当前活动的 Wi-Fi 或以太网连接的地址（即使 VPN 持有默认路由），然后是其他物理适配器，再是虚拟适配器（Docker、WSL/Hyper-V、VirtualBox/VMware），再是 VPN 和 Tailscale 地址。已关闭的适配器会被排除。

其他设备显示“无法连接”¶

共享开启时，Settings → Sharing & Remote Access（设置 → 共享与远程访问）会显示自检：共享监听器绑定的地址和端口（0.0.0.0:<port>，每个接口），以及列出的每个地址是否能从本机响应。切换网络后使用刷新按钮；URL 和二维码会跟随新地址。

• 某个地址显示警告： 监听器在该地址上没有响应。停止并重启共享；如果仍然如此，说明另一个程序占用了端口，可在 Ports（端口） 下设置不同的 LAN share port（局域网共享端口）。
• 所有地址都有响应，但其他设备仍无法连接： 两台设备之间的连接被阻止。自检运行在本机上，因此无法看到以下情况：
• 不同网络。 两台设备必须处于同一 Wi-Fi 或局域网。访客网络以及启用了 client（客户端隔离）或 AP isolation（AP 隔离）的路由器会阻止设备到设备的流量。使用移动数据的手机无法访问局域网地址。
• 地址错误。 使用列表中的第一个地址。诸如 172.17.x.x（Docker）、172.2x.x.x（WSL/Hyper-V）、192.168.56.x（VirtualBox）或 VPN 地址等只能从本机访问。
• Windows Defender 防火墙。 首次启动共享时，Windows 会询问是否允许 VoiceStudio 后端（VoiceStudio 安装目录中的 python.exe）访问网络。请在专用网络上允许它，并将 Wi-Fi 设为专用（设置 → 网络和 Internet → Wi-Fi → 你的网络 → 专用网络）；在公用网络上，Windows 会阻止入站连接。如果你忽略了提示，请打开 Windows 安全中心 → 防火墙和网络保护 → 允许应用通过防火墙，并为该 python.exe 勾选专用。
• macOS 防火墙。 如果系统设置 → 网络 → 防火墙已开启，请在 macOS 询问时允许 VoiceStudio 后端的传入连接，或在 Options（选项） 下添加它。阻止所有传入连接必须关闭。
• Linux 防火墙。 允许共享端口，例如 sudo ufw allow 3901/tcp 或 sudo firewall-cmd --add-port=3901/tcp。
• 任一台设备上的 VPN。 启用了阻止本地网络（或 kill switch）设置的 VPN 会阻止局域网流量。请允许本地网络访问或关闭 VPN。
• 页面打开但要求输入 PIN： 输入面板中的 PIN，或扫描包含 PIN 的二维码。每次启动共享都会生成新的 PIN。

如需从网络外部访问，请使用 Tailscale（见下文），而不要在路由器上开放端口。

桌面安装程序包含局域网地址所使用的 Web 界面；其他设备无需安装 VoiceStudio，主机也无需源码检出或单独的前端开发服务器。后端提供运行中应用自带的 Web 构建（OMNIVOICE_FRONTEND_DIST），因此更新后，局域网设备无需额外步骤即可获得匹配的界面。

其他设备显示“Web 界面不可用”： 后端正在运行，但没有可提供的 Web 构建。修复 #2599 之前的桌面构建在所有操作系统上都有此问题；请更新到最新版本。若是源码检出，请运行 bun run build:web 并重启后端。其他设备绝不会被重定向到 localhost，因为在该设备上它不是 VoiceStudio。

PIN 的工作原理¶

• 每次启用共享时都会生成一个新的 6 位 PIN；它从不写入磁盘。
• 二维码对 PIN（…/?pin=######）进行编码，因此扫描即可一步连接。如果直接输入不带参数的 URL，则会提示输入 PIN。
• 来自其他设备的请求必须提供 PIN（输入/扫描后会自动发送）；来自本机的请求永远不需要。在 Docker 中，宿主机自己的浏览器不算作本机，因此需要 PIN，除非你通过 OMNIVOICE_TRUST_HOST_LOOPBACK=1 选择启用（参见 Docker 安装）。

安全模型¶

• 每次启动时默认仅限回环（loopback） — 每个会话你都必须显式启用共享；它永远不会自动暴露。
• 共享关闭时，不会绑定任何内容到网络接口（端口已关闭，而不仅仅是被防火墙拦截）。
• 控制面（control surface）和所有 /system/* 端点都是仅限回环的 — 局域网设备无法启用共享、读取 PIN 或更改设置，即使共享已开启。
• 局域网路径是明文 HTTP。如需加密或从局域网外部访问，请使用 Tailscale（见下文）。

Tailscale（可随时随地私有远程访问）¶

如果你已安装 Tailscale 并登录，即可通过你的私有 tailnet 从任意设备访问 VoiceStudio——基于身份验证，无开放端口、无 PIN（Tailscale 负责身份验证，WireGuard 隧道对传输进行加密）。

1. 设置 → 共享与远程访问 → Tailscale。
2. 如果未检测到 Tailscale，则会显示安装 Tailscale 链接。
3. 否则，启用将通过 tailscale serve 在您的 tailnet 上发布此后端。面板会显示您的 <machine>.<tailnet> URL，并提供复制 / 打开 / 二维码操作。
4. 默认情况下，这会在 tailnet 上通过 HTTP 提供服务（tailscale serve --http=80）——适用于任何 tailnet，因为 WireGuard 隧道已经对流量进行了加密。无需证书。
5. 如果你的 tailnet 启用了 HTTPS 证书（管理控制台 → DNS → HTTPS 证书），它将改为通过 HTTPS 提供服务，你会得到一个 https://…ts.net URL。（在没有该功能的情况下强制使用 HTTPS 才会产生 error enabling https feature: 404——因此我们会自动检测并回退到 HTTP。）
6. Tailscale serve 设置由机器上的所有应用共享，因此 VoiceStudio 不会替换其他应用的共享。如果其他服务占用了默认端口（HTTP 为 80，HTTPS 为 443），VoiceStudio 会尝试使用 10000 端口，并将其包含在地址中，例如 http://<machine>.<tailnet>:10000。如果该端口也被占用，VoiceStudio 会保持配置不变并报告错误。
7. 在已登录同一 tailnet 的任意设备上打开显示的 URL。禁用只会移除针对此 VoiceStudio 后端的 serve 处理程序，使用 tailscale serve --http=<port> off；它会保留所有其他应用的共享，并且绝不会运行 tailscale serve reset。

Tailscale 会直接代理回环后端，因此——与 LAN 共享一样——它绝不会重启后端或丢弃已加载的模型。

注意事项¶

• 两种方式都会让正在运行的模型和进行中的任务完全不受影响。
• 可以通过 IP 地址、localhost、本机主机名、其 Tailscale 名称或容器主机别名（如 host.docker.internal）打开共享或远程的 VoiceStudio。任何其他主机名（例如反向代理域名）都需要有效的 API 密钥或管理员会话，或者 OMNIVOICE_ALLOWED_HOSTS 条目；请参阅 API 身份验证。
• 服务器部署（Docker，或使用 OMNIVOICE_BIND_HOST=0.0.0.0 启动的源码后端）自行管理网络；应用内开关适用于桌面应用，不受这些流程影响。