Elastic Compute Service:Install and configure Workbench CLI credentials

Limites

• Sistema operacional da instância de destino: O Workbench CLI conecta-se apenas a instâncias Linux via Secure Shell Protocol (SSH) e não oferece suporte a instâncias Windows.

• Sistema operacional da máquina local: O próprio Workbench CLI executa em Linux, macOS (amd64 / arm64) e Windows (amd64).

• Conectividade de rede: A máquina local precisa acessar *.aliyuncs.com e o endpoint WebSocket de backend do Workbench.

Etapa 1: Instalar o Workbench CLI

Escolha o comando de instalação conforme o sistema operacional da máquina local. O script detecta automaticamente a arquitetura (amd64 / arm64), baixa o binário da CDN do OSS, verifica o checksum SHA256 e o instala no caminho padrão do sistema.

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

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

workbench version

Etapa 2: Preparar um AccessKey com permissões de privilégio mínimo para o Workbench CLI

O Workbench CLI chama as APIs da Alibaba Cloud usando um AccessKey. O objetivo desta etapa é obter um AccessKey com apenas as permissões mínimas necessárias, permitindo que você o configure na CLI da sua máquina local na próxima etapa. O procedimento recomendado é: Criar um usuário RAM → Conceder as permissões mínimas → Criar um AccessKey para o usuário RAM.

1. RAM console

   Criar um usuário RAM. Faça login no e navegue até a página Identities > Users. Clique em Create User. Na página de criação, insira o User Login Name e o Display Name e clique em OK.

   Não crie um AccessKey neste momento. Ele será gerado na etapa 4, após a conclusão da autorização.

2. Criar uma política personalizada. No console RAM, acesse a página Permissions > Policies e clique em Create Policy. Mude para o modo Script Editor, cole o JSON abaixo e clique em OK.

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ecs-workbench:*"
         ],
         "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"
           }
         }
       }
     ]
   }

   A tabela a seguir descreve a finalidade de cada Action na política:

   Action	Finalidade
   ecs:DescribeInstances	workbench list ecs Consulta a lista de instâncias.
   ecs:DescribeCloudAssistantStatus	Verifica o status do Cloud Assistant Agent na instância de destino.
   ecs:StartTerminalSession	Estabelece uma sessão de terminal com a instância ECS.
   ecs-workbench:LoginECSInstance	Login sem senha através do canal Workbench (utilizado por connect, exec, upload e download).
   ecs-workbench:ChatMessages	Permissões necessárias para o assistente AI Agent durante a sessão (modo /agent).
   ecs-workbench:EndSessions	Encerra a sessão do Workbench (chamado por session close e pela limpeza automática de sessões).
   ram:CreateServiceLinkedRole	Cria a função vinculada ao serviço Workbench no primeiro uso, utilizando Condition para restringir a criação à função vinculada do serviço workbench.ecs.aliyuncs.com.

   Por padrão, a política acima concede acesso a todas as instâncias. Para limitar o escopo a instâncias específicas, utilize ARNs de instância apenas para operações que suportam autorização no nível da instância e divida-as em blocos Statement separados conforme necessário para modificar o campo Resource:

   "Resource": "acs:ecs:<region>:<account-id>:instance/<instance-id>"

   Nota

   As ações ecs-workbench:ChatMessages e ram:CreateServiceLinkedRole não permitem restrição por ARN de instância e devem permanecer como "Resource": "*".

3. Conceder a política ao usuário RAM. Acesse a página de detalhes do usuário RAM criado na etapa 1 e clique na aba Permissions. Clique em Grant Permission

   Manage the permissions of a RAM user

   Grant Permission, selecione a política personalizada criada anteriormente e conclua a autorização. Para mais instruções, consulte .

4. Criar um AccessKey para o usuário RAM. Na página de detalhes do usuário RAM, vá para a aba Credentials > AccessKey e clique em Create AccessKey. Na tela exibida, selecione Use the AccessKey in the CLI, marque I confirm that I must create an AccessKey e clique em Continue

   Create an AccessKey pair

   Continue. Para instruções detalhadas, veja .

   Importante

   O segredo do AccessKey é exibido apenas uma vez, no momento da criação, e não pode ser consultado novamente após fechar a página. Salve o AccessKey ID e o segredo imediatamente em um gerenciador de senhas ou keystore. Caso os perca, será necessário criar um novo par de AccessKey.

   Um AccessKey é uma credencial de longo prazo; se vazada, pode ser explorada por muito tempo. Em ambientes de produção, mude para um modo de credencial com atualização automática, como RamRoleArn, assim que concluir a configuração na Etapa 3. Consulte a seção Outros métodos de configuração para detalhes.

Etapa 3: Configurar o par de AccessKey na CLI local

Execute o comando abaixo e insira o AccessKey ID e o segredo obtidos na Etapa 2 quando solicitado.

workbench config

Ao finalizar a configuração, as credenciais são salvas em ~/.workbench/config.json, e as permissões do arquivo são definidas automaticamente como 0600 (leitura e escrita permitidas apenas para o usuário atual). Exemplo do conteúdo do arquivo:

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

Para verificar se a conexão funciona, execute o comando a seguir (substitua cn-hangzhou pela sua região real):

workbench list ecs -r cn-hangzhou

