Tous les produits
Search
Centre de documentation

Elastic Compute Service:**Gérer des instances ECS avec Workbench CLI**

Dernière mise à jour :Aug 18, 2026

Utilisez les commandes list, connect, exec et upload/download pour interroger les instances ECS, vous connecter sans mot de passe, exécuter des commandes à distance et transférer des fichiers. La sortie JSON structurée et la transmission du code de sortie des commandes facilitent l'intégration dans des scripts et le diagnostic rapide des échecs.

Prérequis

  • Workbench CLI est installé sur votre ordinateur, et les identifiants ainsi que les autorisations RAM minimales sont configurés. Pour plus d'informations, consultez Installer Workbench CLI et configurer les identifiants.

  • L'instance ECS cible est une instance Linux à l'état Running, et l'agent Cloud Assistant est installé et en cours d'exécution.

  • Votre ordinateur peut accéder à *.aliyuncs.com et au point de terminaison WebSocket backend de Workbench. Les commandes upload et download nécessitent également que l'instance puisse accéder au point de terminaison interne OSS de la région correspondante.

Important

Workbench CLI prend actuellement en charge la connexion uniquement aux instances Linux. Pour vous connecter à une instance Windows, utilisez Se connecter à une instance avec Workbench.

Paramètres globaux

Les trois paramètres globaux suivants s'appliquent à toutes les sous-commandes workbench.

Paramètre

Valeur par défaut

Description

--output / -o

text

Le format de sortie. Valeurs valides : text et json. Nous vous recommandons d'utiliser json pour une consommation par des scripts ou des agents IA.

--region / -r

Déduit automatiquement

L'ID de région Alibaba Cloud, par exemple cn-hangzhou. L'interface CLI déduit la région automatiquement à partir du préfixe de l'ID d'instance, il n'est donc généralement pas nécessaire de la spécifier manuellement.

--profile / -P

Le profil actif

Spécifie le profil d'identifiants à utiliser pour cette commande, en remplaçant le profil actif. Utilisez-le pour basculer entre plusieurs comptes ou ensembles d'identifiants.

La région est déduite selon l'ordre suivant : mappage du préfixe de l'ID d'instance → recherche des sessions actives dans le daemon → **une erreur vous invitant à spécifier --region manuellement**. Lors de la première utilisation d'une instance, nous vous recommandons d'exécuter d'abord workbench list ecs -r <region> pour confirmer l'ID de l'instance.

Interroger la liste des instances (workbench list ecs)

Utilisez cette commande pour interroger les instances ECS par région, état, tag et autres conditions, afin de localiser rapidement l'ID de l'instance cible. workbench list équivaut par défaut à workbench list ecs. Exemples courants :

# 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

Paramètres :

Paramètre

Obligatoire

Description

-r / --region

Oui

L'ID de région Alibaba Cloud.

--status

Non

Filtre par état. Valeurs valides : Running, Stopped, Starting et Stopping.

--tag

Non

Filtre par tag au format key=value (ou par key uniquement). Vous pouvez spécifier ce paramètre plusieurs fois ; plusieurs tags utilisent la sémantique ET.

--instance-type

Non

Filtre par type d'instance, par exemple ecs.g7.large.

--instance-name

Non

Filtre par nom d'instance. Le caractère générique * est pris en charge.

--image-id

Non

Filtre par ID d'image.

--vpc-id

Non

Filtre par ID de VPC.

--zone-id

Non

Filtre par ID de zone.

--vswitch-id

Non

Filtre par ID de vSwitch.

--private-ip

Non

Filtre par adresses IP privées. Séparez plusieurs adresses par des virgules.

--limit

Non

Le nombre maximal d'instances à renvoyer par page. Valeurs valides : 1 à 100. Par défaut : 50.

--next-token

Non

Le jeton de pagination obtenu à partir de la réponse précédente, utilisé pour récupérer la page suivante.

La structure de retour de --output json est la suivante :

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

Connexion interactive (workbench connect)

workbench connect ouvre une session PTY interactive et constitue la commande principale de Workbench CLI. Exemples courants :

# 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

Paramètres :

Paramètre

Obligatoire

Valeur par défaut

Description

-i / --instance-id

Oui*

—

L'ID de l'instance ECS.

-r / --region

Non

Déduit automatiquement

