dsh-homing（DSH Host 插件）

v1.4.0 变更（务必先读）

• 入口从「常量暗号 ?func=dsh-view + 可伪造的 dshview=1 Cookie」改为 HMAC 签名、带过期的入口令牌 ?k=。
• 令牌打开一次后换成 逐设备令牌 dsh-homing-device（HttpOnly / SameSite=Lax / Secure，180 天），设备可在 /dsh_homing/devices 单独吊销，吊销即时生效。
• 生成入口：node bin/entry-link.mjs（或 dsh-homing-entry），默认 30 天有效；书签只存 https://域名/。
• 旧链接 ?func=dsh-view 默认失效；如确需兼容，配置 legacyFunc: true。
• 新增：写操作来源校验（Origin + Sec-Fetch-Site，含 WebSocket）、登录失败分桶锁定 + 全局延迟、 请求体上限 maxBodyBytes（默认 300 MiB，补回 TLS 透传后 nginx 失去的那一层）、配对设备上限 maxDevices。

把本机 DSH 通过 SSH 反向隧道安全地开放到手机 / 微信浏览器，随 DSH 启动，跨平台（Windows / Linux / macOS）。

手机 ──HTTPS──> 云服务器 nginx ──SSH 反向隧道──> 本机插件(127.0.0.1:8787) ──> DSH 自己的 Web 服务

它做什么

| 能力 | 实现 | |---|---| | 找 DSH 端口 | ctx.webServer.getOrigin()，不扫进程、不依赖平台 | | 注入登录态 | ctx.credentials.readRecord('client-connection/browser-session') 取签名密钥，签 dsh-auth-* Cookie | | 账号登录 | 登录页 + scrypt 哈希 + 7 天签名 Cookie，失败限速 | | 入口令牌 | 首次必须带 ?k=<签名令牌>，之后靠 dsh-homing-device Cookie；两者都没有则 404 | | 移动端适配 | 注入 CSS/JS：窄屏隐藏右侧边栏、选完会话自动收起抽屉 | | 反向隧道 | 调系统自带 ssh -N -R，断线 5 秒重连，日志写 $DSH_HOME/integrations/dsh-homing/tunnel.log | | 生命周期 | 全部资源在 ctx.effect() 里注册，插件卸载时关闭监听并杀掉 ssh 子进程 |

配置（cordis.patch.yml 的 config）

| 字段 | 说明 | 默认 | |---|---|---| | serverHost | 云服务器 IP；留空则只在本机/局域网跑，不起隧道 | 空 | | sshUser / sshPort / sshKey | SSH 登录信息；sshKey 留空用 ~/.ssh/dsh_tunnel | ubuntu / 22 / 空 | | listenPort | 本机插件监听的端口（冲突了自己改，服务器不用动） | 8787 | | remotePort | 服务器上 ssh 隧道占用的回环端口，必须等于 nginx 的 proxy_pass | 8787 | | syncPortFromServer | 启动时和每 10 分钟向服务器查询 proxy_pass 端口，不一致就以服务器为准改本地 | true | | bindAddress | 127.0.0.1 只给隧道用；:: 局域网也能直连 | 127.0.0.1 | | publicUrl | 手机访问入口，用于日志/二维码 | 空 | | legacyFunc | 是否仍接受旧版 ?func= 常量暗号（默认 false） | false | | login | 是否要求账号密码 | true |

桌面共享（VNC，跨平台）

/vnc 页面内置 noVNC（MIT/MPL 开源），连接本机 VNC 服务端，20–30fps：

• 只连本机回环（默认 127.0.0.1:5900），必须登录插件页面才能访问
• 支持密码认证、缩放视口、触摸/键盘/剪贴板（noVNC 自带）
• 无VNC服务端时页面会提示连接失败，不影响其它功能
• 配置：settings.json 的 vnc.host / vnc.port

各平台装服务端（一次性）：

| 平台 | 服务端 | 要点 | |---|---|---| | Windows | TightVNC / UltraVNC | 设密码；勾选"仅接受本机连接"（Access Control → localhost） | | Linux X11 | x11vnc / TigerVNC | x11vnc -localhost -forever -shared -rfbauth ~/.vnc/passwd | | Linux Wayland | wayvnc | 绑定 127.0.0.1，设密码 | | macOS | 系统设置 → 通用 → 共享 → 屏幕共享 | 打开后即监听 5900，可设密码 |

