手机远程访问网关alexcarterio/dsh-mobile-access

dsh-mobile-access

CI

架构：手机 -> lan-gate -> DSH web，以及 ntfy 推送路径

从手机使用 DeepSeek Harness（DSH）所需的一切：一个带设备审批的安全局域网网关插件、移动端友好的布局、手机推送通知，以及 PWA 安装资源。

核心是一个自包含、无依赖的 Cordis 插件（lan-gate.mjs），它通过一个经设备审批、令牌绑定的反向代理，将你本地的 DSH Web UI 暴露给受信任的局域网 / Tailscale 设备——此外还有一个可选的 dsh-push 辅助程序，通过 ntfy 将 DSH 会话事件转发到你的手机。

功能特性

- 设备审批流程——新设备会看到一个“等待审批”的网关页面，在你从桌面端批准之前无法访问 DSH。
- 按设备设置访问模式——每个已批准的设备可设置为 auto、phone 或 desktop。手机模式会注入紧凑布局；桌面模式即使在窄窗口中也会保持桌面布局。
- 令牌 + Cookie 绑定——一次审批会签发一个 128 位随机令牌，通过 HttpOnly/SameSite=Lax Cookie 仅下发一次（在 HTTPS/Tailscale Serve 入口上会添加 Secure 标志）。令牌在 90 天后过期，同一 IP 上的浏览器会自动重新认领，而不会卡在“已绑定到另一个浏览器”页面上。撤销设备会立即切断其访问权限。
- 速率限制——按 IP 的滑动窗口限制（默认 3000 请求/分钟，高于上游的 120），溢出时返回 429，以遏制扫描器和暴力破解尝试。
- 移动端布局——紧凑的手机 CSS、全屏对话框、不遮挡内容的模型/上下文菜单、iOS 聚焦缩放预防，以及用于非 HTTPS 内网环境的 crypto.randomUUID polyfill。
- 附件上传——POST /lan-gate/upload 接受最大 20 MB 的文件，保存在 $DSH_HOME/uploads/ 下，并自动清理 7 天前的文件。配套脚本 tools/parse_file.py 可将常见附件格式（txt/docx/pdf/zip/7z/rar）转换为可读文本。
- 手机相册 / 相机按钮——注入的浮动按钮，复用桌面端的粘贴路径（或回退为插入 ）。
- 管理面板——应用内面板，位于 设置 → 局域网访问，可查看状态、批准/拒绝设备、切换访问模式、撤销设备，以及复制访问 URL。
- ntfy 手机推送（dsh-push）——一个独立的监视程序，当 DSH 等待你的审批或回复时发送高优先级通知，当任务回合完成时发送普通通知。

安全模型

该插件设计为仅在受信任的网络上运行。它不提供端到端 HTTPS，并且绝不能直接暴露到公共互联网。
1. 网络层（防火墙）——仅允许来自你的局域网或 Tailscale 子网（100.64.0.0/10）的入站流量访问网关端口（默认 3088）。其他所有流量均不可达。
2. 应用层（审批 + 令牌）——每台新设备都必须在桌面端获得批准，然后会收到一个通过单一浏览器绑定 cookie 签发的一次性令牌。令牌在 90 天后过期，同一 IP 的设备会自动重新认领，而不会被卡住。撤销操作会切断连接。
3. 主机进程——DSH Web 服务器本身始终绑定到 127.0.0.1:3080；只有进程内的网关代理会转发到它。仅限本地的控制路由（/lan-gate/status、/lan-gate/action、/lan-gate/upload）会通过检查 x-forwarded-for 来拒绝非本地请求，并额外针对 CSRF 强制执行 Origin 允许列表（回环地址 / 局域网 IP / *.ts.net）。
4. Serve 入口客户端 IP 解析——通过 tailscale serve（HTTPS 入口）到达的流量来自回环地址，但携带 tailscale-user-login 头和 x-forwarded-for；网关仅在回环地址 + Serve 头请求的情况下信任该转发 IP，因此按设备审批仍会应用于每个 tailnet 设备，而不会将它们全部合并为本地机器。

警告： 不要将 DSH 本身绑定到 0.0.0.0，也不要将网关端口端口转发到公网。仅在受信任的局域网或 Tailscale tailnet 内使用它。

要求

- DeepSeek Harness 通过 npm 安装（安装方法见上游仓库）。web 配置文件必须在 127.0.0.1:3080 上提供 UI。
- Node.js——你的 DSH 运行的任意版本（该插件是单个 .mjs 文件，无依赖项）。
- Tailscale（可选，推荐用于手机访问）——在桌面端和每部手机上安装客户端，并登录同一账号。
- ntfy（可选）——用于手机通知：手机上安装 ntfy 应用，并安装 Python 3 及 requests 和 zstandard 包以使用 dsh-push。

安装

1. 放置插件

将 lan-gate.mjs 复制到你的 DSH 主目录：

~/.dsh/lan-gate/lan-gate.mjs

（$DSH_HOME 默认为 ~/.dsh；设置 DSH_HOME 可覆盖它。）

2. 注册插件

将以下内容合并到 ~/.dsh/profiles/web/cordis.patch.yml（完整带注释版本见 cordis.patch.yml.example）：

- insert:
- id: lan-gate
name: 'file:///C:/Users//.dsh/lan-gate/lan-gate.mjs'

将 file:/// 路径调整为你的真实绝对 lan-gate.mjs 位置（Windows 为 file:///C:/...，macOS/Linux 为 file:///home/... 或 file:///Users/...）。

3. 重启 DSH