L'ID de région Alibaba Cloud. Il n'est généralement pas nécessaire de le spécifier.

-u / --user-name

Non

root

Le nom d'utilisateur de connexion à distance.

--auth-type

Non

none

La méthode d'authentification. Valeurs valides : none, password et certificate.

-p / --port

Non

22

Le port SSH distant.

--new

Non

false

Force une nouvelle session et n'en réutilise pas une existante.

--session-id

Oui*

—

Se connecte directement à un ID de session spécifié (utilisation avancée).

Remarque

* Spécifiez soit -i, soit --session-id. Si vous spécifiez les deux, --session-id est prioritaire.

Méthodes d'authentification

Méthode d'authentification

Comportement

Scénario

none (par défaut)

Établit une session directement via le canal de connexion sans mot de passe de Workbench, sans qu'il soit nécessaire de prédéfinir un mot de passe ou une clé sur l'instance.

Opérations quotidiennes sans surcharge de gestion des clés SSH.

password

Vous invite à saisir le mot de passe de manière interactive après la connexion. La saisie n'est pas affichée.

Scénarios où la connexion par mot de passe est activée sur l'instance et nécessite une authentification SSH par mot de passe.

certificate

Vous invite à saisir le chemin du fichier de clé de manière interactive après la connexion (par exemple ~/.ssh/id_rsa). L'interface CLI lit automatiquement le contenu du fichier et effectue l'authentification.

Scénarios où l'équipe exige une connexion basée sur une clé et où l'audit doit permettre de remonter à l'empreinte digitale de la clé.

Commandes interactives et raccourcis clavier

Une fois dans une session workbench connect, appuyez sur Tab au début d'une ligne pour afficher le panneau de commandes slash :

Commande

Fonction

/agent

Active le mode de conversation avec l'agent IA intégré à la session (voir la section suivante).

/upload

Téléverse un fichier local vers l'instance (ouvre un sélecteur de fichiers interactif).

/download

Télécharge un fichier depuis l'instance vers l'ordinateur local (ouvre un sélecteur de fichiers interactif).

/detach

Détache la session (la session reste active en arrière-plan et vous pouvez vous y reconnecter ultérieurement en exécutant workbench connect -i <instance ID>).

/exit

Quitte et ferme la session.

/clear

Efface l'écran.

/help

Affiche les informations d'aide.

Raccourcis clavier courants :

Touche

Fonction

Tab (au début d'une ligne)

Affiche le panneau de commandes slash.

Ctrl+A

Active ou désactive le mode agent IA.

Ctrl+D

Quitte la session (équivalent à /exit).

Ctrl+C

Interrompt la commande distante en cours sans déconnecter la session.

Utiliser l'assistant IA intégré à la session

Au sein d'une session workbench connect, vous pouvez invoquer directement l'assistant IA intégré pour que l'IA effectue des opérations sur l'instance actuelle en langage naturel. Vous pouvez le déclencher de trois manières :

  • Saisissez /agent au début d'une ligne et appuyez sur Entrée.

  • Appuyez sur le raccourci clavier Ctrl+A.

  • Appuyez sur Tab pour afficher le panneau de commandes slash et sélectionnez /agent.

Une fois en mode agent, l'invite de commande change pour devenir une invite dédiée au mode agent. Saisissez directement du langage naturel après cette invite, et l'agent renvoie les réponses en flux continu. Commandes slash en mode agent :

Commande

Fonction

/shell

Quitte le mode agent et revient au shell standard (Ctrl+A permet également de quitter).

/new

Démarre une nouvelle conversation avec l'agent et efface le contexte.

/clear

Efface l'écran.

/upload / /download

Déclenche directement un téléversement ou un téléchargement de fichier en mode agent.

/help

Affiche l'aide.

/exit

Quitte et ferme la session.

Exemple de conversation typique :

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)
Important

