UniDesk CLI Reference

UniDesk 的统一 CLI 入口是根目录 scripts/cli.ts，运行方式固定为 bun scripts/cli.ts <command>。CLI 默认输出 JSON，所有成功和失败路径都必须向 stdout 写出结构化对象，避免无输出造成状态不可观测。

Command Model

help 输出命令索引，适合作为交互式入口。
config show 读取并校验根目录 config.json，不从环境变量、默认值或隐藏文件静默补配置。
check 执行配置校验、文件存在性检查、scripts/ TypeScript 检查、src/components/ TypeScript 检查和 Docker Compose 配置检查。
server start 创建异步 job，在后台执行 Docker 构建和启动；命令本身只负责返回 job id、日志路径和启动命令。
server stop 创建异步 job，在后台停止固定 Compose project 中的全部 UniDesk 服务。
server status 查询公开端口、内部端口、Compose 容器、core/frontend/provider/database 健康检查和访问 URL。
server logs 返回 logs/ 文件日志和 Docker 容器日志的尾部，默认限制输出大小，避免日志爆炸。
ssh <providerId> [ssh-like args...] 通过 backend-core 内网 WebSocket broker 和 provider-gateway 的 Host SSH / WSL SSH 维护桥连接目标节点；无后续参数时进入远端登录 shell，有后续参数时按 ssh 远端命令体验执行并返回远端 exit code。
job list 与 job status 查询 .state/jobs/ 文件系统状态，是异步命令的可观测入口。
debug health、debug dispatch 与 debug task 走真实内部 core、WebSocket、数据库、provider、系统指标、Docker 状态和 Host SSH 维护桥流程，只用于开发调试，不写入 TEST.md 的正式验收步骤。
e2e run 使用 publicHost 派生的公开 frontend/provider ingress URL，并通过 Docker 内网验证 core API、PostgreSQL、provider self-connection、系统指标曲线、Docker 状态快照、provider.upgrade 预检和 Playwright 前端页面，是交付前的自动化 E2E 门禁。

Async Job State

长时操作采用 Fire-and-Forget 模式：CLI 创建 .state/jobs/{jobId}.json，后台进程执行真实命令，并将 stdout、stderr 分别写入 .state/jobs/{jobId}.stdout.log 与 .state/jobs/{jobId}.stderr.log。调用者通过 bun scripts/cli.ts job status <jobId> 查询进度和尾部输出。

Output Contract

每条命令的最外层 JSON 包含 ok、command 和 data 或 error。失败时 CLI 设置非零退出码，但仍然输出 JSON 错误对象；错误对象应包含 name、message 和可用的 stack。

Debug Contract

debug 子命令必须复用真实模块与真实端点，禁止维护平行实现。debug health 会摘要展示 /api/nodes/system-status 和 /api/nodes/docker-status，避免输出完整快照造成信息爆炸。debug dispatch 会在 backend-core 容器内调用内部 /api/dispatch，core 再通过 WebSocket 将 docker.ps、provider.upgrade、host.ssh 或 echo 任务下发给 provider gateway，因此它可以验证核心调度闭环，同时不需要公开 core REST API。provider.upgrade 默认使用 mode: "plan" 预检；需要验证一键升级时必须显式加 --mode schedule，并通过 --wait-ms 或 debug task 确认任务进入 succeeded、result 中包含 updater 容器信息和 policy: "always-enabled"。host.ssh 默认使用 mode: "probe" 做短超时维护桥自检；需要执行明确命令时使用 --ssh-command 进入 mode: "exec"，并配合 --wait-ms 和 debug task 查看 stdout、stderr、exitCode 与 probeLine。

SSH Command

ssh <providerId> [ssh-like args...] 是面向人的终端透传入口，不包装 JSON 输出。CLI 会在宿主机启动一个 docker exec -i unidesk-backend-core bun -e ... broker，broker 只连接 backend-core 的 Docker 内网 /ws/ssh，core 再把 stdin/stdout/stderr 流量通过目标 provider 的既有 WebSocket 转发到 provider-gateway，provider-gateway 最终执行维护用 ssh -tt 连接宿主或 WSL sshd。该入口不新增 core 公网端口，不暴露 database，也不改变 frontend/provider ingress 之外的公网边界。

bun scripts/cli.ts ssh D518 应表现为登录 D518 WSL 的 shell；bun scripts/cli.ts ssh D518 hostname 应像 ssh D518 hostname 一样只输出远端命令结果并返回远端 exit code。Provider ID 前的目标选择由 UniDesk 节点清单决定，-p、-i、-l、-o 等传统 ssh 传输参数由 provider-gateway 部署配置统一管理，CLI 会兼容性消费这些参数但不会覆盖节点侧维护桥配置。

core 只允许声明了 host.ssh capability 的 provider 使用 ssh 透传或 host.ssh dispatch；旧 provider 不支持该能力时必须快速失败并输出错误，不能把未知命令误判成 echo 成功。

4.8 KiB Raw Blame History Unescape Escape