dsh-net-access

从设置页控制 DeepSeek Harness Web GUI 的访问范围。

想在手机上通过 Tailscale 打开 GUI、想开放给整个局域网、或者只想锁死在本机——一个设置项、四种模式，并且会明确告诉你什么时候需要重启才生效。

在 设置 → 远程访问 中配置。

四种模式

模式	监听套接字	信任的授权来源	能否热切换
仅本机（默认）	所有网卡	仅回环地址	能
仅 Tailscale	所有网卡	tailnet 地址	能
所有本地网络	所有网卡	所有本地 IPv4	能
关闭	127.0.0.1	回环地址	否 —— 需重启

为什么只有一种模式需要重启

DSH 在服务器启动时只绑定一次 HTTP 监听端口，且 dsh-host-webserver 只接受 127.0.0.1 和 0.0.0.0 两个绑定地址。进程运行期间没有重新绑定的路径，所以已经绑定到回环的套接字无法再次打开。

本插件把这个限制变成设计，而不是与之对抗：

• 三种模式让套接字保持在所有网卡上，改为在 /api 的信任围栏（trust fence）上表达访问决策。该围栏按请求求值，因此「仅本机」「仅 Tailscale」「所有本地网络」这三种模式可以在设置页热切换。
• 关闭是唯一改变绑定地址的模式：它把套接字收回回环。它也是唯一让端口在端口扫描中不可见的模式——这正是它值得重启一次的原因。

设置页会读取当前服务器启动时使用的模式，并在选择尚未生效时明确提示，而不是报告一个不会发生的切换。

需要接受的取舍

仅本机模式让端口保持对所有网卡开放，只在应用层拒绝除回环之外的一切请求。这在一个具体方面弱于回环绑定：

	关闭	仅本机
局域网端口扫描能看到端口	否	是
局域网设备能完成 TCP 握手	否	是
局域网设备能访问 GUI	否	否（403）

如果你需要端口本身不可达，请使用关闭并接受重启——或者添加一条主机防火墙规则。仅本机模式适用于：你想保留较宽的监听，但又不希望其他设备穿过它。

可达性是如何被强制执行的

信任围栏位于 dsh-client-connection。在认证之前，每个请求都必须提供回环地址或已声明的授权 Host；其他一律返回 403，已信任但未认证的请求返回 401。

在一台同时具备 Tailscale、局域网、VMware 和 WSL 网卡的机器上、处于仅 Tailscale模式时实测（下表用文档示例地址代替实测时的真实地址）：

Host 请求头	结果	含义
100.64.0.10:3080	401	已信任（tailnet）—— 进入令牌认证
localhost:3080	401	已信任（回环）
192.0.2.10:3080	403	被拒绝（局域网）
198.51.100.10:3080	403	被拒绝（VMware 虚拟网卡）
203.0.113.10:3080	403	被拒绝（WSL 虚拟网卡）
evil.com	403	被拒绝（DNS 重绑定）

这个围栏拦的是浏览器访问，不是 TCP 可达性。 在三种「所有网卡」模式下，其他网络上的设备仍然可以与端口完成 TCP 握手，只是无法穿过围栏。

认证与可达性相互独立：URL 中打印的进程令牌才是授权浏览器的凭据。

Tailnet 地址探测

插件不硬编码任何 IP，因此在任何机器上都能工作：

1. 先按网卡名查找 Tailscale 网卡（Tailscale、tailscale0 等），客户端在 Windows、macOS、Linux 上命名一致。
2. 找不到网卡时，接受 Tailscale 100.64.0.0/10 范围内的任意地址。

网卡名优先于网段，因此运行第二个 CGNAT 覆盖网络的机器仍能解析出正确地址。当探测结果不可能正确时（例如你通过 MagicDNS 域名而非 IP 访问该节点），在设置页手动填写 Tailnet 地址。

在仅 Tailscale模式下，若机器上不存在 tailnet 地址，插件会**回退到「关闭」**并记录原因，而不会静默放宽为「所有本地网络」。

安装

推荐从 npm 安装：

dsh plugin --profile web add dsh-net-access

包内已含构建产物，因此这条命令不需要本地构建，也不需要 allowBuilds 授权。

其他安装方式

从 GitHub 安装 —— 想跟未发布的提交时用：

dsh plugin --profile web add github:czhzz/dsh-net-access

从本地目录安装 —— 改代码时用：

cd dsh-net-access
npm run build

dsh plugin --profile web add /absolute/path/to/dsh-net-access

重启生效

安装后重启一次 GUI，让 profile 加载新的组合包：

dsh --profile web

启动时会打印可访问的 URL，适用时包含局域网形式：

dsh web: http://127.0.0.1:3080/?token=… (LAN: http://100.x.y.z:3080/?token=…)

配置

设置页是常规路径。相同的值也可以写在 cordis.patch.yml 中该行的 config 块里，它作为设置页覆盖的基础层。

字段	默认值	含义
mode	local	local、tailscale、all 或 off
address	""	固定 tailnet 地址；留空表示自动探测
extraTrustedHosts	[]	额外接受的 host[:port] 授权

命令行传入的 --trusted-host 授权会合并进所有模式。

已知限制

• 「仅本机」需要重启。 绑定地址在监听器打开时就固定了。
• 不自动重启。 设置页只显示重启命令，而不是替你重启：插件运行在 DSH 进程内部，退出以重启会杀掉当前会话以及其中运行的所有任务，且没有任何机制把它带回来。
• 地址按请求采样，但绑定地址不会。 运行中切换网络会立即反映到「所有本地网络」，但不会移动套接字。
• 无 TLS。 Tailscale 会加密节点间流量，但 GUI 本身使用 HTTP。
• 仅 IPv4。 不探测 Tailscale 的 IPv6 网段。

开发

npm install     # esbuild、lightningcss、semver，以及 schemastery（仅开发用）
npm run build   # 宿主部分直接复制；客户端部分用 esbuild 打包
npm test        # 16 项行为测试，覆盖四种模式

@deepseek-ai/schemastery 是可选 peer：运行时由 DSH 宿主提供，插件自身不打包它，所以它不在 dependencies 里；但开发时源码要导入它，因此它同时列在 devDependencies。版本范围 >=3.18.2 <4 描述的是 schemastery 自己的版本线，不是 DSH 的——两者独立发版（dsh 是 0.1.6-alpha.1 时 schemastery 是 3.18.2）。照着 DSH 版本号写范围会让 npm install 直接 ETARGET，tests/peer-range.check.mjs 专门守住这一点，并从 package.json 读取范围本身。

构建依赖优先从本目录的 node_modules 解析；找不到时才回退到旁边的 harness checkout 及其 pnpm store，因此在没有 harness checkout 的机器上也能构建。

客户端部分被打包成 DSH 模块加载器所要求的单文件工厂。React 与 @deepseek-ai/dsh-client-ui-primitives 保持为外部依赖——由浏览器的模块表提供，姿态选择条复用共享的 Pill 控件而非另带一份副本。CSS Modules 经 lightningcss 编译，并通过带 data-plugin-css 标记的 <style> 元素按插件注入一次。

测试直接运行文件而非通过 node --test，因为测试运行器会派生子进程，而这在受限文件系统沙箱下会被拒绝。

许可证

MIT