@nevermindzzt/dsh-manager-plugin

本版本适配 DSH 0.1.7-rc.2：插件以命名导出 name、Config、inject、apply，使 DSH loader 的 module namespace 保留 Config schema；client 端通过 configForms.get/whileServed 和 plugins.bundle.config slot 渲染 RC2 设置卡片。未被 DSH user layer 覆盖的 Manager URL、Agent 名称和实例 ID 会显示当前 environment/local-state 有效值；显式 DSH user overrides 优先。字段使用 volatile schema，pairingCode 使用 secret role 并以 write-only 控件保存。Host-side describe({ redactSecrets: true }) 只把非敏感 user overrides 交给隧道配置解析；配对码仅从 volatile Config/受保护的本地状态读取，不放入 descriptor user data。settings 更新按 settings/document-updated(ns, revision) 处理并忽略重复或过期 revision；不再使用旧 settingsScope / settings.plugin.item API。DSH 插件列表显示名称来自 locale/<lang>.json 的 meta.title，图标来自 package.json 的相对 icon 文件；dsh.patch.yml 中的 name 仍保留为实际模块 specifier。

0.3.0 DSH RC2 settings and package branding

• Add the RC2 ConfigForms settings card for Manager URL, pairing code, Agent name, and instance ID.
• Show effective non-secret Manager URL/name/instance values when no DSH user override exists; keep pairingCode write-only.
• Add localized plugin-list title metadata and the custom tunnel/shield icon.

0.2.3 transport and relay optimization

• 移除私有证书、TLS fingerprint 和证书 pinning；
• manager 使用单一 HTTP upstream 端口；
• 可信内网可直接使用 http://manager:port；
• 公网 HTTPS/WSS 由 Cloudflare Tunnel 或其他反向代理终止，manager upstream 仍使用 HTTP；
• DSH Web startup URL 只在内存中保存，绝不写入 plugin state 或日志；Manager transport 仅记录 origin，不记录 URL userinfo、path、query 或 fragment；
• 首个 manager 标记的根请求使用 startup token，随后通过 Cookie 使用干净 URL；
• WebSocket tunnel 会转发浏览器 Cookie；
• 对浏览器支持 gzip 的请求保留 DSH gzip 响应，避免在 Agent WebSocket 上传输未压缩静态资源；
• 与支持 proxy.binary-response-v1 的 manager 使用二进制响应帧，避免 HTTP 响应 body 再次 Base64 编码。

架构

浏览器
  ├─ Manager 隧道：HTTP / WSS → dsh-manager 单一 HTTP 端口 → Agent Protocol v1 ─┐
  └─ 局域网直连：HTTP → dsh-manager-plugin 额外监听端口 ──────────────────────┤
                                                                                ↓
                                                         当前 DSH 实例（loopback HTTP / WebSocket）

插件只能代理当前 dsh 实例，不提供任意 shell 或 launcher 生命周期命令。

能力

• 使用首次配对码完成一次性注册；后续连接只使用 Agent Token；
• HTTP/HTTPS enrollment（HTTPS 由外部代理提供）；
• WS/WSS Agent 长连接（WSS 由外部代理提供）；
• HTTP 请求反向代理；
• WebSocket 双向代理；
• 可选独立局域网直连 HTTP / WebSocket 入口（默认关闭，不依赖 Manager 隧道）；
• settings.host、plugin.config、dsh.web.bootstrap-v1 和 proxy.binary-response-v1 能力声明；
• Agent Token 本地持久化；
• pairing code 刷新不会使已有 Agent Token 失效；
• 不支持任意 shell 和远程生命周期命令。

安装

dsh plugin --profile web add @nevermindzzt/dsh-manager-plugin@0.4.0

安装后重启 dsh：

dsh web

dsh 设置

进入：

设置 → 插件 → dsh-manager-plugin → 配置

原生配置表单提供 Manager 隧道设置，以及独立的局域网直连设置。首次配对码和直连访问密码均为 secret/write-only 字段。Manager URL 为空时仍可单独启用直连监听；直连默认关闭并绑定 127.0.0.1。RC2 的 settings/document-updated(ns, revision) 会刷新设置并分别重建对应服务；重复或过期 revision 不会重复重建。更换配对码不会清除已有 Agent Token。没有 TLS fingerprint 配置项。

