Connect to an ECS instance by using Workbench CLI (for the command line and AI agents) - Elastic Compute Service: Central de Documentação do Alibaba Cloud

O que é o Workbench CLI

Importante

Atualmente, o Workbench CLI suporta conexão apenas com instâncias Linux (via protocolo SSH). Não há suporte para conexão com instâncias Windows. Para se conectar a uma instância Windows, consulte Connect to an instance by using Workbench.

O Workbench CLI (cujo comando é workbench) é uma ferramenta de linha de comando fornecida pelo Alibaba Cloud ECS para conexão com instâncias. Ela é adequada para os seguintes usuários:

Usuários humanos: Quando não há um endereço IP público atribuído à instância, utilize a linha de comando para realizar login interativo, executar comandos remotamente e fazer upload e download de arquivos, como alternativa a uma conexão SSH direta.
Agentes de IA: Com saída estruturada em JSON (--output json) e repasse de código de saída, ferramentas de programação com IA (como Wukong e opencode) podem invocar o comando workbench diretamente para gerenciar instâncias ECS, sem necessidade de adaptações adicionais.

As principais capacidades do Workbench CLI são:

Login interativo: workbench connect abre uma sessão PTY e oferece suporte a três métodos de autenticação: sem senha, por senha e por chave.
Execução remota de comandos: workbench exec executa um único comando na instância e retorna o resultado em formato de texto ou JSON.
Transferência de arquivos: Os comandos workbench upload e workbench download transferem arquivos entre seu computador e a instância utilizando o OSS como retransmissor.
Gerenciamento de sessões e daemon: workbench session e workbench daemon são utilizados para diagnósticos e limpeza manual. Nenhuma intervenção é necessária durante o uso diário.
Assistente de agente de IA na sessão: Em uma sessão interativa do connect, pressione Tab ou Ctrl+A para acionar o assistente de IA e use linguagem natural para solicitar que a IA execute comandos na instância.

Comparação com outros métodos de conexão do ECS

O Alibaba Cloud ECS disponibiliza três métodos de conexão baseados no Workbench ou Session Manager que não exigem um endereço IP público. A tabela a seguir compara esses métodos.

Capacidade	Workbench (web)	Workbench CLI	Session Manager CLI (ali-instance-cli)
Interação	GUI no navegador	Linha de comando local	Linha de comando local
Endereço IP público necessário	Não	Não	Não
Sistemas operacionais suportados	Linux e Windows	Apenas Linux (via protocolo SSH)	Linux e Windows
Comandos remotos e transferência de arquivos	Operações manuais no terminal web	Comandos nativos: exec, upload e download	Apenas sessões de terminal; requer scripts adicionais
Projetado para agentes de IA	Não	Sim (saída estruturada em JSON e repasse de código de saída)	Não
Cenários típicos	Solução de problemas pontuais e acesso à área de trabalho Windows	Scripts diários de O&M e assistentes de programação com IA	Scripts existentes que requerem apenas sessões de terminal

Recomendações para seleção do método:

Caso necessite de uma interface gráfica ou precise conectar-se a uma instância Windows, utilize Connect to an instance by using Workbench.
Para operar instâncias Linux via linha de comando ou em ferramentas de programação com IA, opte pelo Workbench CLI.
Se você já possui scripts ali-instance-cli e precisa apenas de sessões de terminal, pode continuar a utilizá-los. Para mais informações, consulte Connect to an instance by using ali-instance-cli.

Limites

Sistema operacional da instância: Há suporte apenas para instâncias Linux (via protocolo SSH). Instâncias Windows não são suportadas.
Agente do Cloud Assistant: A instância de destino deve ter o agente do Cloud Assistant instalado e funcionando corretamente. Instâncias ECS criadas a partir de imagens públicas oficiais após 1º de dezembro de 2017 já possuem o agente do Cloud Assistant pré-instalado por padrão. Caso contrário, será necessário instalá-lo manualmente.
Regras de grupo de segurança: Na primeira conexão, a CLI adiciona automaticamente uma regra interna de grupo de segurança para a instância (porta TCP 22, com autorização para 100.104.0.0/16). Se sua conta não possuir permissões de grupo de segurança, adicione a regra manualmente no console ECS.
Conectividade de rede: Seu computador deve conseguir acessar *.aliyuncs.com e o endpoint WebSocket de backend do Workbench. Os comandos upload e download exigem que a instância tenha acesso ao endpoint interno do OSS da região correspondente.