Confirmation Human-in-the-loop (HITL) : Avant que l'agent n'exécute une commande sur l'instance, il affiche la commande à exécuter et attend votre confirmation avec Y/n. Les opérations d'API Cloud (telles que la création d'un snapshot) nécessitent également une confirmation. Il s'agit d'un mécanisme clé pour prévenir les actions involontaires de l'IA. Ne le désactivez pas.

L'agent conserve le contexte de la conversation au sein de la même session. Vous pouvez utiliser /new pour le réinitialiser. Les réponses sont diffusées en flux continu et vous pouvez appuyer sur Ctrl+C pour interrompre la génération en cours.

Remarque

Cette section explique comment invoquer directement l'assistant IA intégré dans une session connect. Si vous souhaitez qu'un agent dans un outil de programmation IA externe (Wukong ou opencode) appelle des commandes workbench, consultez Exploiter des instances ECS avec Workbench CLI dans des agents IA.

Exécution de commandes à distance (workbench exec)

workbench exec exécute une seule commande sur l'instance et renvoie le résultat. Contrairement au shell persistant de connect, chaque appel exec s'exécute dans un environnement indépendant. Plusieurs appels vers la même instance réutilisent le canal de connexion sous-jacent, ce qui évite toute configuration de connexion répétée. Exemples courants :

# 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

Paramètres :

Paramètre

Obligatoire

Valeur par défaut

Description

-i / --instance-id

Oui

—

L'ID de l'instance ECS.

-c / --command

Oui

—

La commande à exécuter.

--timeout

Non

30

Le délai d'expiration, en secondes.

Important

Chaque appel exec s'exécute dans un environnement shell indépendant et n'hérite ni du répertoire courant, ni des variables d'environnement, ni de l'état du shell de l'appel précédent. Si vous avez besoin d'une continuité de contexte (par exemple, exécuter cd puis une autre commande), combinez les commandes avec && ou ; dans le même paramètre -c.

La structure de retour de --output json est la suivante :

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

Dans cette structure, output correspond à la sortie standard de la commande, stderr à l'erreur standard et exit_code au code de sortie de la commande distante (un entier).

Transfert de fichiers (workbench upload / download)

Lorsque vous ne disposez pas d'adresse IP publique ou de canal SCP, utilisez workbench upload / workbench download pour transférer des fichiers. Le processus de téléversement affiche une barre de progression en temps réel.

Exemple de téléversement :

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

Exemple de téléchargement :

# 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

Paramètres :

Paramètre

Obligatoire

Valeur par défaut

Description

-i / --instance-id

Oui

—

L'ID de l'instance ECS.

Remarque

Les fichiers sont transférés en étant relayés via OSS, ce qui est totalement transparent pour vous et ne nécessite aucune autorisation OSS ni configuration de bucket. L'instance doit pouvoir accéder au point de terminaison interne OSS de la région correspondante (oss-<region>-internal.aliyuncs.com).

Gestion des sessions (workbench session)

Remarque

Les sessions sont généralement créées, réutilisées et nettoyées automatiquement par l'interface CLI et ne nécessitent aucune intervention lors d'une utilisation quotidienne. Les commandes de cette section servent au diagnostic et au nettoyage manuel.

Commandes courantes :

# 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

Transitions d'état des sessions :

  • OPEN : La session est établie et peut être lue et écrite normalement.

  • RECONNECTING : Le WebSocket sous-jacent s'est déconnecté et est en cours de reconnexion.

  • BROKEN : La reconnexion a échoué et la session n'est pas disponible.

  • CLOSED : La session est fermée (fermée par l'utilisateur, expiration du délai ou atteinte de la limite TTL).

Plusieurs opérations connect, exec, upload et download sur la même instance partagent la même session, gérée de manière transparente par le daemon, de sorte que vous n'avez pas à vous soucier de l'ID de session. Un seul terminal (TTY) peut être attaché à la même session à la fois. Si un terminal est déjà attaché, vous pouvez utiliser --new pour créer une nouvelle session, ou fermer d'abord la connexion existante.

Gestion du daemon (workbench daemon)

Workbench CLI s'appuie sur un daemon d'arrière-plan en espace utilisateur pour maintenir la connexion WebSocket et multiplexer les sessions. Le cycle de vie du daemon est entièrement automatique et ne nécessite généralement aucune gestion manuelle.

# View the daemon status
workbench daemon status

# Stop the daemon (closes all sessions)
workbench daemon stop
  • Démarrage automatique : Le daemon est démarré automatiquement la première fois que vous exécutez une commande workbench.

  • Arrêt automatique : Le daemon s'arrête automatiquement 60 secondes après la fermeture de la dernière session.

  • Instance unique : Une seule instance de daemon est autorisée par utilisateur du système d'exploitation (appliquée par un verrou de fichier PID).

  • Canal IPC : L'interface CLI et le daemon communiquent via ~/.workbench/run/daemon.sock (un socket Unix), en utilisant le protocole JSON-RPC.

Scénarios typiques

Scénario 1 : Déploiement d'application

Téléversez le package de déploiement → exécutez le script de déploiement à distance → vérifiez l'état de santé du service sur l'instance.

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"

Scénario 2 : Exécution groupée de commandes de diagnostic

Utilisez exec --output json pour obtenir des résultats structurés pouvant être analysés ultérieurement par un script ou filtrés avec jq.

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'

Scénario 3 : Se rattacher à une session après détachement

Pour les tâches de longue durée (comme le suivi des journaux ou la compilation), vous pouvez exécuter /detach puis fermer le terminal local. Lorsque vous exécutez à nouveau connect ultérieurement, vous vous rattachez automatiquement à la session d'origine.

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

Codes de sortie

workbench exec transmet le code de sortie de la commande distante : quel que soit le code de sortie renvoyé par la commande distante, l'interface CLI se termine avec le même code de sortie (comportement cohérent avec SSH). Par conséquent, un script peut déterminer si la commande distante a réussi directement à partir du code de sortie de workbench exec.

Par exemple, la commande suivante exécute exit 42 sur l'instance, et l'interface CLI se termine également avec 42 :

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

Lorsqu'une commande échoue pour des raisons telles que des paramètres incorrects, une authentification défaillante, un problème réseau ou une instance inexistante, l'utilisation de --output json affiche les détails de l'erreur au format suivant :

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

Dans cette structure, code est un identifiant d'erreur non nul et message est une description d'erreur lisible (qui inclut généralement le code d'erreur et le RequestId de l'API sous-jacente), que vous pouvez utiliser pour localiser le problème.

Dépannage

Symptômes courants et première action à entreprendre :

Symptôme / message d'erreur

Première action

Échec d'authentification / InvalidAccessKeyId.NotFound (l'AccessKey n'existe pas) ou IncompleteSignature (le secret AccessKey ne correspond pas)

Vérifiez si l'ID AccessKey et le secret AccessKey dans ~/.workbench/config.json forment une paire correspondante et sont complets sans espaces supplémentaires, ou exécutez à nouveau workbench config.

Une erreur indiquant que l'instance n'existe pas / InvalidParameter.InstanceId

Confirmez que l'ID d'instance et la région sont corrects. Vous pouvez exécuter workbench list ecs -r <region> pour interroger et confirmer.

Échec de la connexion sans mot de passe / IncorrectStatus.CloudAssistantNotRunning (l'agent Cloud Assistant n'est pas en cours d'exécution)

Par défaut, la connexion sans mot de passe (lorsque --auth-type n'est pas spécifié, il vaut none) repose sur l'exécution de l'agent Cloud Assistant à l'intérieur de l'instance, et cette erreur se produit lorsque l'agent est dans un état anormal. Assurez-vous que l'agent Cloud Assistant est installé et fonctionne normalement sur l'instance cible ; s'il est anormal, redémarrez-le ou réinstallez-le dans la console ECS. Consultez Installer l'agent Cloud Assistant. Sinon, utilisez --auth-type password ou certificate pour l'authentification SSH.

profile not found

Vérifiez si le nom du profil est correct. Exécutez workbench config list pour afficher les profils configurés.

Délai de connexion dépassé / erreur WebSocket

Vérifiez si votre ordinateur peut accéder à *.aliyuncs.com. Vérifiez si le groupe de sécurité de l'instance autorise le canal Workbench (de 100.104.0.0/16 vers TCP 22).

La connexion est occupée (la session est déjà attachée par un autre terminal)

Utilisez --new pour créer une nouvelle session, ou fermez d'abord la connexion existante.

Impossible de se connecter au daemon

Exécutez workbench daemon status. S'il est arrêté, toute commande déclenche un redémarrage automatique.

Erreur d'autorisation du fichier de configuration

Exécutez chmod 600 ~/.workbench/config.json. L'interface CLI rejette les fichiers de configuration dont les autorisations sont trop permissives.

Jeton STS expiré

En mode RamRoleArn, l'interface CLI actualise automatiquement. Si vous utilisez un jeton STS statique, mettez à jour le jeton.

Commandes de débogage :

# 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

Les journaux du daemon sont enregistrés dans ~/.workbench/log/daemon.log.

Références