@hyzyn/dsh-docker 0.8.0 → 0.9.0-rc.1

package/lib/ssh-exec.js

@@ -13,11 +13,69 @@
  * 这类长流走 stream()/runLocalStream()（无总超时、无上限，靠 AbortSignal 停止）。
  */
 import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { Duplex } from 'node:stream';
 import { StringDecoder } from 'node:string_decoder';
 import { Client } from 'ssh2';
+/**
+ * 清洗一份跳板机输入（`readTtyBooks` 用）。返回 `undefined` = 没配跳板机——不给下游留
+ * `host: ''` 的半个对象（那会让拨号去连空主机名）。
+ */
+export function sanitizeJumpSpec(input) {
+    if (typeof input !== 'object' || input === null)
+        return undefined;
+    const raw = input;
+    const host = typeof raw.host === 'string' ? raw.host.trim() : '';
+    if (host === '')
+        return undefined;
+    const port = Number(raw.port);
+    const jump = { host, port: Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 22 };
+    if (typeof raw.username === 'string' && raw.username.trim() !== '')
+        jump.username = raw.username.trim();
+    if (raw.auth === 'agent' || raw.auth === 'key' || raw.auth === 'password')
+        jump.auth = raw.auth;
+    if (typeof raw.keyPath === 'string' && raw.keyPath !== '')
+        jump.keyPath = raw.keyPath;
+    if (typeof raw.passphrase === 'string' && raw.passphrase !== '')
+        jump.passphrase = raw.passphrase;
+    if (typeof raw.password === 'string' && raw.password !== '')
+        jump.password = raw.password;
+    return jump;
+}
+/** 跳板机展示串（`user@host:port`）；没配时返回空串。**凭据不进这里**。 */
+export function jumpTargetLabel(spec) {
+    const jump = spec.jump;
+    if (jump === undefined || jump.host.trim() === '')
+        return '';
+    const port = jump.port ?? 22;
+    return `${jump.username ?? spec.username}@${jump.host.trim()}${port === 22 ? '' : ':' + String(port)}`;
+}
+/** 目标那一跳的展示串 + 跳板机 / 代理命令后缀（错误文案用；理由见 tty `src/ssh.ts` 的同名注释）。 */
+export function targetWithJump(spec) {
+    const label = jumpTargetLabel(spec);
+    if (label !== '')
+        return `${sshTarget(spec)}（经跳板机 ${label}）`;
+    if (sanitizeProxyCommand(spec.proxyCommand) !== undefined)
+        return `${sshTarget(spec)}（经代理命令）`;
+    return sshTarget(spec);
+}
+/** 跳板机那一跳的连接规格：显式给的优先，其余继承目标。 */
+function jumpSpecOf(spec) {
+    const jump = spec.jump;
+    const username = typeof jump.username === 'string' && jump.username.trim() !== '' ? jump.username.trim() : spec.username;
+    return {
+        host: jump.host.trim(),
+        port: jump.port ?? 22,
+        username,
+        auth: jump.auth ?? spec.auth ?? 'agent',
+        keyPath: jump.keyPath ?? spec.keyPath,
+        passphrase: jump.passphrase ?? spec.passphrase,
+        password: jump.password ?? spec.password,
+    };
+}
 let credentialsProvider = null;
 /** 由 index.ts 在可选注入里挂上（服务缺失即为 null，退回 process.env）。 */
 export function setCredentialResolver(resolver) {
@@ -95,8 +153,355 @@ export function shJoin(argv) {
  * 长流额度被悄悄翻倍（恰好掩盖 D07 想暴露的 MaxSessions 问题）。口径与 TOFU 的
  * hostVerifier（D03）保持一致：那里也用 `trim().toLowerCase()` 分组指纹。
  */
-function poolKey(spec) {
-    return `${spec.username}@${spec.host.trim().toLowerCase()}:${String(spec.port ?? 22)}`;
+/**
+ * 池键。**跳板机 / 代理命令身份必须并进来**：不同 bastion（或不同代理命令）到同一目标
+ * 绝不是同一条连接——只按 `user@host:port` 记的话，第二个 bastion 会静默复用第一条连接、
+ * 走错跳板机。这与 tty 的 SFTP 池不同（那边键是 `JSON.stringify(spec)`，天然带上 jump）。
+ *
+ * 代理命令**只并入它的哈希**，不并入原文：原文可能含凭据（`-i /path/key`、甚至嵌 token），
+ * 而池键会进日志/错误文案附近的诊断路径——摘要足够区分且不泄露。
+ */
+export function poolKey(spec) {
+    const basis = `${spec.username}@${spec.host.trim().toLowerCase()}:${String(spec.port ?? 22)}`;
+    const label = jumpTargetLabel(spec);
+    if (label !== '')
+        return `${basis}|jump:${label.toLowerCase()}`;
+    const proxyCommand = sanitizeProxyCommand(spec.proxyCommand);
+    if (proxyCommand !== undefined) {
+        return `${basis}|cmd:${createHash('sha256').update(proxyCommand).digest('hex').slice(0, 12)}`;
+    }
+    return basis;
+}
+/** 跳板机通道打开兜底（与 tty 同参数：对端不回 forwardOut 回调时不能让 await 挂着）。 */
+const JUMP_CHANNEL_TIMEOUT_MS = 15_000;
+/**
+ * 拨跳板机并借一条 forwardOut 通道（ProxyJump 单跳）。与 tty `src/ssh.ts` 的 dialJump 同序。
+ * **导出仅供单测**（`test/ssh-jump.test.ts` 用假 ssh2 验「先拨跳板机、再把通道当 sock」）。
+ */
+export async function dialJump(options) {
+    const jumpSpec = jumpSpecOf(options.spec);
+    const label = jumpTargetLabel(options.spec);
+    const destination = sshTarget(options.spec);
+    const bastion = new Client();
+    const closeQuietly = () => {
+        try {
+            bastion.end();
+        }
+        catch {
+            /* 已断开 */
+        }
+    };
+    let connectConfig;
+    try {
+        connectConfig = await buildConnectConfig(jumpSpec);
+    }
+    catch (error) {
+        throw new Error(`跳板机连接失败（${label}）：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const policy = applyHostKeyPolicy({ connectConfig, spec: jumpSpec, store: options.store, logger: options.logger, target: `跳板机 ${label}` });
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            closeQuietly();
+            reject(error);
+        };
+        bastion.once('ready', () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        });
+        bastion.on('error', (error) => {
+            fail(new Error(policy.mismatchMessage() ?? `跳板机连接失败（${label}）：${error.message}`));
+        });
+        bastion.once('close', () => {
+            fail(new Error(`跳板机连接已关闭（${label}）：目标连接尚未建立`));
+        });
+        if (connectConfig.tryKeyboard === true) {
+            const password = connectConfig.password ?? '';
+            bastion.on('keyboard-interactive', (_name, _instructions, _lang, _prompts, finishKb) => {
+                finishKb([password]);
+            });
+        }
+        try {
+            bastion.connect(connectConfig);
+        }
+        catch (error) {
+            fail(new Error(`跳板机连接失败（${label}）：${error instanceof Error ? error.message : String(error)}`));
+        }
+    });
+    const sock = await new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            closeQuietly();
+            reject(new Error(`跳板机通道打开超时（${label} → ${destination}，${String(JUMP_CHANNEL_TIMEOUT_MS / 1000)}s 无响应）：跳板机可能不允许转发或不响应`));
+        }, JUMP_CHANNEL_TIMEOUT_MS);
+        timer.unref?.();
+        bastion.forwardOut('127.0.0.1', 0, options.spec.host, options.spec.port ?? 22, (error, channel) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error !== undefined && error !== null) {
+                closeQuietly();
+                reject(new Error(`跳板机通道打开失败（${label} → ${destination}）：${error.message}`));
+                return;
+            }
+            resolve(channel);
+        });
+    });
+    options.logger?.info(`[dsh-docker] ssh ${destination} 经跳板机 ${label} 已建立转发通道（ProxyJump）`);
+    return { bastion, sock };
+}
+/* ------------------------------------------------------------------ *
+ * ProxyCommand：与 tty 同一档信任级（默认关闭 + 显式开关 + 导入永不自动带入）
+ * ------------------------------------------------------------------ */
+/** 代理命令长度上限（与 tty 同值：它是一条命令行）。 */
+export const PROXY_COMMAND_MAX = 2000;
+const PROXY_STDERR_KEEP = 2048;
+const PROXY_STDERR_SHOWN = 300;
+const PROXY_KILL_GRACE_MS = 2000;
+/** `%h` / `%r` 等展开值允许的字符集（与 tty 同口径：白名单而非转义，理由见 tty 同名常量）。 */
+const PROXY_VALUE_SAFE = /^[A-Za-z0-9._@:\[\]-]+$/;
+/**
+ * 闸门关着时报什么错。**与 tty 是同一个开关**（tty settings 的 `allowProxyCommand`）——
+ * 连接簿只有一处，开关也只能有一处，否则「连接簿配了、docker 不认」会很难解释。
+ */
+export const PROXY_COMMAND_DISABLED = '代理命令（ProxyCommand）未启用：本机命令执行默认关闭，请到 插件配置 → 终端面板 打开「允许 ProxyCommand」后重试。'
+    + '未启用时携带代理命令的目标不会退回直连——直连多半也连不上，还会把配置问题伪装成网络问题。';
+/**
+ * 清洗一份代理命令输入（`readTtyBooks` 用）。返回 `undefined` = 没配。
+ * 只做形状校验（非空 / 单行 / 长度）；命令内容不解释——「能不能执行」由闸门决定。
+ */
+export function sanitizeProxyCommand(input) {
+    if (typeof input !== 'string')
+        return undefined;
+    const trimmed = input.trim();
+    if (trimmed === '' || trimmed.length > PROXY_COMMAND_MAX)
+        return undefined;
+    if (/[\r\n\0]/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+/**
+ * 展开 `%h` / `%p` / `%r` / `%n` / `%%`（与 OpenSSH 同义，与 tty 逐字同口径：
+ * 代入值必须过白名单，否则拒绝执行——理由见 tty `expandProxyCommand`）。
+ */
+export function expandProxyCommand(command, spec) {
+    const values = {
+        h: spec.host,
+        n: spec.host,
+        p: String(spec.port ?? 22),
+        r: spec.username,
+    };
+    return command.replace(/%(.)/g, (whole, key) => {
+        if (key === '%')
+            return '%';
+        const value = values[key];
+        if (value === undefined)
+            return whole;
+        if (!PROXY_VALUE_SAFE.test(value)) {
+            throw new Error(`代理命令里的 %${key} 无法代入：目标主机名 / 用户名含 shell 特殊字符（只允许字母数字与 . _ @ : [ ] -）`);
+        }
+        return value;
+    });
+}
+/** 杀代理命令（含它拉起的子孙进程）：与 tty `killProxyChild` 同策略（POSIX 杀进程组）。 */
+function killProxyChild(child) {
+    const pid = child.pid;
+    const kill = (signal) => {
+        try {
+            if (pid !== undefined && process.platform !== 'win32')
+                process.kill(-pid, signal);
+            else
+                child.kill(signal);
+        }
+        catch {
+            try {
+                child.kill(signal);
+            }
+            catch {
+                /* 已退出 */
+            }
+        }
+    };
+    kill('SIGTERM');
+    const timer = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null)
+            kill('SIGKILL');
+    }, PROXY_KILL_GRACE_MS);
+    timer.unref?.();
+}
+/**
+ * 启动代理命令（ProxyCommand）并把它的 stdio 当作目标连接的传输。
+ *
+ * 与 tty `src/ssh.ts` 的 dialProxyCommand **逐句同序**（两包不互相 import，只能各写一份；
+ * 语义口径由这份注释与单测钉住）：闸门 → 展开 → spawn → 提前退出拖垮传输 → stderr 常驻排空。
+ * **导出仅供单测**。
+ */
+export async function dialProxyCommand(options) {
+    const raw = sanitizeProxyCommand(options.spec.proxyCommand);
+    if (raw === undefined)
+        throw new Error('代理命令为空（proxyCommand 需要一条非空的单行命令）');
+    if ((options.allowed?.() ?? false) !== true)
+        throw new Error(PROXY_COMMAND_DISABLED);
+    const destination = sshTarget(options.spec);
+    const command = expandProxyCommand(raw, options.spec);
+    const child = spawn(command, {
+        shell: true,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+        detached: process.platform !== 'win32',
+    });
+    const stdout = child.stdout;
+    const stdin = child.stdin;
+    const stderr = child.stderr;
+    if (stdout === null || stdin === null || stderr === null) {
+        killProxyChild(child);
+        throw new Error('代理命令启动失败：stdio 管道未建立');
+    }
+    const sock = Duplex.from({ readable: stdout, writable: stdin });
+    let failure = null;
+    let disposed = false;
+    /**
+     * 传输是否已经关掉（子进程输出结束）。与 tty 同因：子进程**先结束输出、后触发 `exit`**，
+     * 而 ssh2 一看到流断了就立刻报「Connection lost before handshake」——那一刻 `exit` 还没到。
+     * 只认 `exit` 的话，最需要解释的失败（命令一开始就挂）反而没有任何解释。
+     */
+    let transportClosed = false;
+    const chunks = [];
+    let kept = 0;
+    /** 已攒到的 stderr 摘要（单行、截断；没有则空串）。 */
+    const stderrExcerpt = () => {
+        if (chunks.length === 0)
+            return '';
+        const text = Buffer.concat(chunks).toString('utf8').replace(/[\r\n\0]+/g, ' ').replace(/\s+/g, ' ').trim();
+        return text.slice(0, PROXY_STDERR_SHOWN);
+    };
+    const stderrTail = () => {
+        const text = stderrExcerpt();
+        return text === '' ? '' : `；stderr: ${text}`;
+    };
+    stderr.on('data', (chunk) => {
+        if (kept >= PROXY_STDERR_KEEP)
+            return;
+        kept += chunk.length;
+        chunks.push(chunk);
+    });
+    const recordFailure = (error) => {
+        // **覆盖**而不是只记第一个：传输关闭先触发的往往语焉不详，随后 exit 带来的（退出码 +
+        // stderr）严格更有信息量
+        failure = error;
+        try {
+            sock.destroy();
+        }
+        catch {
+            /* 已销毁 */
+        }
+    };
+    child.on('error', (error) => {
+        recordFailure(new Error(`代理命令出错：${error.message}`));
+    });
+    child.on('exit', (code, signal) => {
+        if (disposed)
+            return;
+        const how = signal !== null ? `被信号 ${signal} 终止` : `退出码 ${String(code)}`;
+        recordFailure(new Error(`代理命令已退出（${how}）${stderrTail()}`));
+    });
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        child.once('spawn', () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        });
+        child.once('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`代理命令启动失败：${error.message}`));
+        });
+    });
+    options.logger?.info(`[dsh-docker] ssh ${destination} 已启动代理命令（ProxyCommand）作为传输`);
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        try {
+            sock.destroy();
+        }
+        catch {
+            /* 已销毁 */
+        }
+        killProxyChild(child);
+    };
+    /*
+     * **readable 侧 end** 是关键时点：ssh2 就是看到它才判定「握手前连接中断」并发错，
+     * 而子进程的 `exit` 还在后面（实测差 1~2ms）。所以在这里就认定「传输已关」，
+     * 错误路径才能带上已经攒到的 stderr。
+     */
+    sock.once('end', () => {
+        transportClosed = true;
+    });
+    sock.once('close', () => {
+        transportClosed = true;
+        // 不置 disposed：那是「我们主动收尾」的标记；子进程该杀，但它随后带来的 exit 事实要记下来
+        if (!disposed)
+            killProxyChild(child);
+    });
+    /*
+     * 必须挂这个监听器：`Duplex.from({readable, writable})` 销毁时会把 **AbortError** 抛给底层流，
+     * 没人接就是进程级「未捕获异常」（与 tty 同因，实测 dispose() 即可触发）。
+     */
+    sock.on('error', (error) => {
+        if (disposed)
+            return;
+        /*
+         * **AbortError 直接忽略**：它不是一个诊断，而是我们自己 destroy 这条传输时 Duplex 抛给
+         * 底层流的副产品（"The operation was aborted"）。把它记成失败原因，用户看到的就会是这句
+         * 毫无信息量的话，而不是「命令退出了、stderr 说了什么」。
+         */
+        if (error.name === 'AbortError' || error.code === 'ABORT_ERR')
+            return;
+        recordFailure(new Error(`代理命令传输出错：${error.message}`));
+    });
+    return {
+        child,
+        sock,
+        failure: () => {
+            if (failure !== null)
+                return failure;
+            if (disposed || !transportClosed)
+                return null;
+            const tail = stderrTail();
+            return new Error(`代理命令传输已关闭${tail === '' ? '（命令已结束）' : tail}`);
+        },
+        stderrHint: () => {
+            // 主动收尾之后不再提示（那是正常结束，不是线索）；没有 stderr 也不提示
+            if (disposed)
+                return '';
+            const text = stderrExcerpt();
+            return text === '' ? '' : `；代理命令 stderr: ${text}`;
+        },
+        dispose,
+    };
+}
+/** 代理命令失败的事实 → 错误文案后缀（空串 = 没失败），与 tty 同口径。 */
+export function proxyFailureSuffix(proxy) {
+    if (proxy === null)
+        return '';
+    const failure = proxy.failure();
+    if (failure !== null)
+        return `；${failure.message}`;
+    // 与 tty 同因的兜底：错误已经在报，手里有 stderr 就交出去（真机实测 1~2ms 的竞态）
+    return proxy.stderrHint();
 }
 /**
  * 有界输出收集器（短命令路径的 stdout / stderr 各持一个）。
@@ -211,7 +616,20 @@ export function streamBudgetError(target, busy, max = MAX_STREAMS_PER_TARGET) {
  * @param message - ssh2 给出的原始错误文案。
  * @returns 补了指向性说明的文案；不认识的原样返回。
  */
+/**
+ * SSH 超时文案里的**跳板机提示**（项目级 ROADMAP 第 2 项）。
+ *
+ * 为什么值得单独一句话：本插件经数据级复用读得到 tty 的连接簿，但**不读 `~/.ssh/config`**，
+ * 所以「配了跳板机的目标连不上」在 docker 侧只能表现为一句通用超时。企业内网主机几乎都
+ * 要过 bastion，用户需要的是「可能是什么原因、以及这个版本到底支不支持」——而不是 20 秒后
+ * 一句放之四海皆准的「主机无响应」。
+ */
+export const SSH_TIMEOUT_HINT = '若该主机只能经跳板机访问，请在目标引用的那条 tty 连接簿条目里配置跳板机'
+    + '（连接簿的 `~/.ssh/config` 导入会自动带上 ProxyJump）；'
+    + '代理命令（ProxyCommand）同一处手动填写后，还需在 插件配置 → 终端面板 打开「允许 ProxyCommand」';
 export function describeExecError(message) {
+    if (/Timed out|ETIMEDOUT/i.test(message))
+        return `${message}：${SSH_TIMEOUT_HINT}`;
     if (!/Channel open failure|open failed/i.test(message))
         return message;
     return `${message}（远端 sshd 拒绝了新通道：同一连接上的通道额度可能已被实时流占满——`
@@ -251,11 +669,21 @@ export function shouldRecycleConn(conn, now, idleMs = IDLE_MS) {
 export class RemoteExec {
     logger;
     store;
+    options;
     conns = new Map();
     sweeper = null;
-    constructor(logger, store) {
+    constructor(logger, store, 
+    /**
+     * ProxyCommand 闸门求值器（缺省 = 恒关）。
+     *
+     * 为什么是**回调**而不是构造时读一次的布尔值：开关归 tty settings，本包的 settings 句柄是
+     * 运行时才就绪的，而且用户随时可能关掉它——关掉之后必须**立刻**对下一次拨号生效
+     * （留着旧值意味着「关了还能用」，那正是这一档最不能出的错）。求值只读内存，无 IO。
+     */
+    options = {}) {
         this.logger = logger;
         this.store = store;
+        this.options = options;
     }
     /** 插件卸载：关定时器与全部连接（幂等）。 */
     disposeAll() {
@@ -273,6 +701,16 @@ export class RemoteExec {
             catch {
                 /* 连接已断开 */
             }
+            try {
+                rt.jump?.end();
+            }
+            catch {
+                /* 连接已断开 */
+            }
+            rt.jump = null;
+            // 代理命令是子进程：只 end() 目标 client 不会杀它（ssh2 不管子进程生死）
+            rt.proxy?.dispose();
+            rt.proxy = null;
         }
         this.conns.clear();
     }
@@ -500,6 +938,17 @@ export class RemoteExec {
                 catch {
                     /* 连接已断开 */
                 }
+                // 空闲回收同样要成对：只关目标会留下一堆 keepalive 养着的跳板机连接
+                try {
+                    rt.jump?.end();
+                }
+                catch {
+                    /* 连接已断开 */
+                }
+                rt.jump = null;
+                // 代理命令一并杀（空闲回收后它没有任何用了，留着就是常驻孤儿进程）
+                rt.proxy?.dispose();
+                rt.proxy = null;
             }
             if (this.conns.size === 0 && this.sweeper !== null) {
                 clearInterval(this.sweeper);
@@ -538,7 +987,21 @@ export class RemoteExec {
             if (attempt === 0 && isTransportError(message)) {
                 // 丢掉这条连接并**关闭它**（D07）：只摘出池不 end() 的话，keepalive 会一直
                 // 养着一条死连接；dropConn 带身份校验，不会误摘同键上的新连接（D06）。
-                this.dropConn(poolKey(spec), client);
+                const key = poolKey(spec);
+                const stale = this.conns.get(key);
+                if (stale !== undefined && stale.client === client) {
+                    // 跳板机 / 代理命令也一起收：重连会重新拨一条，旧的留着只会白养一条连接 / 一个进程
+                    try {
+                        stale.jump?.end();
+                    }
+                    catch {
+                        /* 连接已断开 */
+                    }
+                    stale.jump = null;
+                    stale.proxy?.dispose();
+                    stale.proxy = null;
+                }
+                this.dropConn(key, client);
                 try {
                     client.end();
                 }
@@ -570,7 +1033,7 @@ export class RemoteExec {
         // 循环——若此时池里还没有条目，并发第二个请求会各自建连，先建好的那条立即脱管
         //（回收不到、disposeAll 关不掉、配额记在别人头上），日后的 close/error 还会误摘
         // 同键的新连接（D06）。占位后并发请求拿到的就是同一条 ready。
-        const entry = { client, lastUsed: Date.now(), ready, busy: 0, inflight: 0, disposed: false };
+        const entry = { client, lastUsed: Date.now(), ready, busy: 0, inflight: 0, disposed: false, jump: null, proxy: null };
         this.conns.set(key, entry);
         // ready 被拒时不要留下未处理 rejection（调用方 await 时会拿到）
         ready.catch(() => {
@@ -604,6 +1067,27 @@ export class RemoteExec {
                 /* 同上 */
             }
         };
+        /**
+         * 关掉这条条目上的跳板机 / 代理命令（目标 client 只是借用它们的通道 / stdio，必须成对收）。
+         *
+         * 两者**都要**做（不是二选一）：拨号时按 ProxyJump 优先只起一条，但这里只关心「条目上
+         * 挂了什么」，写成两行就不必再判一次谁生效——no-op 的代价远低于漏收尾。
+         */
+        const closeTransport = () => {
+            const jump = entry.jump;
+            entry.jump = null;
+            if (jump !== null) {
+                try {
+                    jump.end();
+                }
+                catch {
+                    /* 已断开 */
+                }
+            }
+            const proxy = entry.proxy;
+            entry.proxy = null;
+            proxy?.dispose();
+        };
         const settleError = (error) => {
             if (settled)
                 return;
@@ -615,15 +1099,52 @@ export class RemoteExec {
             const finalError = ownsEntry() ? error : new Error(`SSH 连接已在建立期间被释放（${target}）：请重试`);
             this.dropConn(key, client);
             forceClose();
+            closeTransport();
             rejectReady(finalError);
         };
         try {
             const connectConfig = await buildConnectConfig(spec);
+            /*
+             * 跳板机（ProxyJump 单跳）：先拨它、借一条 forwardOut 通道，再把目标连接跑在这条
+             * 通道上（`ConnectConfig.sock`）。拨号失败/超时都在 dialJump 里点名跳板机并自我清理；
+             * 成功后这条「跳板机连接」登记在池条目上，与目标成对关闭（见 closeRuntime）。
+             */
+            const proxyCommand = sanitizeProxyCommand(spec.proxyCommand);
+            if (spec.jump !== undefined) {
+                if (proxyCommand !== undefined) {
+                    // 两者同时配：按 OpenSSH 语义 ProxyJump 优先，但**不静默**（用户以为走的是代理命令最坏）
+                    this.logger.warn(`[dsh-docker] ssh ${sshTarget(spec)} 同时配了跳板机与代理命令：按 OpenSSH 语义走跳板机（ProxyJump 优先），代理命令被忽略`);
+                }
+                const dialed = await dialJump({ spec, store: this.store, logger: this.logger });
+                entry.jump = dialed.bastion;
+                connectConfig.sock = dialed.sock;
+            }
+            else if (proxyCommand !== undefined) {
+                /*
+                 * 代理命令（ProxyCommand）：整档信任级，闸门由 tty settings 的 `allowProxyCommand`
+                 * 决定（回调按**每次拨号**求值，用户一关就立刻生效）。关着时 dialProxyCommand 直接抛
+                 * 明确的错——**不退回直连**，并由 settleError 收掉占位条目。
+                 */
+                const dialed = await dialProxyCommand({ spec, allowed: this.options.proxyCommandAllowed, logger: this.logger });
+                entry.proxy = dialed;
+                connectConfig.sock = dialed.sock;
+            }
             const policy = applyHostKeyPolicy({ connectConfig, spec, store: this.store, logger: this.logger, target });
-            /** 指纹变更优先于任何通用文案（含 D94 的「已释放」）：安全提示不能被噪音盖掉。 */
-            const describe = (error, fallback) => new Error(policy.mismatchMessage() ?? `${fallback}：${error.message}`);
+            /**
+             * 指纹变更优先于任何通用文案（含 D94 的「已释放」）：安全提示不能被噪音盖掉。
+             * 握手超时则补上跳板机提示——那是「通用超时」最容易被误读的成因（ROADMAP 第 2 项）。
+             */
+            const describe = (error, fallback) => {
+                const mismatch = policy.mismatchMessage();
+                if (mismatch !== null)
+                    return new Error(mismatch);
+                const hint = /Timed out|ETIMEDOUT/i.test(error.message) ? `：${SSH_TIMEOUT_HINT}` : '';
+                // 代理命令死了的话 ssh2 只会报「握手完成前关闭」——把退出码 / stderr 补在后面，
+                // 否则用户会去查目标主机（那里没有任何问题）
+                return new Error(`${fallback}：${error.message}${hint}${proxyFailureSuffix(entry.proxy)}`);
+            };
             timer = setTimeout(() => {
-                settleError(new Error(`SSH 连接超时（${target}）`));
+                settleError(new Error(`SSH 连接超时（${targetWithJump(spec)}）：${SSH_TIMEOUT_HINT}`));
             }, connectTimeoutMs());
             client.once('ready', () => {
                 if (settled)
@@ -636,19 +1157,35 @@ export class RemoteExec {
                     // 交出去就是脱管连接——关掉再拒绝（D94）
                     this.dropConn(key, client);
                     forceClose();
+                    closeTransport();
                     rejectReady(new Error(`SSH 连接已被释放（${target}）：请重试`));
                     return;
                 }
                 entry.lastUsed = Date.now();
                 resolveReady(client);
             });
-            client.once('error', (error) => {
-                settleError(describe(error, `SSH 连接失败（${target}）`));
+            /*
+             * `on` 而不是 `once`（D145）：**同一次建连失败**里 ssh2 会 emit 不止一个 `error`——
+             * socket 层报一次，client 层的「握手完成前关闭」再报一次。`once` 会在第一个 error 之后
+             * 把监听摘掉，第二个就成了「没有监听者的 `error` 事件」，Node 按约定**直接抛成 uncaught
+             * exception**：于是「目标不可达」这条最平常的路径会把整个进程带崩（本机实测：`pnpm test`
+             * 22 条断言全过、退出码却是 1）。监听器常驻即可——`settleError` 自己按 `settled` 幂等，
+             * 重复进来是 no-op（后到的那个 error 本来也没什么新信息可报）。
+             */
+            client.on('error', (error) => {
+                settleError(describe(error, `SSH 连接失败（${targetWithJump(spec)}）`));
             });
-            client.once('close', () => {
+            // 同理常驻：重复的 close 是 no-op（条目已摘、跳板机与代理命令已收）
+            client.on('close', () => {
+                // 先取下代理命令的失败事实再收尾：closeTransport() 会把 entry.proxy 清掉，
+                // 那时再取就永远是空串了（这正是「错误文案里少了最有用的那一句」的经典成因）
+                const proxySuffix = proxyFailureSuffix(entry.proxy);
                 this.dropConn(key, client);
+                // 目标这条（无论握手期还是就绪后）断了：跳板机 / 代理命令也要一起收，
+                // 否则前者带着 keepalive 一直挂着、后者变成没人管的常驻进程
+                closeTransport();
                 if (!settled)
-                    settleError(new Error(`SSH 连接失败（${target}）：连接在握手完成前关闭`));
+                    settleError(new Error(`SSH 连接失败（${targetWithJump(spec)}）：连接在握手完成前关闭${proxySuffix}`));
             });
             try {
                 client.connect(connectConfig);