mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: isolate trans ssh bootstrap

Browse Source
This commit is contained in:
Codex
2026-06-19 15:43:54 +00:00
parent 1c371c7431
commit f9e11ff93e
8 changed files with 1152 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/cli.md
+4 -4
View File
@@ -1,8 +1,8 @@
# UniDesk CLI Reference
UniDesk 的统一 CLI 实现入口是根目录 `scripts/cli.ts`，运行方式固定为 `bun scripts/cli.ts <command>`；普通根 CLI 子命令仍使用该入口。`trans <route> ...` 是 `bun scripts/cli.ts ssh <route> ...` 的短 alias，只用于 SSH/WSL/k3s 透传，用于避免远端操作里反复输出过长前缀；长期参考文档、AGENTS 索引、CLI help 和人工远端操作示例都必须优先写 `trans ...`，不得再把 `bun scripts/cli.ts ssh ...` 作为默认透传入口。CLI 默认输出 JSON，所有成功和失败路径都必须向 stdout 写出结构化对象，避免无输出造成状态不可观测。
UniDesk 的统一 CLI 实现入口是根目录 `scripts/cli.ts`，运行方式固定为 `bun scripts/cli.ts <command>`；普通根 CLI 子命令仍使用该入口。`trans <route> ...` 是 SSH/WSL/k3s 透传专用入口，wrapper 委托轻量 `scripts/ssh-cli.ts` 启动链路，避免被无关根 CLI 子命令模块的解析或语法错误拖垮；长期参考文档、AGENTS 索引、CLI help 和人工远端操作示例都必须优先写 `trans ...`，不得再把 `bun scripts/cli.ts ssh ...` 作为默认透传入口。CLI 默认输出 JSON，所有成功和失败路径都必须向 stdout 写出结构化对象，避免无输出造成状态不可观测。
主 server 必须在 PATH 上提供 `/root/.local/bin/trans` 可执行 wrapper，内容委托 repo 内版本化 `scripts/trans` 并执行 `bun scripts/cli.ts ssh "$@"`；交互 shell 可额外提供 alias，但非交互 Codex `exec` 和脚本不能依赖 alias 展开。
主 server 必须在 PATH 上提供 `/root/.local/bin/trans` 可执行 wrapper，内容委托 repo 内版本化 `scripts/trans` 并执行 `bun scripts/ssh-cli.ts ssh "$@"`；交互 shell 可额外提供 alias，但非交互 Codex `exec` 和脚本不能依赖 alias 展开。
`trans` wrapper 是 SSH/WSL/k3s 透传的唯一默认入口：人工/Codex 远端操作、长期参考文档、AGENTS 索引、CLI help、非交互脚本和非交互 `exec` 都必须直接调主 server PATH 上的 `/root/.local/bin/trans`；禁止把 `bun scripts/cli.ts ssh ...`、`bun scripts/cli.ts trans ...` 或任何带 `bun scripts/cli.ts` 前缀的透传写法作为默认入口。`bun scripts/cli.ts help`、`config`、`server`、`provider`、`microservice` 等普通根 CLI 子命令不受这条限制，仍使用 `bun scripts/cli.ts <command>`，避免透传命令和根子命令在调用前缀上互相混淆。
@@ -233,11 +233,11 @@ GitHub issue/PR 正文局部修补必须优先使用 `trans gh:/owner/repo/issue
## SSH Command
`trans <providerId> [ssh-like args...]` 是面向人的终端透传入口，不包装 JSON 输出，底层等价于 `bun scripts/cli.ts ssh <providerId> ...`。CLI 会在宿主机启动 `docker exec -i unidesk-backend-core backend-core --ssh-broker ...`，broker 只连接 backend-core 的 Docker 内网 `/ws/ssh`；core 使用 provider WebSocket 下发 open/dispatch 控制消息，但 stdin/stdout/stderr 数据面必须走 provider 主动连接 main server 的 `host.ssh.tcp-pool` TCP warm pool，provider-gateway 最终执行维护用 SSH 连接宿主或 WSL sshd。TTY 策略固定为交互登录 shell 使用 `ssh -tt`，带远端命令的会话使用 `ssh -T`；`apply-patch`、脚本 stdin、`py` 和旧 `apply-patch-v1` fallback 这类命令模式不得被伪终端回显或注入控制字符。该入口不暴露 database，也不改变 frontend/dev frontend/provider ingress 之外的业务边界；provider data TCP port 是 provider 主动连入的数据面端口，不是计算节点入站要求。
`trans <providerId> [ssh-like args...]` 是面向人的终端透传入口，不包装 JSON 输出，默认由 `scripts/ssh-cli.ts` 只加载 SSH/route/远程前端转发相关模块。主 server 本地执行时会在宿主机启动 `docker exec -i unidesk-backend-core backend-core --ssh-broker ...`，broker 只连接 backend-core 的 Docker 内网 `/ws/ssh`；core 使用 provider WebSocket 下发 open/dispatch 控制消息，但 stdin/stdout/stderr 数据面必须走 provider 主动连接 main server 的 `host.ssh.tcp-pool` TCP warm pool，provider-gateway 最终执行维护用 SSH 连接宿主或 WSL sshd。TTY 策略固定为交互登录 shell 使用 `ssh -tt`，带远端命令的会话使用 `ssh -T`；`apply-patch`、脚本 stdin、`py` 和旧 `apply-patch-v1` fallback 这类命令模式不得被伪终端回显或注入控制字符。该入口不暴露 database，也不改变 frontend/dev frontend/provider ingress 之外的业务边界；provider data TCP port 是 provider 主动连入的数据面端口，不是计算节点入站要求。
`trans --help` 和 `trans <providerId> --help` 是本地 JSON 帮助命令，必须快速返回；不能把 `--help` 解析成 Provider ID，不能打开交互 shell，也不能等待 provider 会话。
主 server 固定提供 `trans` 缩写，等价于 `bun scripts/cli.ts ssh "$@"` 的受控 UniDesk SSH 透传入口。这里必须同时保留两层入口：交互式 shell 可额外配置 alias；Codex `exec`、脚本和其他非交互 shell 不会自动展开 alias，所以还必须有 `/root/.local/bin/trans` 可执行 wrapper，内容固定为委托 repo 内版本化脚本：
主 server 固定提供 `trans` 缩写，等价于 `bun scripts/ssh-cli.ts ssh "$@"` 的受控 UniDesk SSH 透传入口。这里必须同时保留两层入口：交互式 shell 可额外配置 alias；Codex `exec`、脚本和其他非交互 shell 不会自动展开 alias，所以还必须有 `/root/.local/bin/trans` 可执行 wrapper，内容固定为委托 repo 内版本化脚本：
```sh
#!/bin/sh