使用 Workbench CLI 管理 ECS 实例

前提条件

• 已在本机安装 Workbench CLI 并完成凭证与最小 RAM 权限配置。具体操作，请参见 安装并配置 Workbench CLI 凭证。

• 目标 ECS 实例为 Linux 实例，状态为 运行中，且已安装并正常运行 云助手 Agent。

• 本机能访问 *.aliyuncs.com 及 Workbench 后端 WebSocket 端点；upload / download 命令还需实例能访问对应地域的 OSS 内网端点。

全局参数

以下 3 个全局参数适用于所有 workbench 子命令。

地域自动推断的顺序为：实例 ID 前缀映射 → 守护进程内活跃会话查找 → 报错要求手动指定 --region。首次使用某个实例时，建议先执行 workbench list ecs -r <region> 确认实例 ID。

查询实例列表（workbench list ecs）

用于按地域、状态、标签等条件查询 ECS 实例，方便快速定位目标实例 ID。workbench list 默认等价于 workbench list ecs。常用示例：

# 查询指定地域的所有实例
workbench list ecs -r cn-hangzhou

# 仅查询运行中的实例
workbench list ecs -r cn-hangzhou --status Running

# 按标签过滤（多个 --tag 之间为 AND 语义）
workbench list ecs -r cn-hangzhou --tag env=prod --tag app=web

# 按规格 / 名称 / VPC 等条件过滤
workbench list ecs -r cn-hangzhou --instance-type ecs.g7.large --instance-name "web-*"

# 输出为 JSON 供脚本或 AI Agent 消费
workbench list ecs -r cn-hangzhou --output json

参数说明：

--output json 的返回结构如下：

{
  "instances": [
    {
      "instance_id": "i-bp1xxxxx",
      "instance_name": "web-prod-01",
      "instance_type": "ecs.g7.large",
      "region_id": "cn-hangzhou",
      "status": "Running",
      "private_ip": "172.16.0.10",
      "public_ip": "",
      "os_type": "linux",
      "image_id": "aliyun_3_x64_20G_alibase_20230727.vhd",
      "tags": {"env": "prod"}
    }
  ]
}

交互式连接（workbench connect）

workbench connect 用于打开交互式 PTY 会话，是 Workbench CLI 的核心命令。常用示例：

# 默认无密码认证（Workbench 免密登录）
workbench connect -i i-bp1a2b3c4d5e6f

# 密码认证（进入后交互式输入密码，输入不回显）
workbench connect -i i-bp1a2b3c4d5e6f --auth-type password

# 密钥认证（进入后交互式输入密钥文件路径，如 ~/.ssh/id_rsa）
workbench connect -i i-bp1a2b3c4d5e6f --auth-type certificate

# 指定登录用户与端口
workbench connect -i i-bp1a2b3c4d5e6f -u admin -p 2222

# 强制新建会话（不复用已有会话）
workbench connect -i i-bp1a2b3c4d5e6f --new

参数说明：

Agent> 查看当前CPU占用最高的进程
  ┌─ 执行命令 ──────────
  │ ps aux --sort=-%cpu | head -10
  └─────────────────────
  等待确认 (Y/n): y
  [已执行]
  ... (Agent 继续分析并给出结论)

远程命令执行（workbench exec）

workbench exec 用于在实例上执行一条命令并返回结果。相比于 connect 的持久 shell，exec 每次调用在独立环境中执行；同一实例的多次调用复用底层连接通道，无需重复建连。常用示例：

# 执行一条命令
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h"

# 组合命令：cd + 环境变量 + 执行
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/app && ./deploy.sh"

# 设置超时
workbench exec -i i-bp1a2b3c4d5e6f -c "sleep 30" --timeout 10

# JSON 输出用于脚本或 AI Agent 消费
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json

参数说明：

--output json 的返回结构如下：

{
  "output": "Filesystem ...\n",
  "stderr": "",
  "exit_code": 0
}

其中 output 为命令的标准输出、stderr 为标准错误、exit_code 为远程命令的退出码（整型）。

文件传输（workbench upload / download）

在没有公网 IP 或 SCP 通道的情况下，通过 workbench upload / workbench download 传输文件。上传过程会显示实时进度条。

