SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场alibabacloud-workbench-cli

alibabacloud-workbench-cli

部署与运维

查看项目

更新于 10-15 14:10

技能介绍

用途

Workbench CLI 是阿里云提供的命令行工具，用于操作阿里云 ECS 实例，特别是那些没有公网 IP 地址的实例。它面向 Agent 工作流设计，主要针对单实例操作，核心能力包括毫秒级远程命令执行、文件传输和端口转发。该技能覆盖从安装、配置凭证、执行命令/传输文件/端口转发，到管理会话和排查错误的完整流程。

主要能力

  • 远程命令执行（exec）：非交互式、毫秒级执行远程命令。每次调用在独立的 shell 上下文中运行，状态（如 cd、export）不会在调用之间保留，需用 && 或 ; 在单次调用中串联命令。
  • 文件传输（upload/download）：支持最大 1GB 的文件上传与下载，通过 OSS 作为中转，对用户透明，无需配置 OSS。
  • 端口转发：资料中列为能力之一，具体命令细节暂未提供。
  • 实例列表（list）：按地域、状态、标签、实例类型、实例名、镜像 ID、VPC、可用区、交换机、私网 IP 等条件筛选 ECS 实例，支持分页。
  • 会话管理（session）：列出、关闭会话，支持关闭全部。会话生命周期为 OPEN → RECONNECTING → BROKEN → CLOSED，空闲 30 分钟自动关闭，同一实例的多个操作共享一个会话。
  • 守护进程管理（daemon）：启动、查看状态、停止守护进程。首次调用 CLI 时自动启动，最后一个会话关闭 60 秒后自动退出，每个操作系统用户单例运行，通过 Unix socket 上的 JSON-RPC 通信。
  • 配置管理（config）：设置单个配置字段、列出所有 profile、切换活动 profile、查看 profile 详情、删除 profile。
  • 自更新（upgrade） 与 版本查看（version）。

使用方式

安装

预检查：workbench version（应打印版本、提交、构建日期）。

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        # 升级到指定版本

配置凭证

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

mkdir -p ~/.workbench
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

支持的凭证模式：AK（默认，适用于开发、长期凭证）、StsToken（临时安全凭证）、RamRoleArn（生产、跨账号、最小权限，自动刷新 STS 令牌）、CredentialsCmd（零信任 / Vault 集成，外部命令输出凭证 JSON）、CredentialsURI（元数据服务 / sidecar，HTTP 端点返回凭证 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（不能删除活动 profile）

命令结构

workbench
├── exec             # 执行远程命令（非交互式，毫秒级）
├── upload           # 上传本地文件到实例（最大 1GB，经 OSS 中转）
├── download         # 从实例下载文件（最大 1GB，经 OSS 中转）
├── list             # 列出 ECS 实例
├── session          # 会话管理（list / close）
├── daemon           # 守护进程生命周期（start / status / stop）
├── config           # 凭证配置与 profile 管理
├── upgrade          # 自更新
└── version          # 打印版本信息

全局标志：--output / -o（输出格式 text 或 json）、--region / -r（阿里云地域，默认从实例 ID 前缀自动推断）、--profile / -P（使用指定 profile，覆盖活动 profile）。

列出实例

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 --output json

list ecs 必须指定 --region。筛选参数包括 --status、--tag（可重复，AND 逻辑）、--instance-type、--instance-name（支持通配符 *）、--image-id、--vpc-id、--zone-id、--vswitch-id、--private-ip（逗号分隔）、--limit（1-100，默认 50）、--next-token（分页）。

远程命令执行

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 和 --command / -c 为必填，--timeout 默认 30 秒。

文件传输

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

upload 内置覆盖保护：远程目标文件已存在时会提示确认，默认答案为 No。download 的第二个参数（本地路径）可选，默认当前目录。

会话与守护进程

workbench session list
workbench session close <session-id>
workbench session close --all
workbench daemon start
workbench daemon status
workbench daemon stop

地域推断

CLI 从实例 ID 的 3 字符前缀自动推断地域（覆盖 290+ 地域）。推断失败时需指定 --region。list 命令始终需要 --region。

适用场景

  • 管理无公网 IP 的 ECS 实例。
  • Agent 自动化工作流中的远程命令执行与文件传输。
  • 需要最小权限、跨账号或临时凭证的生产环境运维。
  • 通过会话与守护进程机制进行多操作复用与连接管理。

限制与安全注意事项

  • 主要面向单实例操作。
  • exec 为非交互式、无状态执行，不提供持久 shell，每次调用相互隔离。
  • 执行破坏性命令（如 rm -rf、shutdown、reboot、mkfs、dd、服务停止/重启等）前，Agent 必须先向用户确认操作内容、目标实例和潜在影响，未经明确批准不得执行。
  • 在自动化/Agent 工作流中使用 upload 时，若无法交互确认，Agent 必须先检查远程目标文件是否存在并告知用户。
  • 需要相应的 RAM 权限策略（ecs-workbench:LoginECSInstance、ecs-workbench:ChatMessages、ecs:DescribeInstances、ecs:DescribeCloudAssistantStatus、ecs:StartTerminalSession，以及受限的 ram:CreateServiceLinkedRole）。
  • 退出码：0 成功、1 一般错误、2 参数错误、3 会话未找到、4 认证/授权失败、5 网络错误、6 守护进程不可达、7 会话被占用；exec 会透传远程命令的退出码。
  • 端口转发的具体命令细节暂未提供。