alibabacloud-workbench-cli

Workbench CLI 专家

帮助用户通过 workbench 命令行工具操作阿里云 ECS 实例，尤其是那些没有公网 IP 地址的实例。Agent 工作流的核心功能：毫秒级远程命令执行（exec）、最大 1GB 的文件传输（upload/download）以及端口转发。本技能涵盖：安装 → 配置凭证 → 执行命令/传输文件/端口转发 → 管理会话 → 排查错误。

说明

1. 安装 Workbench CLI

安装前检查：

workbench version     # Should print version, commit, build date

Linux / macOS：

curl -fsSL https://workbench-cli.oss-cn-hangzhou.aliyuncs.com/install.sh | bash

Windows（PowerShell）：

irm https://workbench-cli.oss-cn-hangzhou.aliyuncs.com/install.ps1 | iex

升级：

workbench upgrade                        # Upgrade to latest
workbench upgrade --version 0.2.0        # Upgrade to specific version

2. 配置凭证

凭证存储在 ~/.workbench/config.json 中，权限为 0600。作为 Agent，请直接写入此文件，而不要使用交互式 workbench config 命令。

# Create config directory
mkdir -p ~/.workbench

# Write config file (example: AK mode)
cat > ~/.workbench/config.json << 'EOF'
{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "<AccessKeyID>",
      "access_key_secret": "<AccessKeySecret>"
    }
  }
}
EOF

# Set secure permissions
chmod 600 ~/.workbench/config.json

按模式划分的配置文件架构：

AK 模式：

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "LTAI...",
      "access_key_secret": "..."
    }
  }
}

RamRoleArn 模式（自动刷新 STS 令牌）：

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "RamRoleArn",
      "access_key_id": "LTAI...",
      "access_key_secret": "...",
      "ram_role_arn": "acs:ram::123456789:role/WorkbenchRole",
      "role_session_name": "workbench-session"
    }
  }
}

CredentialsURI 模式（HTTP 端点返回凭证）：

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "CredentialsURI",
      "credentials_uri": "http://localhost:8080/credentials"
    }
  }
}

模式	使用场景
AK（默认）	开发、长期有效的凭证
StsToken	临时安全凭证（AccessKey + STS Token）
RamRoleArn	生产环境、跨账号场景，通过 STS 角色扮演实现最小权限（自动刷新令牌）
CredentialsCmd	零信任 / Vault 集成 — 外部命令输出凭证 JSON
CredentialsURI	元数据服务 / sidecar — HTTP 端点返回凭证 JSON

配置档案管理（非交互式）：

workbench config list                     # List all profiles (* marks active)
workbench config switch --profile prod    # Switch active profile
workbench config get                      # Show current profile details (JSON)
workbench config get --profile prod       # Show specific profile details
workbench config delete --profile old     # Delete a profile (cannot delete active)

3. 命令参考

workbench
├── exec             # Execute remote command (non-interactive, millisecond-level)
├── upload           # Upload local file to instance (up to 1GB, via OSS relay)
├── download         # Download file from instance (up to 1GB, via OSS relay)
├── list             # List ECS instances
├── session          # Session management (list / close)
├── daemon           # Daemon lifecycle (start / status / stop)
├── config           # Credential configuration & profile management
│   ├── set          # Set a single config field
│   ├── list         # List all profiles
│   ├── switch       # Switch active profile
│   ├── get          # Show profile details
│   └── delete       # Delete a profile
├── upgrade          # Self-update
└── version          # Print version info

全局标志：

标志	用途	默认值
--output / -o	输出格式：`text	json`
--region / -r	阿里云地域（例如 cn-hangzhou）	根据实例 ID 前缀自动推断
--profile / -P	使用指定配置档案（覆盖当前活动配置档案）	当前活动配置档案

4. 列出实例

workbench list ecs --region cn-hangzhou
workbench list ecs --region cn-hangzhou --status Running
workbench list ecs --region cn-hangzhou --tag env=prod --tag team=infra
workbench list ecs --region cn-hangzhou --instance-type ecs.g7.large
workbench list ecs --region cn-hangzhou --instance-name my-instance
workbench list ecs --region cn-hangzhou --image-id ubuntu_22_04_x64_20G_alibase_20230907.vhd
workbench list ecs --region cn-hangzhou --output json

list ecs 必须指定 --region。筛选条件：--status（Running|Stopped|Starting|Stopping）、--tag（key=value 或 key，可重复，采用 AND 逻辑）、--instance-type（例如 ecs.g7.large）、--instance-name（支持通配符 *）、--image-id、--vpc-id、--zone-id、--vswitch-id、--private-ip（逗号分隔）、--limit（1-100，默认值为 50）、--next-token（分页）。

JSON 输出架构：

[{
  "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": "ubuntu_22_04_x64_20G_alibase_20230907.vhd",
  "tags": {"env": "prod"}
}]

5. 远程命令执行

内置安全机制：此 CLI 是非交互式执行工具，不提供持久化 Shell。每次调用彼此隔离且无状态，可防止因 Shell 会话持续存在而意外造成连锁损害。

Agent 执行前检查要求：执行破坏性命令前（例如 rm -rf、shutdown、reboot、mkfs、dd、停止/重启服务，或任何会删除数据或使系统停止运行的命令），Agent 必须先向用户确认，并说明计划执行的操作、目标实例及潜在影响。未经用户明确批准，不得执行破坏性命令。

