alibabacloud-workbench-cli 是什么？

面向单实例的Workbench命令行工具，支持单实例的毫秒级的远程命令执行、1GB 大文件传输、TCP 端口转发，支持四种认证方式，适合代码部署、日志查看、文件收发及实例运维管理。

alibabacloud-workbench-cli 怎么安装？

打开本页上方的「安装命令」标签页，复制命令到终端运行即可完成安装。

alibabacloud-workbench-cli 适合哪些场景？

主要用于「编程开发」等场景，适合需要面向单实例的Workbench命令行工具，支持单实例的毫秒级的远程命令执行、1GB 大文件传输、TCP 端口转发，支持四种认证方式，适合代码部署、日志查看、文件收发及实例运维管理。的任务。

alibabacloud-workbench-cli 收费吗？

本站收录的 Skill 安装包可免费获取使用；部分 Skill 依赖的第三方服务（如外部 API）可能需单独申请或订阅，以官方说明为准。

alibabacloud-workbench-cli：面向单实例的Workbench命令行工具，支持单实例的毫秒级的远程命令执行、1GB 大

Q: alibabacloud-workbench-cli 适合哪些场景？

主要用于「编程开发」等场景，适合需要 面向单实例的Workbench命令行工具，支持单实例的毫秒级的远程命令执行、1GB 大文件传输、TCP 端口转发，支持四种认证方式，适合代码部署、日志查看、文件收发及实例运维管理。 的任务。

Workbench CLI 专家

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

使用说明

1. 安装 Workbench CLI

预检查：

workbench version     # 应打印版本、commit、构建日期

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                        # 升级到最新版
workbench upgrade --version 0.2.0        # 升级到指定版本

2. 配置凭证

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

创建配置目录

mkdir -p ~/.workbench

写入配置文件（示例：AK 模式）

cat > ~/.workbench/config.json << 'EOF'

{

"current": "default",

"profiles": {

"default": {

"mode": "AK",

"access_key_id": "<AccessKeyID>",

"access_key_secret": "<AccessKeySecret>"

}

EOF

设置安全权限

chmod 600 ~/.workbench/config.json


**按模式的配置文件 schema：**

AK 模式：

{

"current": "default",

"profiles": {

"default": {

"mode": "AK",

"access_key_id": "LTAI...",

"access_key_secret": "..."

}


RamRoleArn 模式（自动刷新 STS token）：

{

"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 endpoint 返回凭证）：

{

"current": "default",

"profiles": {

"default": {

"mode": "CredentialsURI",

"credentials_uri": "http://localhost:8080/credentials"

}


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

**Profile 管理（非交互式）：**

workbench config list # 列出所有 profile（* 标记当前激活）

workbench config switch --profile prod # 切换激活 profile

workbench config get # 显示当前 profile 详情（JSON）

workbench config get --profile prod # 显示指定 profile 详情

workbench config delete --profile old # 删除 profile（不能删除激活中的）


### 3. 命令参考

workbench

├── exec # 执行远程命令（非交互式，毫秒级）

├── upload # 上传本地文件到实例（最大 1GB，经 OSS 中转）

├── download # 从实例下载文件（最大 1GB，经 OSS 中转）

├── list # 列出 ECS 实例

├── session # 会话管理（list / close）

├── daemon # 守护进程生命周期（start / status / stop）

├── config # 凭证配置与 profile 管理

│ ├── set # 设置单个配置字段

│ ├── list # 列出所有 profile

│ ├── switch # 切换激活 profile

│ ├── get # 显示 profile 详情

│ └── delete # 删除 profile

├── upgrade # 自更新

└── version # 打印版本信息


**全局 flag：**

| Flag | 用途 | 默认 |
| --- | --- | --- |
| `--output` / `-o` | 输出格式：`text|json` | `text` |
| `--region` / `-r` | 阿里云地域（如 `cn-hangzhou`） | 从实例 ID 前缀自动推断 |
| `--profile` / `-P` | 使用特定 profile（覆盖激活 profile） | 当前激活 profile |

### 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


`--region` 对 `list ecs` 是**必填**。筛选器：`--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 输出 schema：

[{

"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


| Flag | 必填 | 说明 | 默认 |
| --- | --- | --- | --- |
| `--instance-id` / `-i` | 是 | ECS 实例 ID | — |
| `--command` / `-c` | 是 | 要执行的命令 | — |
| `--timeout` | 否 | 超时秒数 | `30` |

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

JSON 输出 schema：

{

"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]


默认答案是 **No**——如果用户未明确确认，上传将中止。这防止意外覆盖现有远程文件。

**Agent 预检查要求**：在自动化/Agent 工作流中无法交互确认时，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。空闲超时 30 分钟 → 自动 CLOSED。对同一实例的多次操作共享一个会话（透明多路复用）。

### 8. 守护进程管理

workbench daemon start # 手动启动（通常不需要）

workbench daemon status

workbench daemon stop # 关闭所有会话


- **自动启动**：首次 CLI 调用时生成。
- **自动退出**：最后一个会话关闭后 60 秒。
- **单例**：每个操作系统用户一个（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`	缺失、格式错误或无效的 flag 值
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"
        }
      }
    }
  ]
}

限制到特定实例：把每个 statement 中的 "Resource": "*" 替换为相应格式：

ecs-workbench:LoginECSInstance：acs:ecs:<region>:<account-id>:ecs/<instance-id>
ecs actions：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` 的网络连通性。验证安全组规则。
会话忙 / attach 错误	7	另一终端已附加。先关闭它，或用 `workbench session close <id>`。
`cannot start daemon` / socket 错误	6	运行 `workbench daemon status`。如果已停止，任何命令都会自动重启它。
权限被拒（RAM）	4	把 `## RAM 权限` 中的 RAM 策略附加到用户或角色。
`insecure permissions`	2	运行 `chmod 600 ~/.workbench/config.json`。
STS token 过期	4	如果使用 `RamRoleArn` 模式，CLI 自动刷新。如果使用静态 STS，更新 token。

alibabacloud-workbench-cli：面向单实例的Workbench命令行工具，支持单实例的毫秒级的远程命令执行、1GB 大文件传输、TCP 端口转发，支持四种认证方式，适合代码部署、日志查看、文件收发及实例运维管理。

Workbench CLI 专家

使用说明

1. 安装 Workbench CLI

2. 配置凭证

创建配置目录

写入配置文件（示例：AK 模式）

设置安全权限

退出码

RAM 权限

故障排查

文档 3 / 6：`alibabacloud-starops-chat`

◯ 评论 0

Workbench CLI 专家

使用说明

1. 安装 Workbench CLI

2. 配置凭证

创建配置目录

写入配置文件（示例：AK 模式）

设置安全权限

退出码

RAM 权限

故障排查

文档 3 / 6：alibabacloud-starops-chat

◯ 评论 0

文档 3 / 6：`alibabacloud-starops-chat`