Elastic Compute Service:**Gerencie instâncias ECS com o Workbench CLI**

Pré-requisitos

• O Workbench CLI deve estar instalado no seu computador, com as credenciais e as permissões mínimas de RAM configuradas. Para mais informações, consulte Install Workbench CLI and configure credentials.

• A instância ECS de destino deve ser uma instância Linux com status Running, e o agente do Cloud Assistant deve estar instalado e em execução.

• Seu computador precisa acessar *.aliyuncs.com e o endpoint WebSocket de backend do Workbench. Os comandos upload e download também exigem que a instância possa acessar o endpoint interno do oss da região correspondente.

Parâmetros globais

Os três parâmetros globais a seguir aplicam-se a todos os subcomandos do workbench.

A inferência da região segue esta ordem: mapeamento do prefixo do id da instância → busca de sessões ativas no daemon → **erro solicitando a especificação manual de --region**. Ao usar uma instância pela primeira vez, recomendamos executar primeiro workbench list ecs -r <region> para confirmar o id da instância.

Consultar a lista de instâncias (workbench list ecs)

Use este comando para consultar instâncias ECS por região, status, tag e outras condições, facilitando a localização rápida do id da instância desejada. Por padrão, workbench list equivale a workbench list ecs. Exemplos comuns:

# Query all instances in a specified region
workbench list ecs -r cn-hangzhou

# Query only running instances
workbench list ecs -r cn-hangzhou --status Running

# Filter by tag (multiple --tag options use AND semantics)
workbench list ecs -r cn-hangzhou --tag env=prod --tag app=web

# Filter by instance type, name, VPC, and other conditions
workbench list ecs -r cn-hangzhou --instance-type ecs.g7.large --instance-name "web-*"

# Output JSON for consumption by scripts or AI agents
workbench list ecs -r cn-hangzhou --output json

Parâmetros:

A estrutura de retorno de --output json é a seguinte:

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

Conexão interativa (workbench connect)

O comando workbench connect abre uma sessão PTY interativa e constitui o comando principal do Workbench CLI. Exemplos comuns:

# Default no authentication (Workbench passwordless logon)
workbench connect -i i-bp1a2b3c4d5e6f

# Password authentication (enter the password interactively; input is not echoed)
workbench connect -i i-bp1a2b3c4d5e6f --auth-type password

# Certificate authentication (enter the key file path interactively, such as ~/.ssh/id_rsa)
workbench connect -i i-bp1a2b3c4d5e6f --auth-type certificate

# Specify the logon user and port
workbench connect -i i-bp1a2b3c4d5e6f -u admin -p 2222

# Force a new session (do not reuse an existing session)
workbench connect -i i-bp1a2b3c4d5e6f --new

Parâmetros:

Agent> Show the processes with the highest CPU usage
  ┌─ Running command ──────────
  │ ps aux --sort=-%cpu | head -10
  └────────────────────────
  Waiting for confirmation (Y/n): y
  [Executed]
  ... (the agent continues its analysis and provides conclusions)

Execução remota de comandos (workbench exec)

O comando workbench exec executa um único comando na instância e retorna o resultado. Diferentemente do shell persistente do connect, cada chamada de exec roda em um ambiente independente. Múltiplas chamadas para a mesma instância reutilizam o canal de conexão subjacente, eliminando a necessidade de configurar a conexão repetidamente. Exemplos comuns:

# Run a command
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h"

# Combine commands: cd + environment variable + run
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/app && ./deploy.sh"

# Set a timeout
workbench exec -i i-bp1a2b3c4d5e6f -c "sleep 30" --timeout 10

# JSON output for consumption by scripts or AI agents
workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json

Parâmetros:

A estrutura de retorno de --output json é a seguinte:

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

Nesta estrutura, output representa a saída padrão do comando, stderr é o erro padrão e exit_code corresponde ao código de saída do comando remoto (um número inteiro).

Transferência de arquivos (workbench upload / download)

Quando não houver um endereço IP público ou canal SCP disponível, use workbench upload / workbench download para transferir arquivos. O processo de upload exibe uma barra de progresso em tempo real.

Exemplo de upload:

workbench upload ./app.jar /opt/app/app.jar -i i-bp1a2b3c4d5e6f

Exemplo de download:

# Download to the current directory
workbench download /var/log/app.log ./ -i i-bp1a2b3c4d5e6f

# Download and rename
workbench download /var/log/app.log ./local-copy.log -i i-bp1a2b3c4d5e6f

