feat: add structured ssh passthrough helpers
This commit is contained in:
Codex
+26
-3
@@ -15,6 +15,7 @@ UniDesk 的统一 CLI 入口是根目录 `scripts/cli.ts`，运行方式固定
|
||||
- `server rebuild <backend-core|frontend|provider-gateway|todo-note>` 创建异步 job，先构建目标服务镜像，构建成功后只按 Compose project/service label 移除该服务旧容器，再用 `--no-deps` 启动目标服务；该命令用于替代手工删除容器的兜底流程，其中 `todo-note` 只重建主 server 承载的 Todo Note 后端，不会重建或删除 database 命名卷。
|
||||
- `ssh <providerId> [ssh-like args...]` 通过 backend-core 内网 WebSocket broker 和 provider-gateway 的 Host SSH / WSL SSH 维护桥连接目标节点；无后续参数时进入远端登录 shell，有后续参数时按 ssh 远端命令体验执行并返回远端 exit code。
|
||||
- `ssh <providerId> apply-patch [tool args...] < patch.diff` 直接调用远端注入的 `apply_patch` 工具，并把本地 stdin 中的标准 `*** Begin Patch` / `*** End Patch` patch 流透传给目标节点。
|
||||
- `ssh <providerId> py [script-args...] < script.py` 把本地 stdin 落到远端临时 `.py` 文件后再以 `python3 -u` 执行并自动清理，避免再手写 `'python3 -'`、heredoc 或多层引号；`script-args` 会按 argv 安全透传给远端脚本。
|
||||
- `microservice list/status/health/proxy` 通过 backend-core 内网 API 管理挂载在计算节点 Docker 中的 microservice；`health` 和 `proxy` 会走真实 backend-core -> provider-gateway -> 节点本机后端链路，`proxy` 对超大 body 默认输出有界预览，规则见 `docs/reference/microservices.md`。
|
||||
- `job list` 与 `job status` 查询 `.state/jobs/` 文件系统状态，是异步命令的可观测入口。
|
||||
- `debug health`、`debug dispatch` 与 `debug task` 走真实内部 core、WebSocket、数据库、provider、系统指标、Docker 状态和 Host SSH 维护桥流程，只用于开发调试，不写入 `TEST.md` 的正式验收步骤。
|
||||
@@ -46,7 +47,7 @@ core 只允许声明了 `host.ssh` capability 的 provider 使用 `ssh` 透传
|
||||
|
||||
本地 broker 默认等待 provider SSH 会话打开 60000ms，以便在目标节点同时有较多 microservice.http 任务时仍能建立维护会话；需要诊断慢连接时可用 `UNIDESK_SSH_OPEN_TIMEOUT_MS=<ms>` 临时调大，但最小有效值固定为 15000ms，避免把真实离线误判为长时间阻塞。
|
||||
|
||||
`ssh <providerId>` 会在远端会话启动时注入 `/tmp/unidesk-ssh-tools/apply_patch`，并把该目录加入远端 `PATH`。该工具接受标准 `*** Begin Patch` / `*** End Patch` patch 格式，便于通过 SSH 透传编辑远端仓库文件；目标节点需要具备 `python3` 和 `base64`。注入工具只写 `/tmp/unidesk-ssh-tools`，不修改目标仓库，交互式 shell 和远端命令都可以直接调用 `apply_patch`。
|
||||
`ssh <providerId>` 会在远端会话启动时注入 `/tmp/unidesk-ssh-tools/apply_patch` 和 `/tmp/unidesk-ssh-tools/glob`，并把该目录加入远端 `PATH`。`apply_patch` 接受标准 `*** Begin Patch` / `*** End Patch` patch 格式，便于通过 SSH 透传编辑远端仓库文件；`glob` 在远端用 Python 执行路径匹配，避免依赖 shell glob 展开。目标节点需要具备 `python3` 和 `base64`。注入工具只写 `/tmp/unidesk-ssh-tools`，不修改目标仓库，交互式 shell 和远端命令都可以直接调用这些工具。
|
||||
|
||||
如果只是远端打小补丁，不需要再手写 `ssh D601 'apply_patch' < patch.diff` 这种命令拼接；正式入口是 `bun scripts/cli.ts ssh D601 apply-patch < patch.diff`。`apply-patch` 与 `patch` 等价，附加参数会原样透传给远端 `apply_patch`，例如 `bun scripts/cli.ts ssh D601 apply-patch --help`。标准单命令用法如下，不需要先创建本地 patch 临时文件：
|
||||
|
||||
@@ -61,13 +62,35 @@ bun scripts/cli.ts ssh D601 apply-patch <<'PATCH'
|
||||
PATCH
|
||||
```
|
||||
|
||||
通过 `ssh <providerId>` 执行多行脚本时，脚本内容必须从本地 stdin 直接喂给远端解释器，例如 `bun scripts/cli.ts ssh D601 'python3 -' < script.py` 或 `printf ... | (bun scripts/cli.ts ssh D601 'bash -s')` 这种单层 stdin 传输。不要在远端命令字符串里再嵌套 heredoc、复杂引号或 `ssh 'python3 - <<EOF ...'` 形态；多层 shell 解析容易把 stdin 绑定到错误进程，结果会打开远端交互解释器并留下悬挂的 broker/SSH 会话。长脚本需要复用时，优先通过 stdin 写入目标节点的临时脚本，再在同一个远端命令中显式执行并清理。
|
||||
如果只是想远端执行 Python 脚本，不要再手写 `bun scripts/cli.ts ssh D601 'python3 -' < script.py`。正式入口是 `bun scripts/cli.ts ssh D601 py < script.py`；CLI 会先把本地 stdin 写入远端临时 `.py` 文件，再以无缓冲模式执行并自动清理，同时对额外脚本参数逐个做 shell quoting，避免字符串转义问题。典型用法：
|
||||
|
||||
```bash
|
||||
printf 'import sys\nprint(sys.argv)\n' | bun scripts/cli.ts ssh D601 py foo '--bar=baz'
|
||||
```
|
||||
|
||||
`ssh <providerId> py` 的附加参数是脚本参数，不是 Python 解释器参数；如需 `-m`、`-X` 或多条 shell 命令，仍使用原始远端命令入口。为了保证 CLI 输出及时可见且不被 `ssh -tt` 误触发交互 REPL，helper 固定采用“临时文件 + `python3 -u`”模式。
|
||||
|
||||
`ssh <providerId> find` 是常用远端搜索的结构化入口，避免在 Host SSH / WSL SSH 透传里手写 `find \( ... \)`、`*`、管道和多层引号。它会把路径、谓词和 pattern 作为 argv 安全拼接，并支持重复 `--name`、`--iname`、`--path` 或 `--ipath`，重复 pattern 默认按 OR 组合。稳定参数包括 `--max-depth`/`-maxdepth`、`--min-depth`/`-mindepth`、`--type`/`-type`、`--contains`、`--icontains`、`--name`/`-name`、`--iname`/`-iname`、`--path`/`-path`、`--ipath`/`-ipath`、`--mtime`/`-mtime`、`--mmin`/`-mmin`、`--size`/`-size`、`--sort` 和 `--limit N`。典型用法：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts ssh D601 find /home/ubuntu --max-depth 4 --type d --icontains pika --limit 50 --sort
|
||||
```
|
||||
|
||||
`ssh <providerId> glob` 是远端 glob 匹配入口，支持 `--root DIR`、`--pattern PATTERN`、`--contains TEXT`、`--icontains TEXT`、`--type any|f|d`、`--limit N`、`--sort` 和 `--absolute`。`--contains` 与 `--icontains` 可避免在本地 shell 中输入 `*`；若显式使用 `--pattern '**/*.ts'` 这类 pattern，仍应按本地 shell 规则加引号，防止参数到达 CLI 前已被本地 shell 展开。典型用法：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts ssh D601 glob --root /home/ubuntu/pikapython --pattern '**/*-test.cpp' --limit 20 --sort
|
||||
```
|
||||
|
||||
`ssh <providerId> argv <command> [args...]` 是通用 argv 安全拼接入口；`exec` 是同义入口。它适合不需要 shell 管道的常用命令。`find`、`glob` 和 `apply-patch` 有专用入口；`rg`、`grep`、`sed`、`nl`、`stat`、`du`、`ls`、`cat`、`head`、`tail`、`wc` 和 `pwd` 可以直接作为 `ssh` 子命令使用，CLI 会对每个 argv token 做 shell quoting。需要管道、重定向、变量展开或多条命令时仍使用旧的自由远端命令入口，并把整段远端 shell 脚本作为一个本地参数传入。
|
||||
|
||||
通过 `ssh <providerId>` 执行多行脚本时，优先使用结构化 helper，例如 `bun scripts/cli.ts ssh D601 py < script.py` 或 `printf ... | (bun scripts/cli.ts ssh D601 'bash -s')` 这种单层 stdin 传输。不要在远端命令字符串里再嵌套 heredoc、复杂引号或 `ssh 'python3 - <<EOF ...'` 形态；多层 shell 解析容易把 stdin 绑定到错误进程，结果会打开远端交互解释器并留下悬挂的 broker/SSH 会话。长脚本需要复用时，优先通过 stdin 写入目标节点的临时脚本，再在同一个远端命令中显式执行并清理。
|
||||
|
||||
## Remote Main Server Passthrough
|
||||
|
||||
`--main-server-ip` 是一个全局前缀，必须放在需要透传的命令同一次调用中，例如 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug health`。默认传输是公网 frontend：本地 CLI 读取本仓库 `config.json` 中的 frontend 登录账号密码，登录 `http://<ip>:<frontendPort>/` 获取 HttpOnly session cookie，然后通过 frontend 的 `/api/*` 同源代理访问 backend-core 内网 API；因此计算节点只需要能访问公网 frontend，不需要主 server SSH key，也不需要打开 backend-core REST API 或 PostgreSQL 端口。
|
||||
|
||||
默认 frontend 传输支持 `debug health`、`debug dispatch`、`debug task`、`microservice list/status/health/proxy` 和 `ssh <PROVIDER_ID> <remote-command>`。其中 `ssh` 的 remote frontend 传输使用 `host.ssh` dispatch 执行有界远端命令，适合 `ssh D601 hostname` 这类自测；交互式登录 shell 仍应在主 server 本机 CLI 使用，或显式切换到旧 SSH 传输后在主 server 上执行。若确实需要旧行为，可使用 `--main-server-key <key>` 或 `--main-server-transport ssh`，这时 CLI 会通过 SSH 登录主 server 的 `--main-server-root` 目录执行同一个 `bun scripts/cli.ts <command>`。
|
||||
默认 frontend 传输支持 `debug health`、`debug dispatch`、`debug task`、`microservice list/status/health/proxy` 和 `ssh <PROVIDER_ID> <remote-command>`。其中 `ssh` 的 remote frontend 传输使用 `host.ssh` dispatch 执行有界远端命令，适合 `ssh D601 hostname` 这类自测；交互式登录 shell 仍应在主 server 本机 CLI 使用，或显式切换到旧 SSH 传输后在主 server 上执行。frontend 远程透传不会流式转发本地 stdin，因此 `ssh py < script.py`、`ssh apply-patch < patch.diff` 这类 stdin-backed helper 必须在主 server 本机运行，或显式切换到 `--main-server-transport ssh`。若确实需要旧行为，可使用 `--main-server-key <key>` 或 `--main-server-transport ssh`，这时 CLI 会通过 SSH 登录主 server 的 `--main-server-root` 目录执行同一个 `bun scripts/cli.ts <command>`。
|
||||
|
||||
计算节点可以用该入口测试自身的远程升级闭环，而不需要在计算节点公开 core REST API 或 database。标准顺序是：先运行 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug health` 确认主 server 看到当前 Provider 在线，且该 Provider labels 中 `unideskCapabilities` 包含 `host.ssh`、`hostSshConfigured=true`、`hostSshKeyPresent=true`；再运行 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> provider.upgrade --mode schedule --wait-ms 15000` 触发真实 `provider.upgrade`；随后再次运行 `debug health` 确认节点重新上线；最后运行 `bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> host.ssh --wait-ms 15000` 和 `bun scripts/cli.ts --main-server-ip 74.48.78.17 ssh <PROVIDER_ID> hostname` 验证 SSH 透传能力。provider-gateway 新部署或升级后没有完成这组 remote CLI 自测，不能视为交付完成。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user