Importante

No momento, o Workbench CLI não suporta instâncias Windows. Não utilize workbench connect para instâncias Windows.

Início rápido

Realize sua primeira conexão em 5 minutos seguindo os três passos abaixo. Para instruções detalhadas sobre instalação, credenciais e comandos, consulte Install Workbench CLI and configure credentials e Manage ECS instances by using Workbench CLI.

Etapa 1: Instalar o Workbench CLI

Selecione o comando de instalação apropriado para o sistema operacional do seu computador. O script de instalação detecta automaticamente a arquitetura (amd64 ou arm64) e realiza a instalação no caminho padrão do sistema.

Linux ou macOS

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

Windows

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

Etapa 2: Configurar um par de AccessKey

Execute o comando abaixo e insira o AccessKey ID e o AccessKey secret quando solicitado.

workbench config

Após a conclusão da configuração, as credenciais serão salvas em ~/.workbench/config.json, e as permissões do arquivo serão definidas automaticamente como 0600 (leitura e escrita apenas para o usuário atual). Em ambientes de produção, recomendamos o uso de credenciais de função RAM em vez de um par de AccessKey estático. Para mais detalhes sobre o método de configuração, consulte Install Workbench CLI and configure credentials.

Etapa 3: Conectar-se a uma instância

Execute o seguinte comando para estabelecer conexão com a instância desejada. Substitua i-bp1a2b3c4d5e6f pelo ID da sua instância.

workbench connect -i i-bp1a2b3c4d5e6f

A região é inferida automaticamente a partir do prefixo do ID da instância, portanto, geralmente não é necessário especificá-la manualmente usando -r. Após entrar no shell interativo, pressione Tab para abrir o painel de comandos com barra (como /upload, /download e /agent) e pressione Ctrl+D para encerrar a sessão.

Visão geral dos comandos

Comando	Descrição
`workbench list ecs`	Consulta a lista de instâncias ECS por região, status ou tag.
`workbench connect`	Abre uma sessão PTY interativa para conexão com uma instância. Suporta autenticação sem senha, por senha e por chave.
`workbench exec`	Executa um único comando na instância e retorna o resultado. Oferece suporte a saída em texto e JSON.
`workbench upload` / `workbench download`	Realiza upload ou download de arquivos entre seu computador e a instância, utilizando o OSS como retransmissor.
`workbench session`	Consulta e encerra sessões manualmente. Nenhuma intervenção é necessária para uso diário.
`workbench daemon`	Visualiza ou interrompe o daemon em segundo plano. Ele inicia automaticamente na primeira chamada e encerra após 60 segundos de inatividade.
`workbench config`	Configura credenciais. Suporta cinco modos (AK, StsToken, RamRoleArn, CredentialsCmd e CredentialsURI) e múltiplos perfis.
`workbench upgrade`	Atualiza para a versão mais recente ou para uma versão específica.
`workbench version`	Exibe o número da versão atual, commit e data de compilação.

Todos os comandos acima aceitam os parâmetros globais --output json, --region e --profile. Para consultar a lista completa de parâmetros, exemplos e a estrutura de saída JSON de cada comando, veja Manage ECS instances by using Workbench CLI.

Referências

Install Workbench CLI and configure credentials: Instalação da CLI em Linux, macOS e Windows, além da configuração dos cinco modos de credencial (AK, StsToken, RamRoleArn, CredentialsCmd e CredentialsURI) e da política mínima de permissões RAM.
Manage ECS instances by using Workbench CLI: Parâmetros, exemplos, cenários típicos e solução de problemas para os comandos list, connect, exec, upload, download, session e daemon.
Operate ECS instances by using Workbench CLI in AI agents: Como carregar a habilidade do Workbench CLI em ferramentas de programação com IA, como Wukong e opencode, incluindo cenários típicos de conversa e recomendações de segurança.