@nevermindzzt/dsh-manager-plugin

本版本使用 DSH 0.1.2-rc.1 提供的 ctx.settings.installSection() API，不再导入已移除的 settingsNamespace 或 installSettingsSection 顶层导出。

0.2.3 transport and relay optimization

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

架构

浏览器
  ↓ HTTP / WebSocket（或外部代理终止后的 HTTPS / WSS）
dsh-manager 单一 HTTP 端口
  ↓ HTTP / WS Agent Protocol v1
dsh-manager-plugin
  ↓ 本地 dsh HTTP / WebSocket
当前 dsh 实例

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

能力

• 使用首次配对码完成一次性注册；后续连接只使用 Agent Token；
• HTTP/HTTPS enrollment（HTTPS 由外部代理提供）；
• WS/WSS Agent 长连接（WSS 由外部代理提供）；
• HTTP 请求反向代理；
• WebSocket 双向代理；
• 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/[email protected]

安装后重启 dsh：

dsh web

dsh 设置

进入：

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

配置项：启用 dsh-manager 直连、Manager URL、首次配对码、Agent 名称和实例 ID。没有 TLS fingerprint 配置项。保存后插件会重新建立连接。

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。startup URL/token 不会保存。

DSH 0.1.2-rc.1 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 startup bootstrap、Set-Cookie、gzip 响应保留、二进制 HTTP 响应帧、HTTP proxy 和 authenticated WebSocket Cookie forwarding。

相关项目

• dsh-manager
• dsh-launcher
• DeepSeek Harness

MIT