独立局域网直连

此模式由插件直接监听一个额外 HTTP 端口，将请求转发到 DSH Web 的 loopback 地址，不经过 dsh-manager：

其他设备浏览器 → dsh-manager-plugin 监听端口 → http://127.0.0.1:<DSH Web 端口>

启用位置：

设置 → 插件 → dsh-manager-plugin → 配置 → 局域网直连

• 默认关闭，默认监听 127.0.0.1:3081；只想本机测试时保持该地址。
• 要允许同一局域网其他设备访问，将监听地址设为 0.0.0.0，端口默认 3081，并在浏览器访问 http://<运行 DSH 的电脑局域网 IP>:3081/。该版本按 Host 与本机接收网卡地址比对；请使用网卡 IP，不支持任意 DNS 别名或放在另一个反向代理后面。
• 访问密码可选；设置时至少 8 位。插件使用 HttpOnly、SameSite Strict 的短时登录 Cookie；密码变更或 DSH 重启后，旧登录会话会失效。设置页的“清除已保存密码”会移除密码配置。
• 无密码时，任何能够连接监听端口的设备都可以使用完整 DSH Web 权限；它不是只读页面，也没有按用户区分权限。只在你信任的局域网中启用。
• 当前直连端口使用普通 HTTP。HTTP 不加密密码、Cookie、提示词或回复内容，只用于可信局域网；不要将端口直接映射到公网。跨不可信网络访问请使用 VPN，或另行配置带 Host/Origin 校验与身份认证的 HTTPS 入口。
• 防火墙仍需允许运行 DSH 的电脑接收该端口；端口冲突会导致插件报告监听失败。

直连服务与 Manager 隧道是独立开关：可只用直连而不配置 Manager URL，也可以同时使用两种入口。

Manager URL

可信内网：

http://manager.example.com:10090

通过 HTTPS 反向代理：

https://manager.example.com

HTTPS 由 Node.js 系统 CA 校验；插件不接受私有证书 fingerprint，也不会关闭证书校验。

环境变量

DSH_MANAGER_URL=http://manager.example.com:10090
DSH_MANAGER_PAIRING_CODE=one-time-code
DSH_MANAGER_NAME=linux-dsh
DSH_MANAGER_INSTANCE_ID=default

未配置 DSH_MANAGER_URL 时插件保持禁用。

本地凭证

默认状态文件：

~/.dsh/manager-agent.json

保存内容包括 Agent ID、Agent Token、manager URL、Agent 名称、实例 ID，以及用于重新 enrollment 的 pairing code。状态文件权限为 0600；startup URL/token 不会保存，日志和远端 Settings descriptor 不暴露 pairing code。

DSH Web bootstrap

DSH Web UI 只接受启动时打印的一次性 GET /?token=...，成功后颁发 Cookie 并重定向到 /。插件通过 ctx.connection.authenticatedUrl() 得到启动 URL，但只把它保存在当前进程内存中：

1. manager 对新的 /dsh/<session>/ 根请求发送 bootstrap:true；
2. 插件才访问内存中的 startup URL；
3. DSH 的 303 和 Set-Cookie 返回 manager；
4. 后续请求使用浏览器 Cookie；
5. manager WebSocket open 请求携带浏览器 Cookie，插件转发到本地 DSH WebSocket。

安全边界

• Agent Token 不提交到 Git；
• manager 只保存 Token Hash；
• plain HTTP 不提供传输加密，只用于可信网络；
• 公网必须使用外部 HTTPS/WSS 反向代理；
• 插件只代理当前 dsh Web 服务；
• startup token 不持久化、不写入日志；
• 不接受 manager 下发任意 shell。

开发与验证

npm install
npm test

测试覆盖 HTTP manager transport、enrollment 生命周期、DSH 0.1.7 Config defaults/volatile/secret metadata、旧 saved-state 回退、ConfigForms 更新触发隧道重建、DSH startup bootstrap、Set-Cookie、gzip、二进制/流式 HTTP 和 authenticated WebSocket Cookie forwarding。

相关项目

• dsh-manager
• dsh-launcher
• DeepSeek Harness

MIT