重启 DSH 以加载用户补丁。启动时插件会记录日志：

[lan-gate] listening on 0.0.0.0:3088 -> 127.0.0.1:3080

4. 从另一台设备打开

在同一局域网中的设备上，访问：

http://:3088
其中  是本机的局域网 IP。在你于 设置 → 局域网访问 中批准之前，设备会显示一个“等待批准”页面。

5. 解析上传的附件（可选）

tools/parse_file.py 将下载的附件转换为可读文本（或
解压归档文件）：

py tools/parse_file.py  [output]

- 不带 [output] 时，它会写入 .parsed.txt 并将前 500
个字符打印到 stdout。
- 支持：txt/md/csv/json/xml/yaml/log 以及常见代码文件
（以文本方式读取）、docx、pdf，以及归档文件 zip/7z/rar（解压到
同名目录；rar 需要安装 WinRAR/unrar）。

一次性安装其可选依赖：

pip install python-docx pypdf py7zr rarfile

配置

| 环境变量 | 默认值 | 描述 |
|---|---|---|
| LAN_GATE_PORT | 3088 | 网关代理监听的端口。 |
| LAN_GATE_HOST | 0.0.0.0 | 监听地址。当有反向代理/隧道（例如 tailscale serve）位于前端时，设置为 127.0.0.1。 |

- 速率限制 — 硬编码为每个 IP 每分钟 3000 次请求（滑动窗口）。它有意不通过环境变量调整；如果必须修改，请编辑 lan-gate.mjs 中的 RATE_LIMIT_PER_MIN 常量，然后重启 DSH。
- 批准状态 — 持久化于 $DSH_HOME/lan-gate-state.json。批准在 90 天后过期（TOKEN_TTL_MS）；删除该文件可立即重置所有批准。
- 上传 — 存储于 $DSH_HOME/uploads/，7 天后自动清理。

手机设置

在手机上，请遵循对应平台的指南：

| 平台 | 指南 |
|---|---|
| 📱 Android | docs/phone-guide-android.md — Tailscale、入口地址、PWA 安装、ntfy、故障排除 |
| 🍎 iPhone / iPad | docs/phone-guide-ios.md — 相同步骤，附 iOS 主屏幕和通知的具体说明 |

完整的管理员侧手册（架构、防火墙、维护、
升级）位于 docs/install-guide.md。

1. 桌面端：加入 tailnet（Tailscale）

1. 在桌面端和手机上安装 Tailscale。
2. 将两台设备登录到同一个 Tailscale 账户。
3. 确认两者都出现在 Tailscale 管理控制台 中。

使用以下命令查找桌面端的 Tailscale IP：

tailscale ip -4

2. 桌面端：通过 Tailscale Serve 使用 HTTPS（推荐）

tailscale serve 提供有效的 TLS 证书，以便手机浏览器提供
“安装应用”（PWA）流程：

tailscale serve --bg --yes --https=3443 http://127.0.0.1:3088

然后在手机上打开 https://.your-tailnet.ts.net:3443。

- 查看：tailscale serve status
- 移除：tailscale serve reset

DSH 前端的 PWA 图标/manifest/service-worker 资源记录在
pwa/pwa-setup.md 中。

3. 桌面端：手机通知（ntfy）

dsh-push 通过 ntfy 将 DSH 事件转发到你的手机。参见
有关完整指南、隐私说明和配置，请参阅 dsh-push/README.md。

| 环境变量 | 描述 |
|---|---|
| NTFY_URL | 推送服务器，默认 https://ntfy.sh（支持自托管）。 |
| NTFY_TOPIC | 你的主题名称——请像对待机密一样对待它；切勿公开。 |
| NTFY_TOKEN | 可选的 ntfy 访问令牌。 |

运行它（从 dsh-push/ 目录）：

py dsh_push.py            # run continuously
py dsh_push.py --test     # send a test notification

或者在 Windows 上使用 dsh-push/start_push.bat 将其作为后台进程启动（使用 %~dp0，因此可从任意位置运行）。

一次性安装依赖：

pip install requests zstandard

在 ntfy 应用中打开 https://ntfy.sh/ 来订阅你的手机。

限制

- 没有端到端 HTTPS——应用层是 WireGuard 隧道内的纯 HTTP；隧道本身就是加密边界。
- 依赖 Tailscale 控制平面——设备发现依赖 Tailscale 协调服务（数据路径为点对点）。自托管 headscale 是更高级的替代方案。
- 通知不支持深度链接——Tailscale 域名无法通过 WebAPK App Links 验证，因此点击通知会打开浏览器，而不是已安装的应用。
- DSH 升级可能会还原 PWA 更改——对构建后的前端 dist 所做的图标/manifest/service-worker 修改需要在 DSH 升级后重新应用。
- 与 DSH 同一进程——该插件在进程内运行（无子进程，无外部调用）；DSH 升级后请重新审计。

许可证

MIT。

致谢与参考

本项目基于以下项目的工作：

- hchao3335-maker/dsh-lan-gate — lan-gate.mjs 插件派生自
hchao3335-maker/dsh-lan-gate
（MIT）。本版本保留上游 MIT 许可证，并新增：速率限制
120 → 3000、附件上传端点、7 天上传清理、手机
相册/相机按钮，以及菜单布局调整。请参阅 NOTICE。
- Leon0555/dsh-lan-access — 一个
类似的解决方案，作为研究参考进行了审阅。
- DeepSeek Harness —
宿主平台。
- Tailscale — 用于
安全远程访问的网状 VPN。
- ntfy — 由 dsh-push 使用的
推送通知服务。