czhzz/dsh-net-access

dsh-net-access

npm
license
node
GitHub stars

从设置页控制 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=…（局域网：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 run build   # 宿主部分直接复制；客户端部分用 esbuild 打包
npm test        # 16 项行为测试，覆盖四种模式

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

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

许可证

MIT