Parâmetros:

Gerenciamento de sessões (workbench session)

Comandos comuns:

# View all active sessions
workbench session list
workbench session list --output json

# Close a specified session
workbench session close <session-id>

# Close all sessions
workbench session close --all

Transições de estado da sessão:

• OPEN: A sessão está estabelecida e permite leitura e escrita normais.

• RECONNECTING: A conexão WebSocket subjacente foi perdida e está sendo restabelecida.

• BROKEN: A reconexão falhou e a sessão está indisponível.

• CLOSED: A sessão foi encerrada (pelo usuário, por tempo limite ou por atingir o limite TTL).

Múltiplas operações de connect, exec, upload e download na mesma instância compartilham a mesma sessão. O daemon gerencia isso de forma transparente; portanto, não é necessário preocupar-se com o id da sessão. Apenas um terminal (TTY) pode se anexar à mesma sessão por vez. Se já houver um terminal conectado, use --new para criar uma nova sessão ou feche a conexão existente primeiro.

Gerenciamento do daemon (workbench daemon)

O Workbench CLI depende de um daemon em segundo plano no espaço do usuário para manter a conexão WebSocket e multiplexar as sessões. O ciclo de vida do daemon é totalmente automático e geralmente não requer gerenciamento manual.

# View the daemon status
workbench daemon status

# Stop the daemon (closes all sessions)
workbench daemon stop

• Inicialização automática: O daemon inicia automaticamente na primeira vez que você executa qualquer comando workbench.

• Encerramento automático: O daemon encerra automaticamente 60 segundos após o fechamento da última sessão.

• Instância única: Apenas uma instância do daemon é permitida por usuário do sistema operacional (garantida por um bloqueio de arquivo PID).

• Canal IPC: A CLI e o daemon se comunicam por meio de ~/.workbench/run/daemon.sock (um socket Unix), usando o protocolo json-RPC.

Cenários típicos

workbench upload ./app-2.0.tar.gz /opt/deploy/ -i i-bp1a2b3c4d5e6f
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/deploy && tar xzf app-2.0.tar.gz && ./deploy.sh"
workbench exec -i i-bp1a2b3c4d5e6f -c "curl -s http://localhost:8080/health"

workbench exec -i i-bp1a2b3c4d5e6f -c "df -h && free -m" --output json | jq '.output'
workbench exec -i i-bp1a2b3c4d5e6f -c "systemctl status nginx" --output json | jq '.exit_code'

workbench connect -i i-bp1a2b3c4d5e6f
# Run tail -f or a long-running task in the session
# Then enter /detach to detach

# Reattach to the original session later
workbench connect -i i-bp1a2b3c4d5e6f

Códigos de saída

O comando workbench exec propaga o código de saída do comando remoto: qualquer que seja o código retornado pelo comando remoto, a CLI encerrará com o mesmo código (comportamento consistente com ssh). Assim, um script pode determinar se o comando remoto foi bem-sucedido diretamente pelo código de saída do workbench exec.

Por exemplo, o comando abaixo executa exit 42 na instância, e a CLI também encerra com 42:

workbench exec -i i-bp1a2b3c4d5e6f -c "exit 42"
echo $?   # Outputs 42

Quando um comando falha devido a problemas como parâmetros incorretos, autenticação, rede ou instância inexistente, o uso de --output json gera os detalhes do erro no seguinte formato:

{
  "code": 1,
  "message": "session resolve: login instance: ... InvalidParameter.InstanceId ..."
}

Nesta estrutura, code é um identificador de erro diferente de zero, e message contém uma descrição legível do erro (que geralmente inclui o código de erro e o RequestId da api subjacente), permitindo localizar o problema.

Solução de problemas

Sintomas comuns e a primeira ação recomendada:

Comandos de depuração:

# View the daemon status
workbench daemon status

# JSON error output for easy parsing by scripts
workbench exec -i i-bp1a2b3c4d5e6f -c "echo test" --output json

Os logs do daemon são salvos em ~/.workbench/log/daemon.log.

Referências

• Connect to an instance by using Workbench CLI: tópico pai, que aborda o posicionamento da ferramenta e o início rápido.

• Install Workbench CLI and configure credentials: instalação da CLI e configuração de credenciais/permissões.

• Operate ECS instances by using Workbench CLI in AI agents: como fazer um agente chamar comandos do workbench no Wukong ou opencode.

• Install the Cloud Assistant agent: o Workbench CLI depende do agente do Cloud Assistant.