远程安全访问代理IslandManSwevo/deepseek-harness-tailscale

DeepSeek Harness · 随时随地，通过 Tailscale 访问

在一台机器上运行 DeepSeek Harness（dsh）——通过私有 Tailscale 网络，从你的手机、平板和笔记本电脑安全地远程操控它。

零配置启动器 · WebSocket 安全反向代理 · 内置文件查看器 · 自动更新 · 可选 HTTPS

环境要求： Windows（PowerShell + Windows 防火墙）· Node.js ≥ 24 · 主机及所有连接设备上均安装 Tailscale。

为什么需要这个项目

dsh 拥有一个非常出色的 Web UI——但它拒绝绑定到 127.0.0.1 以外的地址，这是有意为之，因为它可以在你的机器上执行代码。开箱即用的情况下，你只能在运行它的同一台电脑的浏览器中使用它。

最朴素的解决方案——在它前面放一个反向代理——会以看似灾难性的方式失败：

- 你刷新页面后，工作区和历史记录就"消失"了。 客户端只有在两个 WebSocket 连接建立后才会加载它们。一个损坏的代理会悄无声息地杀掉这些连接，于是 UI 就停留在"添加工作区 / 选择工作区"，而你在一旁惊慌失措。
- 从手机创建工作区 → HTTP 403（原生文件夹选择器仅限回环地址）。
- 从手机打开生成的文件 → HTTP 403（host.openPath 仅限回环地址）。

本项目真正解决了以上全部三个问题。

它是什么

| 组件 | 作用 |
|---|---|
| start-harness.ps1 | 一条命令搞定。自动检测 Node.js、你的 dsh 安装位置以及你的 Tailscale 身份，然后在端口空闲时启动代理（如果端口空闲）并启动 dsh（如果端口空闲）。幂等——无需编辑配置文件。如果登录时 tailnet 仍在连接中，它会在后台持续轮询，并在 Tailscale 就绪后自动启动代理。 |
| web-proxy.js | 加固的 Node 反向代理：忠实转发 WebSocket 升级请求（/api/events.mux、/api/events.host），因此刷新后能恢复你的历史记录；规范化 Host/Origin，使 dsh 的浏览器信任围栏得以通过；注入在纯 HTTP 下所需的 crypto.randomUUID polyfill。 |
| web-files.js + web-files-page.html | 位于 /__files 的内置文件浏览器/查看器/编辑器——从手机点击生成的文件即可打开，而不会返回 403。 |
| check-updates.ps1 | 当有更新的 dsh 可用时发出通知（或自动更新，并备份 ~/.dsh）。 |
| 可选 HTTPS | 通过 tailscale serve + 免费的 Let's Encrypt 证书实现。Tailscale 原生——不向公共互联网暴露任何内容。 |

快速开始

1. 在主机上安装 Tailscale 并登录。在 Tailscale 管理控制台中启用 HTTPS 证书（DNS → HTTPS Certificates）。
2. 安装 harness：npm install -g @deepseek-ai/dsh（Node.js ≥ 24）。
3. 将本仓库的文件复制到一个文件夹中，例如 %USERPROFILE%\dsh\。
4. 将代理端口限制为仅 tailnet 可访问（如果你更改了 DSH_PROXY_PORT，请相应调整 -LocalPort）：
New-NetFirewallRule -DisplayName 'DeepSeek Harness (Tailscale only)' -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3080 -RemoteAddress 100.64.0.0/10, fd7a:115c:a1e0::/48

5. 启动它（幂等——可安全重复运行）：
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\dsh\start-harness.ps1"

6. 可选 HTTPS：tailscale serve --bg http://127.0.0.1:3080
7. 从任意 Tailscale 设备访问：https://..ts.net

就这么简单。 启动器会自动从你的 Tailscale 身份中推导出受信任主机列表。关于登录时自动启动的计划任务、停止方法、所有配置选项以及深入故障排除，请参阅 完整部署指南。

别人都没搞对的部分