上传示例：

workbench upload ./app.jar /opt/app/app.jar -i i-bp1a2b3c4d5e6f

下载示例：

# 下载到当前目录
workbench download /var/log/app.log ./ -i i-bp1a2b3c4d5e6f

# 下载并重命名
workbench download /var/log/app.log ./local-copy.log -i i-bp1a2b3c4d5e6f

参数说明：

会话管理（workbench session）

常用命令：

# 查看所有活跃会话
workbench session list
workbench session list --output json

# 关闭指定会话
workbench session close <session-id>

# 关闭所有会话
workbench session close --all

会话状态转换：

• OPEN：会话建立，可正常读写。

• RECONNECTING：底层 WebSocket 断开后正在重连。

• BROKEN：重连失败，会话不可用。

• CLOSED：会话已关闭（用户主动关闭、超时或达到 TTL 上限）。

同一实例的多次 connect、exec、upload、download 共享同一会话，由守护进程透明处理，用户无需关心会话 ID。同一会话同一时刻仅允许一个终端（TTY）接入；如已有终端接入，可用 --new 新建会话，或先关闭已有连接。

守护进程管理（workbench daemon）

Workbench CLI 依赖一个用户态后台守护进程持有 WebSocket 连接并多路复用会话。守护进程的生命周期完全自动，通常无需手动管理。

# 查看守护进程状态
workbench daemon status

# 停止守护进程（会关闭所有会话）
workbench daemon stop

• 自动启动：首次执行任意 workbench 命令时自动拉起。

• 自动退出：最后一个会话关闭 60 秒后自动退出。

• 单实例：每个操作系统用户下仅允许一个守护进程实例（通过 PID 文件锁强制）。

• IPC 通道：CLI 与守护进程通过 ~/.workbench/run/daemon.sock（Unix socket）通信，协议为 JSON-RPC。

典型使用场景

workbench upload ./app-2.0.tar.gz /opt/deploy/ -i i-bp1a2b3c4d5e6f
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/deploy && tar xzf app-2.0.tar.gz && ./deploy.sh"
workbench exec -i i-bp1a2b3c4d5e6f -c "curl -s http://localhost:8080/health"

workbench exec -i i-bp1a2b3c4d5e6f -c "df -h && free -m" --output json | jq '.output'
workbench exec -i i-bp1a2b3c4d5e6f -c "systemctl status nginx" --output json | jq '.exit_code'

workbench connect -i i-bp1a2b3c4d5e6f
# 会话内运行 tail -f 或长任务
# 然后输入 /detach 分离

# 稍后重新接入原会话
workbench connect -i i-bp1a2b3c4d5e6f

退出码

workbench exec 会透传远程命令的退出码：远程命令返回什么退出码，CLI 就以相同退出码退出（行为与 SSH 一致）。因此脚本可直接根据 workbench exec 的退出码判断远程命令是否成功。

例如以下命令在实例上执行 exit 42，CLI 也以 42 退出：

workbench exec -i i-bp1a2b3c4d5e6f -c "exit 42"
echo $?   # 输出 42

当命令因参数、认证、网络、实例不存在等原因失败时，配合 --output json 会输出错误详情，格式如下：

{
  "code": 1,
  "message": "session resolve: login instance: ... InvalidParameter.InstanceId ..."
}

其中 code 为非 0 的错误标识，message 为可读的错误描述（通常包含底层 API 的错误码与 RequestId），可据此定位问题。

故障排查

常见现象及首要排查动作：

调试命令：

# 查看守护进程状态
workbench daemon status

# JSON 错误输出便于脚本解析
workbench exec -i i-bp1a2b3c4d5e6f -c "echo test" --output json

守护进程日志保存在 ~/.workbench/log/daemon.log。

相关文档

• 通过 Workbench CLI 连接实例：父节点，包含工具定位与快速开始。

• 安装并配置 Workbench CLI 凭证：CLI 安装与凭证/权限配置。

• 在 AI Agent 中使用 Workbench CLI 操作 ECS 实例：在悟空 / opencode 中让 Agent 调用 workbench 命令。

• 安装云助手 Agent：Workbench CLI 依赖云助手 Agent。