dsh-remote-panel-ssh
Verifieddsh-remote-panel-ssh · v0.1.2 · Apache-2.0 · Web UI
Embed a remote DeepSeek Harness inside the desktop app, and sync local plugins and model providers to it: SSH bootstrap, on-demand remote dsh install, loopback tunnel, same-machine gateway, and a guided sync flow.
Install
dsh plugin add dsh-remote-panel-ssh Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
Remote DSH Panel
把一台远程 Linux 机器上的 DeepSeek Harness 直接嵌进桌面应用的侧边栏面板:左侧一个「远程 DSH」入口,点开选主机,远端那套会话 / 工作区 / 文件都在面板里,就像本地的一样。
A DeepSeek Harness (DSH) plugin that runs a remote harness inside the desktop app's own window: SSH bootstrap, on-demand remote
dshinstall, loopback tunnel, and a same-machine gateway that serves the remote UI to a panel iframe.
为什么需要这层网关
DSH 桌面壳的页面来自自定义 scheme dsh-app://app,而远端 dsh web 是 http://127.0.0.1:<port>。直接把远端塞进 iframe 会遇到两个死结:
- 登录 cookie 跨不过去:远端的鉴权 cookie 是
SameSite=Strict,在dsh-app://的第三方上下文里根本不会被发送 → 页面 401; - cookie 还绑定 authority:
Set-Cookie的 payload 里写着127.0.0.1:<远端端口>,端口一变就失效。
所以本插件不让浏览器碰 cookie:
桌面壳 (dsh-app://app)
└─ iframe → http://127.0.0.1:<网关端口>/ ← 本机 http,无需任何 cookie
└─ 网关(插件宿主进程内)
├─ 自己完成 ?token= → Set-Cookie 的换取
├─ 转发 HTTP(重写 Host/Origin/Referer,带上远端 cookie)
├─ 转发 WebSocket(/api/remote.mux,原样升级)
└─ 注入 Esc 桥接脚本(见下)
└─ 本地隧道 127.0.0.1:<随机> → 远端 127.0.0.1:<dsh web 端口>
└─ SSH 连接 → ssh2.forwardOut()
所有远程操作都走 SSH,因此远端只需要把 dsh web 绑在 127.0.0.1,不需要暴露到局域网,也不需要额外装任何 helper。
功能
| 能力 | 说明 |
|---|---|
| 主机列表 | 自动复用 ~/.dsh/dsh-ssh.json 里已配置的 SSH 主机(标记「SSH 插件」),也可以在面板里自己添加(标记「本面板」) |
| 添加主机 | 名称、主机/IP、SSH 端口、用户名、密码、远端 dsh web 端口、安装用代理(可选) |
| 连接测试 | 只探测、不安装不启动:SSH 是否通、Node 版本、远端 dsh 版本是否与本地一致、远端 dsh web 是否在跑,并给出耗时 |
| 删除主机 | 本面板添加的直接删除;来自 SSH 插件的会在确认后同时从 ~/.dsh/dsh-ssh.json 移除 |
| 自动安装 | 远端没有 dsh 或版本不一致时,自动 npm i -g --prefix "$HOME/.local" @deepseek-ai/dsh@<本地版本>,安装过程有阶段提示与耗时 |
| 自动启动 | 确保远端 dsh web 在跑;没跑就 nohup ... --host 127.0.0.1 --port <webPort> --no-open 拉起来(最多等 40 秒) |
| 会话内嵌 | 面板里直接是远端 DSH,可重新加载 / 断开 |
| 放大 | 面板铺满整个窗口(保留 Windows 三个窗口按钮与任务栏),按 Esc 退出 |
| 剪贴板 | iframe 显式委派 clipboard-read; clipboard-write,远端「复制链接」可用;另外提供「在新窗口打开」作为兜底 |
| 自动恢复 | 远端 401(例如重启换了 token)时网关自动重读 token 并重试一次 |
| 旧进程自愈 | 连接时若远端 dsh web 的启动时间早于当前 dsh 包的安装时间(典型场景:刚自动升级完版本,或有人升级了包却没重启服务),自动结束旧进程并用新版本重启。旧进程会一直沿用启动时打包的插件清单,新客户端用它会大面积 pending(缺 contextMenus / fileDrag 等),重启是唯一解法 |
| 启动防重 | 端口被占用时只等待、绝不再拉第二个 dsh web:重复启动会 EADDRINUSE 并把写着 token 的日志整个截断,连接随即报「远端日志里没有 token」 |
| token 自愈 | 日志里确实没有 launch token 时(历史上的截断、或服务是有人手工起的),自动重启远端服务一次以取回 token,且只重试一次,不会在 401 循环里反复重启 |
| 配置同步 | 把本地 profile 已安装的插件、llm-pi-ai 模型 provider、默认模型和 API Key 同步到远端 profile,支持预演、备份与重启 |
安装
从 npm 安装(推荐)
dsh plugin --profile desktop add dsh-remote-panel-ssh
装完完全退出 DSH 桌面应用(托盘也要退)再打开,左侧出现「远程 DSH」。依赖 ssh2 由安装器一并装好。
名字是
dsh-remote-panel-ssh:registry 上的dsh-remote-panel属于另一位作者的另一个项目,dsh-remote-ssh/dsh-remote-desktop也都已被占用。
从 GitHub 安装(备选)
dsh plugin --profile desktop add github:1583477320/remote-dsh
国内网络直连 GitHub 可能超时;这种情况下优先用上面的 npm 方式。
从本地克隆安装(开发 / 离线)
git clone https://github.com/1583477320/remote-dsh.git
cd remote-dsh
dsh plugin --profile desktop add link:$(pwd)
link: 会建软链指向仓库目录:改代码后完全退出应用再打开即生效(客户端 bundle 带 rev,必须重启才会刷新)。
手动安装(等价做法)
把本仓库放到 profile 的
node_modules下:cp -r . ~/.dsh/profiles/desktop/node_modules/dsh-remote-panel-ssh在
~/.dsh/profiles/desktop/cordis.patch.yml末尾追加:- insert: - id: remote-dsh name: dsh-remote-panel-ssh完全退出 DSH 桌面应用(托盘也要退)后重新打开,左侧出现「远程 DSH」。
插件依赖
ssh2。若手动拷贝,请确认 profile 的node_modules里能解析到ssh2(dsh plugin add会自己装依赖)。
使用
左侧点「远程 DSH」;
选一台主机,先点 测试 看环境(推荐,尤其新机器):
SSH 正常 · Node v24.18.0 · dsh 未安装(连接时会自动安装) · 远端 dsh web 未运行(连接时会启动) · 842ms点 连接,首次会经历:
SSH → 检查环境 → 安装 dsh(如需)→ 启动 dsh web → 建立通道,面板会在每一步显示阶段与已用秒数;连上后:重新加载 / 放大(
Esc退出)/ 在新窗口打开 / 断开;远端 DSH 是独立登录态,第一次需要在那套界面里登录一次 DeepSeek 账号(或用 API key)。
同步本地配置到远端
主机列表里每个主机多了一个 同步 入口,流程是「读取计划 → 勾选 → 预演/开始」:
- 点 同步,插件会同时读取本地 profile(默认
desktop)与远端 profile(默认web); - 勾选要同步的插件和模型 provider,决定是否同步默认模型、API Key、是否重启远端;
- 可以先勾 只预演,不写入远端,确认将安装的版本、将写入的 provider 和默认模型;
- 点 开始同步,页面会显示阶段和实时日志。
同步做四件事:
| 步骤 | 行为 |
|---|---|
| 插件 | 对每个勾选的插件执行 dsh plugin --profile <profile> add <name>@<本地精确版本>;远端已装同版本且已启用时跳过 |
| 模型配置 | 在远端 profile 的 cordis.patch.yml 末尾写一段带标记的托管块,包含 llm-pi-ai 的 provider 和 agent-default-model;每次同步整块替换,托管块之外的文本原样保留 |
| API Key | 用本机 credentials 服务解析 apiKeyEnv 引用的值,合并写入远端 ~/.dsh/.env(0600),不落日志、不回传页面 |
| 校验 / 重启 | 用 dsh --profile <profile> --dump-config 校验;失败会恢复 patch 备份。勾选重启时杀掉远端旧的 dsh web 并按原端口重新拉起 |
注意:
- 第一次同步前,远端需要已有可用的
dsh;没有就先点 连接 让插件安装; - 模型 provider 是整组替换:远端有、本地没有的 provider 会被移除;每次改写前会生成
cordis.patch.yml.bak-remote-dsh-<时间>备份; - 不勾选「默认模型」时远端默认模型保持不变;如果它指向本次被移除的 provider,远端会出现模型不可用。
- 只同步本插件能识别的部分:插件包、
llm-pi-aiprovider、默认模型、.env里的 API Key;MCP 条目、会话、账号登录态、其他插件配置不在范围内; - 标注「仅支持 Windows」的插件会显示为不可选(例如
dsh-screenshot-plugin); - 重启远端
dsh web会让当前已连接的远端面板断开,需要重新连接; - 远端 profile 名称默认为
web;如果远端用的是别的 profile,在同步页里改名称后点「读取此 profile」。
主机字段
| 字段 | 默认值 | 说明 |
|---|---|---|
label |
主机地址 | 列表里显示的名称 |
host / sshPort |
— / 22 |
SSH 目标 |
user / password |
— | SSH 凭据(也支持复用 dsh-ssh 的密钥条目) |
webPort |
18080 |
远端 dsh web 监听端口(仅 127.0.0.1) |
installProxy |
空 | 自动安装时使用的 HTTP 代理;留空会尝试探测远端 127.0.0.1:7890 |
dshBin |
~/.local/bin/dsh |
远端 dsh 可执行文件(环境变量 DSH_BIN 可覆盖探测) |
webLog |
~/.dsh/logs/dsh-web.log |
远端 dsh web 日志(token 从这里读) |
环境变量
| 变量 | 作用 |
|---|---|
DSH_REMOTE_HOST / DSH_REMOTE_PORT |
覆盖内置示例主机(仅调试用) |
DSH_REMOTE_STATE_URL |
覆盖远端 helper 地址(兼容早期的 /state 模式) |
DSH_BIN |
远端 dsh 路径 |
数据与安全
- 面板添加的主机保存在
~/.dsh/remote-dsh.json,权限 0600,密码为明文(与 dsh-ssh 的~/.dsh/dsh-ssh.json同一套信任模型); - 远端
dsh web只监听127.0.0.1,不暴露到局域网; - 网关只监听
127.0.0.1:<随机端口>,且自身持有远端 session cookie:访问该端口的本机进程等价于“已登录远端”,插件卸载/断开时随会话关闭; - 启动令牌(
?token=)只在宿主进程内使用,从不下发到浏览器; - 远端 401 时网关自动重新换取 cookie。
已知限制
- 远端必须是 Linux(Windows/macOS 未验证),需要 Node
^22.19 || >=24与npm; - 远端 dsh 版本必须与本地 client 完全一致:client 的 Remote 能力集合是构建期固定的,跨版本连不通,所以插件安装时会 pin 到本地版本;升级后不需要手动重启远端
dsh web,连接时会自动结束旧进程再拉起; npm默认跳过 install scripts 时,远端 DSH 的终端可能不可用(node-pty原生模块未编译),Web UI 本身不受影响;- 每个主机同一时刻只保留一条会话;断开只关本地隧道与网关,不杀远端进程;
- 剪贴板依赖 iframe 的权限委派;若桌面壳的安全策略仍拒绝,请用「在新窗口打开」或手动选中 +
Ctrl+C; - 放大模式的退出方式为
Esc(网关注入的桥接会把远端页面里的 Esc 传回外层);远端弹窗打开时 Esc 归弹窗使用; - 同步只覆盖本插件认识的配置:插件版本、
llm-pi-aiprovider、默认模型与 API Key;远端独有的 provider 会被整组替换,改写前有备份但没有自动合并; - 本地用
link:/file:装的插件(开发中的源码目录)不会被同步:远端没有那份源码,同名 npm 版本通常是另一个构建,装过去等于装错代码。这类条目在同步页里会标灰并写明原因; - 同步要求远端已装
dsh且版本与本地一致;不一致时请先「连接」让插件升级远端。
源码地图
| 文件 | 职责 |
|---|---|
lib/index.js |
宿主入口:/api/remote-dsh/{hosts,connect,disconnect,state,test,sync,sync/plan,sync/state} 路由、连接/同步任务与阶段状态 |
lib/hosts.js |
主机存储(remote-dsh.json)与 dsh-ssh.json 的读取/删除 |
lib/remote.js |
一次会话:SSH 连接 → 环境检查 → 自动安装 → 启动/复用 dsh web → 读 token → 隧道 → 网关;也提供同步用的远端重启 |
lib/gateway.js |
本机网关:cookie 换取、HTTP/WebSocket 转发、HTML 注入(Esc 桥接)、gzip 处理、401 自愈 |
lib/plan.js |
读取本地 profile 的插件清单、llm-pi-ai provider、默认模型,生成同步计划 |
lib/patch.js |
纯函数:YAML 托管块渲染/合并、.env 合并、provider 选取、插件版本比较 |
lib/sync.js |
同步任务:SSH 检查 → 安装 pnpm/插件 → 写 patch → 合并 .env → --dump-config 校验 → 可选重启 |
lib/client.js |
浏览器半区:侧边栏入口、主机列表/表单、连接阶段轮询、iframe 内嵌、放大与 Esc、同步表单与日志 |
开发提示
- 客户端 bundle 是经典脚本,用
window.__ModuleLoader__.load({ id, factory })包装,factory里require('react'),返回带apply/inject的module.exports; - 改了
lib/client.js或宿主文件都需要完全退出应用再打开(客户端 bundle 带 rev,宿主在启动时加载插件); - 面板注册使用官方扩展点:
ctx.slots.inject('sidebar.panellist', …)与ctx.slots.inject('main', …)。
License
Apache-2.0