窗口共享（手机操作 PC 窗口）

/remote 页面列出 PC 上所有可见窗口，点一个就共享它的实时画面：

• 手机上看该窗口画面（约 2 帧/秒，PrintWindow 抓取，最小化窗口抓不到）
• 点击 = 在窗口对应位置点击；支持右键、滚轮、回车/退格/Esc/Tab
• 文字输入支持中文（SendInput Unicode）
• 换窗口：返回列表重选；适合 WPS 弹窗、安装向导等场景
• 实现：PowerShell 代理（lib/window-agent.ps1）+ 行-JSON 协议，仅本机、需登录

为什么按窗口而不是整个桌面：手机屏幕小，一次只看一个窗口更清楚； 但要注意 WPS 的"另存为"等对话框是独立窗口，需要回列表重新选择。

Office / PDF 预览

文件页里点开 docx / xlsx / pptx / odt / ods / odp / rtf / pdf 会直接在线预览：

• PDF：原样流式返回，浏览器内置阅读器打开
• Office：用 DSH 自带的 LibreOffice 引擎在本机转成 PDF（无需另装 LibreOffice/Office/WPS）， 同一文件按「路径 + 大小 + 修改时间」缓存，只转一次
• 首次转换约 2–5 秒；失败时给出下载链接（可用 WPS/Office 打开）
• 找不到引擎（非常规安装）时可用环境变量 DSH_HOMING_OFFICE_KIT 指定 @deepseek-ai/libreoffice-kit/lib/index.js 的路径

远程终端

跨平台自动探测（插件启动时按当前系统扫描，不需要模型去猜）：

| 平台 | 自动发现 | |---|---| | Windows | Git Bash、MSYS2 Bash、Cygwin Bash、PowerShell 5/7、CMD、WSL、Nushell | | Linux | $SHELL、bash、zsh、fish、sh、dash、ksh、PowerShell 7、Nushell、/etc/shells 里登记的其它 shell | | macOS | $SHELL、zsh、bash、fish、sh、PowerShell 7、Nushell（含 Homebrew 路径） | | 全平台 | Python REPL、Node REPL |

终端页支持切换多种 shell，选择会记在浏览器 Cookie（每台设备独立）：

| 类型 | 说明 | |---|---| | Git Bash / PowerShell 5 / PowerShell 7 / CMD / WSL / Python REPL / Node REPL | 启动时自动探测，装了才出现 |

默认值可在 settings.json 指定：

{ "terminal": { "shell": "powershell" } }

自定义命令行（例如把某个便携版 bash 接进来）：

{
  "terminal": {
    "custom": {
      "label": "MobaXterm Bash",
      "path": "C:\\Program Files\\Git\\bin\\bash.exe",
      "args": ["-l"],
      "cd": "bash"
    }
  }
}

custom 也可以是数组；cd 可选 bash / wsl / windows / python / node。 注意：MobaXterm / Windows Terminal 是图形程序，不能嵌入网页终端，只能接它们底层的 shell。

账号

首次启动自动生成随机账号，打印在 DSH 日志里；存在 $DSH_HOME/integrations/dsh-homing/auth.json（scrypt 哈希 + 会话签名密钥）。 删掉该文件重启即可重置。

服务器初始化脚本

包内自带 in/bootstrap-server.mjs（跨平台 Node 脚本），一次性把服务器配好（nginx + 证书 + 反代）：

node bin/bootstrap-server.mjs --server <服务器IP> --domain <域名> [--install-key] [--dry-run]

安装后如果 bin 已链接到 profile，也可以直接跑 dsh-homing-bootstrap。

服务器侧

需要一台公网服务器配好 nginx：443 终止 TLS（Let's Encrypt）、把请求反代到 127.0.0.1:<listenPort>，并把 80 端口除 ACME 校验外直接断开。 配置在同仓库 deploy/nginx-*.conf。

跨平台说明

• Windows：自带 OpenSSH 客户端（C:\Windows\System32\OpenSSH\ssh.exe），Windows 10 1809+ 默认就有；
• Linux / macOS：系统自带 /usr/bin/ssh；
• 插件本身没有原生依赖，全部用 Node 标准库。