刷新 → 历史记录丢失不是数据问题——你的数据从未丢失（工作区和会话都存放在 ~/.dsh 中）。这是一个 WebSocket 问题：dsh 只有在 /api/events.mux 和 /api/events.host 连接之后才会拉取其工作区/会话基线。大多数代理能正常转发 HTTP，但会破坏 101 升级握手，因此 UI 看起来像是被清空了。本代理正是为解决这两个握手问题而构建的——并且部署指南中包含了能证明这一点的原始握手测试。

安全模型

- dsh 保持仅限回环；代理拥有面向 tailnet 的端口，是唯一的入口。
- Windows 防火墙规则仅允许来自 Tailscale CGNAT 范围（100.64.0.0/10、fd7a:115c:a1e0::/48）的流量访问代理端口——不会向公共互联网暴露任何内容。
- 每个请求都要通过浏览器信任围栏：仅限回环或受信任的 Tailscale 权威来源；跨站以及 Origin/Host 不匹配的请求会被拒绝。
- /__files 查看器仅支持读写（不执行代码），路径限制在 DSH_FILES_ROOT 内，并拒绝 ..、符号链接逃逸和空字节遍历。

提醒： 你 tailnet 上的任何设备都可以通过代理访问该 harness。这正是其设计目的——但请确保 tailnet 中只有你信任的人。dsh 没有登录功能；在共享 tailnet 上，请通过 Tailscale ACL 限制谁可以访问此节点的 :3080/:443，而不要仅依赖 tailnet 成员身份。

配置

每项设置都是可选的且会自动检测；可通过环境变量覆盖（DSH_NODE、DSH_DSH_BIN、DSH_TS_HOST、DSH_TS_IP、DSH_TS_WAIT_SECONDS、DSH_TS_RETRY_SECONDS、DSH_PROXY_PORT、DSH_WEB_PORT、DSH_UPDATE_TRACK、DSH_AUTO_UPDATE、DSH_FILES_ROOT）。如果登录时 Tailscale 仍在连接，启动器会轮询等待它（DSH_TS_WAIT_SECONDS，默认 60），然后启动后台重试（DSH_TS_RETRY_SECONDS，默认 600），以便在 tailnet 出现后自动启动代理。详情见部署指南。

故障排除一览
- 刷新后历史记录“消失” → WebSocket 代理问题；运行 start-harness.ps1 -Verify（一次性健康检查）或指南中的原始握手测试。
- 手机上 UI 正常但没有历史记录，而 PC 上正常 → dsh 运行时缺少其 --trusted-host 列表（它在 Tailscale 就绪之前就启动了）。重新运行 start-harness.ps1（它现在会自我修复此问题），并用 -Verify 确认。
- 从手机创建工作区时出现 HTTP 403 → 启动器设置了 SSH_CONNECTION=remote 以启用浏览器内目录选择器。
- 从手机打开生成的文件时出现 HTTP 403 → 使用内置的 /__files 查看器。

测试

node --test 针对进程内的假上游运行代理和文件查看器测试套件——无需 dsh 或 Tailscale：

- WebSocket 101 中继和上游拒绝透传
- 突然断开的韧性（代理必须在手机中途断流时存活，而不是崩溃）
- Host → Origin 规范化
- polyfill + 集成脚本注入（包括文档已经引用 crypto.randomUUID 的情况）
- /__files 路径包含、信任围栏和保留 CRLF 的写入

对于实时部署健康检查，运行 start-harness.ps1 -Verify：它断言组件所有权、dsh 携带其 --trusted-host 列表，以及两个 WebSocket 握手都返回 101 并带有 tailnet Origin（手机的确切请求路径）。

常见问题

- 这是公共互联网服务吗？ 不是——设计上仅限 tailnet（通过 Tailscale 实现防火墙 + HTTPS）。
- 它会取代 dsh 吗？ 不会——它部署并安全地暴露真实的 @deepseek-ai/dsh Web UI。
- 为什么需要代理？ 因为 dsh web 故意拒绝绑定到回环地址之外。
- 它能在 macOS/Linux 上运行吗？ 脚本面向 Windows（PowerShell、Windows 防火墙、计划任务）。代理本身是纯 Node，可以适配。

许可证

MIT。欢迎提交 Issue 和 PR。