dsh-mobile-access

English | 中文

dsh 手机远程访问组合包：通过你自己的域名和公网服务器，把 Web GUI 提供给手机访问。cordis.patch.yml 叠加在 Web 表层之上：把隧道服务的公共主机加入 connection 行的 /api 浏览器信任栅栏，并插入本包的 mobile-access 粘合插件。该插件在 webserver 之前启动一个本地令牌网关（src/gate.ts）和一个受监管的 SSH 反向隧道（src/tunnel.ts）通往中继服务器，提供 mobileAccess 服务（栅栏接受的公共主机），在 surfaceContext 为 true 时注册手机表层提示词段落与 bash 可见的 DSH_WEB_PUBLIC_URL 运行时变量，并在隧道建立后打印公共 URL（qrCode 为 true 时附带终端二维码）。中继服务器上由 Caddy 为域名终结 HTTPS 并反向代理进隧道；scripts/setup-server.sh 负责安装这一侧。分步部署手册见 DEPLOYMENT.md。

工作原理

phone ── https://dsh.example.com ──> Caddy (HTTPS, on your server)
                                        └──> 127.0.0.1:<relay-port>  (sshd reverse tunnel)
                                                  └──> local token gate (dsh process)
                                                        └──> http://127.0.0.1:<web-port>

隧道是插件拥有的 ssh -N -R 子进程：按指数退避自动重连，稳定运行一段时间后重置退避，并随 fiber 一起消亡。网关提供了信任栅栏刻意不提供的认证层：每个请求和 WebSocket 升级都必须出示令牌（登录表单设置的 cookie，或 Basic/Bearer 凭据），才会被转发到 webserver。公共主机通过 mobileAccess 服务进入栅栏；补丁把该服务注入 connection 行的 inject，因此栅栏的配置表达式永远不会在主机存在之前求值。

弱网行为

手机链路是受限的一段（例如地铁通勤）；隧道和中继服务器位于两端稳定的网络上。当这段链路劣化时，有三个机制保持 GUI 可用：

• 事件流有压缩（宿主支持时）。 WebSocket 下行链路协商 permessage-deflate（dsh 的 web 构建已内置），会话事件流（重复度高的 JSON）在手机链路上缩小数倍。浏览器会自动协商该扩展。
• 浏览器自动重连。 Web 客户端的连接控制器在信号中断时按指数退避（500 ms 起、倍增至 10 s 封顶）重新建立两条事件流，隧道中断或信号盲区无需刷新页面即可恢复。
• 隧道自我修复。 keepAliveIntervalSec / keepAliveCountMax 让 ssh 快速感知中继失联（默认 30 s × 3 次探测），监管进程再按抖动退避（backoffBaseMs..backoffMaxMs）重启子进程。家庭上行不稳时，把 keepAliveIntervalSec 调到 10、backoffBaseMs 调到 1000 可以缩短中断窗口，代价是少量额外探测包。

安装

该组合包是可选安装，叠加在随附的 web profile 之上。可从本仓库安装（prepare 脚本会在安装时从源码构建插件；pnpm ≥10 首次会要求允许构建——把 pnpm 打印的包名写进 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重跑），发布到 npm 后也可直接安装：

dsh plugin --profile web add github:kk99668/dsh-mobile-access
# 或发布到 npm 后：
dsh plugin --profile web add dsh-mobile-access

插入的行从环境变量读取配置（应用启动时会加载调用目录和 Harness 主目录下的 .env）：

变量	含义
DSH_MOBILE_PUBLIC_HOST	公共主机，裸 host 或 host:port（必填）
DSH_MOBILE_RELAY_HOST	中继服务器地址（必填）
DSH_MOBILE_RELAY_USER	中继服务器上的 SSH 登录用户（必填）
DSH_MOBILE_TOKEN	网关密钥，至少 8 个字符（必填）