Se tudo estiver correto, a lista de instâncias da região será retornada. Caso receba erros como InvalidAccessKeyId ou NoPermission, consulte a seção FAQ.

(Opcional) Definir o idioma da interface

O Workbench CLI suporta chinês (zh) e inglês (en) como idiomas de interface. Por padrão, o idioma é chinês. Execute o comando abaixo para alterar:

workbench config set language en   # Switch to English
workbench config set language zh   # Switch back to Chinese

Também é possível definir o idioma no fluxo interativo do workbench config ou editar diretamente o arquivo ~/.workbench/config.json, adicionando o campo language no perfil correspondente:

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "language": "en"
    }
  }
}

A alteração entra em vigor na próxima reconexão, sem necessidade de reiniciar o daemon.

(Opcional) Gerenciar múltiplos perfis

Para alternar entre várias contas Alibaba Cloud ou diferentes conjuntos de credenciais, utilize o recurso de perfis e evite reconfigurar as credenciais repetidamente. Todos os perfis ficam armazenados no mesmo arquivo ~/.workbench/config.json, onde o campo current indica o perfil ativo.

workbench config --profile prod          # Create or edit the prod Profile
workbench config list                    # List all profiles (* marks the active one)
workbench config get --profile prod      # Show the details of the specified profile
workbench config switch --profile prod   # Switch the active Profile
workbench config delete --profile old    # Delete a profile (the active profile cannot be deleted)
workbench exec -i i-xxx -c "hostname" --profile prod   # For this command only, use the specified Profile

Exemplo de config.json com múltiplos perfis:

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AK",
      "access_key_id": "LTAI...",
      "access_key_secret": "..."
    },
    "prod": {
      "mode": "RamRoleArn",
      "access_key_id": "LTAI...",
      "access_key_secret": "...",
      "ram_role_arn": "acs:ram::123456:role/prod",
      "role_session_name": "workbench"
    }
  }
}

Outros métodos de configuração

Um AccessKey estático é uma credencial de longo prazo e, se comprometida, pode ser abusada por um período extenso. Em ambientes de produção ou sob requisitos de segurança mais rigorosos, opte por um dos outros seis modos disponíveis:

workbench config --mode StsToken

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "StsToken",
      "access_key_id": "STS.LTAI...",
      "access_key_secret": "...",
      "sts_token": "..."
    }
  }
}

workbench config --mode RamRoleArn

{
  "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"
    }
  }
}

workbench config --mode CredentialsCmd

workbench config --mode CredentialsCmd
# Process Command input:
# /usr/local/bin/aliyun-zerotrust-credential-provider --app-name=myapp --role=acs:ram::123456789:role/WorkbenchRole

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "CredentialsCmd",
      "process_command": "/usr/local/bin/aliyun-zerotrust-credential-provider --app-name=myapp --role=acs:ram::123456789:role/WorkbenchRole"
    }
  }
}

#!/bin/bash
# ~/.workbench/get-creds.sh
# Obtain credentials from Vault or another key management system
vault read -format=json secret/aliyun | jq '{
  mode: "StsToken",
  access_key_id: .data.access_key_id,
  access_key_secret: .data.access_key_secret,
  sts_token: .data.security_token
}'

workbench config --mode CredentialsURI

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

workbench config --mode EcsRamRole

workbench config --mode AliyunCLI

{
  "current": "default",
  "profiles": {
    "default": {
      "mode": "AliyunCLI",
      "aliyun_profile": "wb-sub-01"
    }
  }
}

Atualizar o Workbench CLI

O Workbench CLI suporta autoatualização em uma única etapa. Execute o comando abaixo para obter a versão mais recente:

workbench upgrade

Durante a atualização, o binário da versão mais recente é baixado, verificado e substitui a versão atual automaticamente.

Desinstalar

O Workbench CLI não registra serviços nem altera configurações do sistema. Para desinstalá-lo, pare o daemon, remova o binário e (opcionalmente) exclua o diretório de configuração local.

workbench daemon stop
sudo rm -f /usr/local/bin/workbench
rm -rf ~/.workbench

workbench daemon stop
Remove-Item "$env:ProgramFiles\workbench" -Recurse -Force

# Delete the item created during installation in the Cloud Assistant scenario: shim
Remove-Item "$env:SystemRoot\System32\workbench.cmd" -Force -ErrorAction SilentlyContinue

Remove-Item "$env:USERPROFILE\.workbench" -Recurse -Force

# Remove the workbench path that the installation script (remote desktop scenario) added to the user PATH
$path = [Environment]::GetEnvironmentVariable("Path", "User")
if ($path -match "workbench") {
    $cleaned = ($path -split ";" | Where-Object { $_ -notmatch "workbench" }) -join ";"
    [Environment]::SetEnvironmentVariable("Path", $cleaned, "User")
}

FAQ

chmod 600 ~/.workbench/config.json

Referências

• Connect using Workbench CLI: Tópico pai, abordando posicionamento da ferramenta, matriz de capacidades e início rápido.

• Manage ECS instances by using Workbench CLI: Descrições detalhadas de cada comando e cenários comuns.

• Operate ECS instances by using Workbench CLI in AI agents: Integração do Workbench CLI com ferramentas de codificação por IA.

• Manage the permissions of a RAM user

• Create an AccessKey pair

• What is STS?

• Install the Cloud Assistant Agent