workbench exec --instance-id i-bp1xxxxx --command "df -h"
workbench exec --instance-id i-bp1xxxxx --command "sleep 30" --timeout 10
workbench exec --instance-id i-bp1xxxxx --command "df -h" --output json

标志	必需	描述	默认值
--instance-id / -i	是	ECS 实例 ID	—
--command / -c	是	要执行的命令	—
--timeout	否	超时时间（秒）	30

重要：每次 exec 调用都在独立的 Shell 上下文中运行。状态（cd、export）不会在调用之间保留。需要共享上下文的命令应在单次调用中使用 && 或 ; 串联。

JSON 输出架构：

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

6. 文件传输

内置安全保护：upload 命令内置覆盖保护。如果远程目标文件已存在，CLI 会在覆盖前提示确认：

Remote file "/root/id.txt" already exists (728 B, modified Jul 27 10:42). Overwrite? [y/N]

默认回答为 否 — 如果用户没有明确确认，上传将会中止。这样可以防止意外覆盖现有远程文件。

Agent 预检查要求：在无法进行交互式确认的自动化/Agent 工作流中使用 upload 时，Agent 必须先检查目标文件在远程实例上是否存在（例如，通过 workbench exec --command "ls -la <path>"），并在文件将被覆盖时告知用户。

workbench upload ./app.jar /opt/app/app.jar --instance-id i-bp1xxxxx
workbench download /var/log/app.log ./ --instance-id i-bp1xxxxx
workbench download /var/log/app.log /tmp/local-copy.log --instance-id i-bp1xxxxx

传输通过 OSS 中转 — 对用户透明，无需配置 OSS。download 的第二个参数（local-path）为可选项，默认使用当前目录。

7. 会话管理

workbench session list
workbench session list --output json
workbench session close <session-id>
workbench session close --all

会话生命周期：OPEN → RECONNECTING → BROKEN → CLOSED。空闲超时 30min 后自动变为 CLOSED。同一实例上的多项操作共享一个会话（透明多路复用）。

8. 守护进程管理

workbench daemon start      # Manual start (usually not needed)
workbench daemon status
workbench daemon stop       # Closes all sessions

• 自动启动：首次调用 CLI 时启动。
• 自动退出：最后一个会话关闭 60 秒后退出。
• 单例：每个 OS 用户运行一个（PID 文件锁）。
• IPC：通过 Unix socket 进行 JSON-RPC 通信（~/.workbench/run/daemon.sock）。

9. 区域推断

CLI 会根据实例 ID 的 3 字符前缀自动推断区域（覆盖 290+ 个区域）。如果推断失败，则必须指定 --region。对于 list 命令，始终必须指定 --region。

退出码

代码	常量	触发条件
0	ExitSuccess	执行成功
1	ExitGeneral	未分类的运行时错误（包括实例未找到、API 错误等）
2	ExitArgument	缺少、格式错误或无效的标志值
3	ExitSessionNotFound	会话 ID 无效或已过期
4	ExitAuth	身份验证或授权失败
5	ExitNetwork	网络超时、WebSocket 异常
6	ExitDaemonUnreach	本地守护进程未运行或 socket 无效
7	ExitSessionBusy	会话已被另一个 TTY 挂载
N	(仅限 exec)	exec 会透明地传递远程命令的退出码

错误 JSON 输出（在 --output json 失败时）：

{
  "code": 1,
  "message": "InvalidParameter.InstanceId: the specified instance does not exist"
}

RAM 权限

所需的最低 RAM 策略：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs-workbench:LoginECSInstance",
        "ecs-workbench:ChatMessages"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:DescribeInstances",
        "ecs:DescribeCloudAssistantStatus",
        "ecs:StartTerminalSession"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "ram:CreateServiceLinkedRole",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "ram:ServiceName": "workbench.ecs.aliyuncs.com"
        }
      }
    }
  ]
}

限制到特定实例：将每条语句中的 "Resource": "*" 替换为相应格式：

• ecs-workbench:LoginECSInstance ：acs:ecs:<region>:<account-id>:ecs/<instance-id>
• ecs 操作：acs:ecs:<region>:<account-id>:instance/<instance-id>

故障排除

错误消息模式	退出码	首要操作
InvalidAccessKeyId / 身份验证错误	4	检查 ~/.workbench/config.json 中的 AK/SK。重新运行 workbench config。
profile not found	1	使用 workbench config list 检查 profile 名称。
not found in <region> / 实例未找到	1	验证实例 ID 和区域。使用 workbench list --region <region> 确认。
网络超时 / WebSocket 错误	5	检查到 *.aliyuncs.com 的网络连接。验证安全组规则。
会话繁忙 / 挂载错误	7	另一个终端已挂载。先关闭该终端，或使用 workbench session close <id>。
cannot start daemon / socket 错误	6	运行 workbench daemon status。如果守护进程已停止，任何命令都会自动重启它。
RAM 权限被拒绝	4	将 ## RAM Permissions 中的 RAM 策略附加到用户或角色。
insecure permissions	2	运行 chmod 600 ~/.workbench/config.json。
STS 令牌已过期	4	如果使用 RamRoleArn 模式，CLI 会自动刷新。如果使用静态 STS，请更新令牌。