19 KiB
内置 SSH 与远程文件夹实施方案(审阅稿)
日期:2026-11-03
仓库:dsh-workspace-groups(workspace-groups-local@1.3.0)
目标:不再把 @zhangfengshun/dsh-remote-ssh 作为运行依赖,由本插件自己提供 SSH 连接、远程目录、远程文件夹工作区和文件/终端能力。
0. 结论先行
- 传输层用系统 OpenSSH,不自写 SSH 协议。 继续用
ssh/sftp这套已验证的客户端,保留~/.ssh/config、ProxyJump、known_hosts、密钥代理、老 HPC 算法和 2FA 兼容性;插件自己负责连接管理、文件操作、镜像工作区和 UI。这样“内置”指不依赖 Remote-SSH 插件,不是“不依赖系统 ssh”。 - 远程文件夹仍然使用 mirror-backed 原生 Workspace。 浏览器只看到本地镜像路径,Host 用
.workspace-groups-remote.json把它映射到远端;原生 Workspace 身份和已有会话不重建。 - 先做可替换的最小闭环,再补完整工具面。 先完成“连接配置 → 远程选目录 → 建远程文件夹 → 重启后仍可用 → 删除/迁移”,再接文件写回、终端、exec、glob/grep、同步。不要一开始就重写 13 个工具。
关键限制先说清楚:DSH 的通用 bash/终端执行仍以本地 Workspace 的
cwd为准。内置 SSH 能做到“远程文件夹 + 显式远程工具 + 远程终端”,不能仅靠插件让 Agent 的所有 bash 命令在 HPC 上执行;后者需要 DSH 平台提供远程执行层。若你的预期是后者,这份方案的边界需要先扩大。
1. 目标与非目标
1.1 目标
- 卸载
@zhangfengshun/dsh-remote-ssh后,分组、文件夹、远程目录选择、远程工作区创建仍可用。 - Host 端持有 SSH 配置、密钥路径、连接池、超时/重连、SFTP/命令执行;浏览器端不接触私钥内容和密码。
- 远程目录选择、远程文件夹创建、删除、重新打开、离线提示完整。
- 远程写入失败硬失败,绝不静默写本地镜像;读缓存明确标记“离线副本”。
- 兼容现有
~/.dsh/remote-workspaces镜像和旧 Remote-SSH 记录,可回滚。 - Windows 本地 + Linux/macOS 远程;Unicode、空格、单引号路径可用。
1.2 非目标(v1 不做)
- 不做远程 Windows 主机(Remote-SSH 当前也主要按 POSIX 远程设计)。
- 不把 SSH 私钥、密码、passphrase 写入浏览器 bundle、URL、日志、marker 或普通配置文件。
- 不做跨设备云同步;镜像仍是本机缓存。
- 不在本方案里顺手修“本地/云端会话拆分”和“图标分类”,它们独立跟踪;但会预留 project identity 接口,避免再次写死。
2. 现状与约束
2.1 当前调用链
GroupsBrowser / FoldersDialog
-> src/client/folder-directory.ts
POST /remote-ssh/api/{listProfiles,listDir,remoteExec,createRemoteWorkspace,listWorkspaces,mkdir}
-> @zhangfengshun/dsh-remote-ssh (Host)
OpenSSH CLI + 连接池 + 镜像 + workspaceRegistry
-> ctx.workspaceRegistry.create(mirrorDir, title)
唯一远程 seam 是 src/client/folder-directory.ts:30-53;remoteExec("cd ... && pwd -P") 在 :141。当前 Host 只 inject = ['webServer'](src/index.ts:57-61),路由在 :122-348。
2.2 关键事实
- Remote-SSH 2.4.41 已安装,MIT,只发布
lib/index.js/lib/client.js,没有源码;不能可靠地 fork/vendor 维护。 - 它用
ctx.subprocess、ctx.workspaceRegistry,底层是系统ssh,不是 ssh2。 - 远程工作区本质是
workspaceRegistry.create(mirrorDir, title)注册的本地镜像目录;会话cwd指向镜像。 - 现有镜像 marker 是
.remote-ssh.json,里面含keyPath;新方案不能继续把密钥路径写进工作区可见文件。 - 现有测试:
tests/folders.test.ts、tests/tree.test.ts、tests/core.test.ts、tools/verify-folders.mjs、tools/verify-folder-directory.mjs(mock)、tools/verify-directory-flow.mjs、scripts/verify-groups.mjs(CDP 真机)。 - 构建:Host ESM + client CJS(
tsdown.config.ts:82-136),浏览器包不能 import Node builtins。
3. 传输层选型
| 维度 | 系统 OpenSSH(推荐) | ssh2 / node-ssh |
|---|---|---|
| 配置兼容 | 原生读 ~/.ssh/config、ProxyJump、Match、Include |
要自己解析,容易漏 |
| 认证 | key、agent、password、keyboard-interactive/2FA 都由 ssh 处理 | 要自己实现 askpass/2FA 流程 |
| 老 HPC 算法 | 跟随系统 ssh,兼容性最好 | 受库的算法列表限制 |
| 文件操作 | 需要 shell/SFTP 组合,需严格转义 | SFTP 原生、结构化、最稳 |
| 依赖 | 系统需有 ssh(Windows 可选功能) |
纯 JS,但 ssh2 有可选原生依赖 |
| 安全边界 | 复用成熟客户端;参数数组调用,不拼 shell | 自己处理 host key、超时、通道,代码面更大 |
| 迁移风险 | 与现有 Remote-SSH 行为最接近 | 需重新验证跳板、密码、算法、终端 |
决定:v1 用系统 OpenSSH。
理由:当前插件的行为基线就是 OpenSSH;用户环境已能连 HPC;换成 ssh2 会把“替换插件”变成“重写 SSH 客户端”,风险和工作量都更高。
本机已确认 C:\Windows\System32\OpenSSH\ssh.exe 与 sftp.exe 存在(PATH 中另有 OpenSSH_10.5p1),v1 不需要额外安装依赖。
保留后路:SshTransport 做成接口;如果未来要求“零系统依赖”,再加 ssh2 实现,不动上层。
4. 目标架构
Browser (React)
├─ SSH 设置 / 连接测试 / 远程目录选择器
├─ 只知道 profileId、displayName、目录项;不知道 keyPath/password
└─ fetch /workspace-groups/ssh/*
│
Host (Node ESM)
├─ SshProfileStore ~/.dsh/workspace-groups/ssh-profiles.json (0600)
├─ SecretVault 仅内存;密码/passphrase,重启即清
├─ SshTransport ctx.subprocess + ssh/sftp;超时、取消、重连、并发上限
├─ RemoteFs stat/list/read/write/mkdir/rename/delete/glob/grep
├─ RemoteWorkspaceService 镜像目录 + marker + workspaceRegistry.create/delete
├─ Migrator 旧 Remote-SSH 记录/镜像一次性导入
└─ RemoteTools 远程 exec/read/write/...(Host 工具,不经浏览器)
│
ctx.workspaceRegistry.create(mirrorDir, title)
│
~/.dsh/remote-workspaces/<recordId>/ ← 原生 Workspace 的 cwd
4.1 新增/修改文件
| 文件 | 作用 |
|---|---|
src/host-ssh/profiles.ts |
profile CRUD、校验、0600 原子写、导入 ~/.ssh/config |
src/host-ssh/transport.ts |
连接测试、命令执行、超时/取消、并发池、host key 策略 |
src/host-ssh/files.ts |
远程文件操作、路径规范化、原子写、大小上限 |
src/host-ssh/workspaces.ts |
镜像、marker、workspaceRegistry 注册/清理、幂等 |
src/host-ssh/migrate.ts |
旧记录/旧镜像导入、双读、回滚 |
src/host-ssh/tools.ts |
Host 侧 remote_* 工具注册(M2 起) |
src/client/ssh-settings.tsx |
连接管理 UI;密码只提交到 Host,不回显 |
src/client/remote-picker.tsx |
远程目录浏览;复用现有目录选择器样式 |
src/client/folder-directory.ts |
把 /remote-ssh/api/* 换成 /workspace-groups/ssh/*;保留六种操作 DTO,删掉 generic remoteExec |
src/index.ts |
注入 workspaceRegistry;注册 SSH 路由;统一错误 envelope |
src/host-folders.ts |
remote marker 只做 fail-closed;新增我们自己的 marker 校验 |
src/client/folders-persist.ts |
创建失败回滚,保证 members round-trip |
cordis.patch.yml |
如接终端 wrapper,补 terminal-controller 补丁;M2 再做 |
4.2 Host 路由(示意)
GET /workspace-groups/ssh/profiles
POST /workspace-groups/ssh/profiles
PATCH /workspace-groups/ssh/profiles/:id
DELETE /workspace-groups/ssh/profiles/:id
POST /workspace-groups/ssh/profiles/:id/test
POST /workspace-groups/ssh/profiles/:id/list
POST /workspace-groups/ssh/profiles/:id/mkdir
POST /workspace-groups/ssh/workspaces
GET /workspace-groups/ssh/workspaces
DELETE /workspace-groups/ssh/workspaces/:recordId
POST /workspace-groups/ssh/workspaces/:recordId/sync
响应统一 { ok: true, value } / { ok: false, error: { code, message } };沿用当前 HttpError 和请求体上限,不引入新的网络暴露面。
5. 数据模型
5.1 Profile
type SshAuth =
| { kind: 'key'; keyPath: string } // 仅 Host 可读;浏览器只看到 basename
| { kind: 'agent' }
| { kind: 'password' } // 密码不落盘,仅 SecretVault
interface SshProfile {
id: string // crypto.randomUUID()
name: string
host: string
port: number // 默认 22
user: string
auth: SshAuth
proxyJump?: string
remoteRoot: string // 默认 '~';文件操作必须落在此根下
connectTimeoutMs: number // 默认 15000
keepaliveSeconds: number // 默认 30
}
- 存储:
~/.dsh/workspace-groups/ssh-profiles.json,权限0600,原子 rename。 - 不存密码/passphrase;
SecretVault以profileId为键存在 Host 内存,重启清空。 - 导入
~/.ssh/config只复制 host/user/port/keyPath/proxyJump,不复制密码。
5.2 远程工作区记录
interface RemoteWorkspaceRecord {
id: string // 稳定 recordId,不用时间戳拼
profileId: string
title: string
remotePath: string // 用户看到的绝对路径
mirrorPath: string // 本地绝对路径
workspaceId: string // 原生 workspaceRegistry id
createdAt: string
schemaVersion: 1
}
Marker:<mirror>/.workspace-groups-remote.json
{"schemaVersion":1,"recordId":"...","profileId":"...","remotePath":"/home/u/proj"}
不写 host/user/keyPath/proxyJump;这些只在 Host profile store。旧 .remote-ssh.json 只读,不修改。
5.3 FolderMember
沿用 src/core/folders.ts:20-68 的 FolderMember,不新增必填字段;可选加:
remoteRecordId?: string // 只做诊断/迁移,不参与归属
workspaceId 仍是唯一权威;path 仍是镜像路径。不要用标题或 host 反推归属。
6. 安全不变量
| # | 不变量 | 验证 |
|---|---|---|
| S1 | 私钥内容永不进入 Host 响应、浏览器 bundle、日志、marker | 构建产物 grep BEGIN OPENSSH PRIVATE KEY;路由快照断言无 keyPath |
| S2 | keyPath 只在 Host profile store;浏览器只拿 basename | API 单测 |
| S3 | password/passphrase 只存内存,响应不回显,日志脱敏 | 重启后连接需重输;日志 grep |
| S4 | host key 默认 StrictHostKeyChecking=yes,使用应用私有 known_hosts;首次连接显示指纹并要求确认 |
中间人测试:换 key 必须失败 |
| S5 | 远程路径必须落在 profile remoteRoot 内,realpath -m 后校验;拒绝 ..、NUL、换行 |
路径穿越测试 |
| S6 | 所有进程用 argv 数组调用,禁止 shell: true;远程命令参数用 POSIX 单引号 + base64 |
注入测试(', $(...), 空格, 中文) |
| S7 | 写文件先写同目录临时文件,再 mv 原子替换;失败保留原文件 |
断连/磁盘满测试 |
| S8 | 远程写失败绝不回落本地镜像;读缓存只读并标 offline |
断网测试:镜像 mtime 不变,UI 明确报错 |
| S9 | 单命令/单文件有超时与大小上限;可取消;输出截断 | 大文件、sleep 999、kill |
| S10 | 删除远程文件夹只删本地记录/镜像,不删远端目录;删除远端目录需单独确认 | UI 文案 + 测试 |
补充:
- 使用应用私有 known_hosts:
~/.dsh/workspace-groups/known_hosts,提供“从~/.ssh/known_hosts导入”按钮;不静默接受新主机。 - 密码认证只在回环/受信 Host 上可用;若 GUI 通过局域网访问,提示改用密钥。
- 命令输出做 secret redaction;
ssh -v诊断只保留认证相关行,其他丢弃。
7. 远程工作区生命周期
7.1 创建
- 校验 profile +
remotePath,cd <path> && pwd -P解析绝对路径;不存在则按用户选择mkdir -p。 - 按
profileId + remotePath查重;已存在则复用 record,不新建。 - 生成稳定
recordId;镜像目录沿用~/.dsh/remote-workspaces/<recordId>。 - 创建镜像目录,写 marker(不含密钥信息),写一份只读
README.md说明“这是远程镜像,写操作请走远程工具”。 ctx.workspaceRegistry.create(mirrorPath, title);若已有同路径原生 Workspace,复用其 id 并setTitle。- 保存 record;返回
{mirrorPath, workspaceId, recordId, remotePath, profileId, reused}。 - 任一步失败:回滚已创建的原生 Workspace / 镜像;不写 folders overlay。客户端只有在拿到完整返回后才 PUT members。
7.2 删除
- 从 folders overlay 移除 member;
- 若无其他 member 引用同一
workspaceId,删除原生 Workspace 记录和镜像; - 不执行远端
rm -rf;UI 明确写“只移除本地映射,不会删除服务器文件”。
7.3 重开/离线
- 启动时只读 marker + record,不自动连 SSH;目录行显示“远程(离线)”状态。
- 用户点开或执行操作时才连接;失败显示具体阶段(DNS/TCP/认证/host key/权限),不把本地镜像伪装成远端成功。
8. 从 Remote-SSH 迁移
原则:先双读,后切换,可回滚;不重建原生 Workspace,不丢已有会话。
- 一次性读取旧插件
listWorkspaces(若仍安装)或扫描~/.dsh/remote-workspaces/*/.remote-ssh.json。 - 按
host + user + port + keyPath basename匹配/创建新 profile;密码不迁移,要求重输。 - 复用旧
mirrorPath和shellWorkspaceId(旧记录里有);生成我们的 record + marker。 - 迁移
FolderMember时保留workspaceId,只补remoteRecordId;不按标题合并。 - 旧插件仍保留安装但禁用;新插件通过 feature flag 接管。验收通过后再卸载旧插件。
- 回滚:保留旧
.remote-ssh.json和旧设置不动;关闭新 backend 即可回到旧插件。
9. 会话拆分问题(独立小任务)
用户看到的“同一项目在本地文件夹和云端文件夹分成两个会话列表”,根因大概率不是 SSH 传输,而是每个远程文件夹注册了不同的原生 Workspace,Session 的 workspaceId 不同。本方案只做两件事,避免加重问题:
- 创建远程文件夹时优先复用同一逻辑项目的 owner/member 归属,不产生新的顶层项目行。
- 预留
projectKey投影接口;后续用“canonical project”聚合会话,不直接改写 Session 归属。
需要一次平台能力验证(Phase 0):
能否在 owner Workspace 下创建
cwd = 远程镜像的 Session?
- 能:远程文件夹不新建 Workspace,会话天然统一,这是最优解。
- 不能:保留 mirror-backed Workspace,另做 UI 投影聚合。
在验证前不承诺“合并历史会话”。
10. 分阶段实施
| 阶段 | 内容 | 交付/验收 | 预估 |
|---|---|---|---|
| P0 决策与探针 | 确认传输选型;验证 owner Workspace + mirror cwd 是否可行;冻结六种 DTO 和错误码 | 一页探针结论;不写生产代码 | 0.5–1 天 |
| P1 连接与目录 | profiles、连接测试、known_hosts、远程 list/mkdir、SSH 设置页 | 不装 Remote-SSH 也能连 HPC、浏览目录 | 3–5 天 |
| P2 远程文件夹闭环 | 镜像、marker、workspaceRegistry、创建/删除/重开、folders 回滚、迁移 | 建远程文件夹,重启后仍在;删记录不删远端 | 3–5 天 |
| P3 文件与终端 | read/write/stat/rename/delete/glob/grep、原子写、离线态、终端 wrapper | 远程改文件失败不落本地;终端进 HPC | 4–7 天 |
| P4 工具面/同步 | exec 超时/取消、sync/push、上传、13 工具对齐、并发池 | 与旧插件功能对照表全绿 | 4–8 天 |
| P5 加固发布 | 安全测试、Unicode/空格/引号、大文件、断网、CDP 真机、文档与迁移说明 | 验收清单全过;可卸载旧插件 | 3–5 天 |
总计约 15–30 个工作日(单人;不含会话合并和图标分类)。如果只做 P1–P2,约 7–11 天,就能先摆脱“建远程文件夹必须装 Remote-SSH”。
11. 验收清单
功能
- 全新 profile:密钥、agent、密码(内存)三种认证都能连。
- ProxyJump /
~/.ssh/config的 Host 别名可用。 - 远程目录浏览支持
~、绝对路径、空格/中文/单引号目录。 - 创建远程文件夹后,原生 Workspace 的
cwd是镜像路径,标题正确。 - 重启 DSH 后,远程文件夹仍在,能重新打开。
- 删除远程文件夹只删本地映射,远端目录和文件不变。
- 旧 Remote-SSH 记录迁移后,已有会话仍挂在原 Workspace 下。
安全/失败
- 构建产物和 API 响应中搜不到私钥内容、密码、完整 keyPath。
- host key 变化时连接失败,不自动接受。
- 远程路径
../../etc、symlink 逃逸被拒绝。 $(touch /tmp/pwned)、反引号、换行注入不执行。- 断网写文件:报错,镜像文件字节不变。
- 命令超时/取消后子进程被 kill,无孤儿 ssh。
- 日志不含 Authorization、密码、passphrase。
兼容
- Windows 本地 + Linux 远程;macOS 本地 smoke。
- 远程 Unicode 文件名 round-trip。
- 大文件超过上限时明确拒绝,不截断后写回。
- 卸载 Remote-SSH 后,P1–P4 功能不回退。
12. 风险与待确认
- “完整内置”的边界:如果要求 Agent 的普通 bash 也在 HPC 执行,这不是本插件能单独完成的,需要 DSH 平台远程执行层;本方案只能做到显式远程工具 + 远程终端。
- 系统 OpenSSH 依赖:Windows 需启用 OpenSSH Client;安装页要检测
ssh -V并给出一键说明。若你要求零系统依赖,需改 ssh2,工期和兼容风险上升。 - 密码/2FA:v1 密码只存内存,重启要重输;keyboard-interactive 先走终端,Host 工具面后补。若必须持久化,需要接 OS 凭据库(DPAPI/Keychain/libsecret),单独评估。
- 远程 Windows 主机:v1 不做;POSIX shell 假设(
sh、base64、find、grep)。 - 终端 wrapper:需要
nodePath逃生舱(旧插件已有同类问题);Desktop 的 Host node 不一定在 PATH。 - 会话拆分:见第 9 节,先探针后承诺。
- 图标分类:与 SSH 无关,独立处理;当前通用 50 个图标未分节,材料 28 个已分 4 节。
13. 需要你拍板的三件事
- 传输层:系统 OpenSSH(推荐,兼容最好)还是纯 JS
ssh2(零系统依赖,但重写配置/跳板/2FA)? - 首期范围:只做 P1–P2(远程文件夹闭环,最快摆脱 Remote-SSH),还是一次做到 P4(完整工具面)?
- 密码策略:只存内存、重启重输(推荐,安全)还是接 OS 凭据库持久化?
确认后我再动代码;当前仓库工作树干净,未改任何实现文件。