必填变量未设置时启动会明确失败并指出字段名。其余设置都是带默认值的插件配置字段：relayPort 22、remoteBindHost 127.0.0.1、remoteBindPort 3080、localPort（当前 webserver 端口）、gatePort 0（由系统分配）、sshBin ssh、identityFile 不设、keepAliveIntervalSec 30、keepAliveCountMax 3、connectTimeoutSec 10、退避 2s..30s、stableUptimeMs 60s、runningAfterMs 3s、printUrl true、qrCode true、surfaceContext true。要修改其中一项，请在 $DSH_HOME/profiles/web/cordis.patch.yml 中覆盖该行的 config（补丁会整体替换 config，因此需要重述所有键）：

- id: mobile-access
  config:
    publicHost: dsh.example.com
    relayHost: vps.example.com
    relayUser: dsh-relay
    token: a-long-random-secret
    remoteBindPort: 8443
    identityFile: C:\Users\you\.ssh\id_ed25519

服务器设置

在中继服务器上以 root 运行一次：sudo ./scripts/setup-server.sh dsh.example.com 3080 ~/dsh-relay.pub。脚本会安装带自动 HTTPS 的 Caddy 并为域名配置反向代理，创建 dsh-relay 用户，把给定的公钥安装到 authorized_keys 并加上只允许反向监听的限制（permitlisten="127.0.0.1:3080"，无 shell、无 agent、无 X11），在 GatewayPorts 被开启时给出警告，并在 ufw 中开放 22/80/443。密钥文件参数可选：任何能登录服务器的 SSH 方式都可用，但受限的中继用户是推荐形态。脚本执行后，设置上面的环境变量，启动 dsh --profile web，用手机扫描二维码即可。

安全

• 令牌网关是公网与 agent 之间唯一的屏障。任何知道令牌的人都能控制这个 agent——请把它当作凭据对待。
• 网关的登录 cookie 是 HttpOnly 且 SameSite=Lax；令牌不会进入 URL、日志或 referrer。
• 中继服务器只把隧道端口绑定到回环地址；手机从不直接接触隧道，只通过 TLS 与 Caddy 通信。
• 栅栏的特权方法（settings.*、credentials.*、host.* 等）即使在 trusted-host 部署下也固定为仅回环可访问，因此配置平面无法通过隧道触达。
• 在共享或不可信网络上暴露 harness 前请三思。Web 应用本身没有用户账号；网关就是边界。

模型体验

手机表层上下文

模型看到的内容

当 surfaceContext 为 true 时，全局段落 app:mobile-surface（顺序 −97，紧跟在 web-surface 段落之后）向模型说明公共主机，DSH_WEB_PUBLIC_URL 也会连同描述出现在受管 bash 环境中，每次调用时解析：

该字段的逐字文本

The DeepSeek Harness Web GUI is also served at https://dsh.example.com through a secure tunnel. Users arriving there interact with the same harness and sessions as this local GUI.

Token 影响

每个会话一段提示词，外加一行受管环境变量；每个进程内保持恒定。

KV Cache 影响

该段落位于系统提示词靠前位置，且在进程整个生命周期内稳定（公共主机是启动期事实），因此不会使跨轮次缓存失效。

已知限制与延期工作

• 隧道需要 SSH 客户端：sshBin 必须在运行 dsh 的机器上可解析；二进制缺失会在 spawn 时明确失败并按退避重试，README 中的手动 ssh -N -R 命令是排查路径。
• 每台手机每次需要浏览器登录：会话 cookie 没有 Max-Age，因此每台手机每个浏览器配置需要登录一次；没有持久设备注册表或按设备吊销。
• Windows 自启动由用户自己负责：隧道活在 dsh --profile web 进程内；要保持 GUI 可访问就要保持该进程运行（不附带服务包装）。
• GUI 内没有状态面板：隧道状态只能通过控制台日志和 mobileAccess 服务查看；设置卡片是延期工作。