Après avoir installé Workbench CLI sur votre machine locale Linux, macOS ou Windows, associez une politique d'autorisations minimales à un utilisateur RAM, puis générez et configurez une AccessKey pour un accès immédiat aux identifiants. Dans les environnements de production, vous pouvez basculer vers RamRoleArn, CredentialsCmd ou CredentialsURI afin d'activer l'actualisation automatique des identifiants et le principe du moindre privilège.
Limites
Système d'exploitation de l'instance cible : Workbench CLI permet uniquement de se connecter aux instances Linux via le protocole SSH (Secure Shell) et ne prend pas en charge la connexion aux instances Windows.
Système d'exploitation de la machine locale : Workbench CLI s'exécute sur Linux, macOS (amd64 / arm64) et Windows (amd64).
Connectivité réseau : La machine locale doit pouvoir accéder à
*.aliyuncs.comainsi qu'au point de terminaison WebSocket du backend Workbench.
Les instances Windows ne sont actuellement pas prises en charge par Workbench CLI. Pour vous connecter à une instance Windows, consultez la rubrique Se connecter à une instance à l'aide de Workbench.
Étape 1 : Installer Workbench CLI
Sélectionnez la commande d'installation correspondant au système d'exploitation de votre machine locale. Le script d'installation détecte automatiquement l'architecture (amd64 / arm64), télécharge le binaire depuis le CDN OSS, vérifie la somme de contrôle SHA256 et l'installe dans le chemin système par défaut.
Linux ou macOS
Exécutez la commande suivante pour installer la dernière version de Workbench CLI.
chmod 600 ~/.workbench/config.json
Après l'installation, le binaire se trouve dans /usr/local/bin/workbench. Sur macOS, le binaire est automatiquement resigné et son attribut de quarantaine est supprimé. Si le répertoire cible nécessite des privilèges d'administrateur, le script utilise automatiquement sudo.
Windows
Exécutez la commande suivante dans PowerShell pour installer la dernière version de Workbench CLI.
chmod 600 ~/.workbench/config.json
Après l'installation, le binaire se trouve dans le répertoire C:\Program Files\workbench\ et le script d'installation configure automatiquement la variable d'environnement PATH. Si vous effectuez l'installation lors d'une session de bureau ou via le protocole Remote Desktop Protocol (RDP), la modification du PATH ne sera prise en compte qu'après déconnexion puis reconnexion.
Vérifier l'installation
Une fois l'installation terminée, exécutez la commande suivante pour vérifier :
chmod 600 ~/.workbench/config.json
Normalement, le numéro de version actuel, l'ID de commit et la date de build s'affichent. Si vous voyez command not found, cela signifie généralement que la variable PATH n'a pas été prise en compte. Vous pouvez alors procéder comme suit :
Linux / macOS : rouvrez la fenêtre du terminal ou exécutez
source ~/.bashrc(ou~/.zshrc), puis réessayez.Windows : fermez et rouvrez la fenêtre PowerShell afin que la nouvelle valeur de PATH soit appliquée.
Étape 2 : Préparer un AccessKey avec des autorisations minimales pour Workbench CLI
Workbench CLI appelle les API Alibaba Cloud à l'aide d'un AccessKey. L'objectif de cette étape est d'obtenir un AccessKey disposant uniquement des autorisations minimales requises par Workbench CLI, afin de pouvoir le configurer dans la CLI sur votre machine locale à l'étape suivante. La procédure recommandée est la suivante : Créer un utilisateur RAM → Accorder les autorisations minimales → Créer un AccessKey pour l'utilisateur RAM.
N'utilisez pas l'AK/SK de votre compte Alibaba Cloud pour configurer la CLI. L'AccessKey d'un compte Alibaba Cloud dispose d'autorisations d'opération sur toutes les ressources cloud associées à ce compte. En cas de fuite, l'ensemble de vos actifs serait exposé. Utilisez toujours l'AccessKey d'un utilisateur RAM disposant uniquement des autorisations minimales requises.
Si vous disposez déjà d'un utilisateur RAM répondant aux exigences d'autorisations minimales de Workbench CLI, ignorez les étapes 1 à 3 et passez directement à l'Étape 4 : Créer un AccessKey pour l'utilisateur RAM.
-
Créez un utilisateur RAM. Connectez-vous à la console RAM et accédez à la page . Cliquez sur Create User. Sur la page de création, saisissez le User Login Name et le Display Name, puis cliquez sur OK.
Ne créez pas d'AccessKey à ce stade. L'AccessKey sera créé à l'étape 4, une fois l'autorisation terminée.
-
Créez une stratégie personnalisée. Dans la console RAM, accédez à la page et cliquez sur Create Policy. Basculez vers le mode Script Editor, collez le code JSON suivant, puis cliquez sur OK.
chmod 600 ~/.workbench/config.jsonLe tableau suivant décrit l'objet de chaque action (Action) définie dans la stratégie :
Action
Objet
ecs:DescribeInstancesworkbench list ecspermet d'interroger la liste des instances.ecs:DescribeCloudAssistantStatusVérifie l'état de l'agent Cloud Assistant sur l'instance cible.
ecs:StartTerminalSessionÉtablit une session de terminal avec l'instance ECS.
ecs-workbench:LoginECSInstanceConnexion sans mot de passe via le canal Workbench (utilisé par connect, exec, upload et download).
ecs-workbench:ChatMessagesAutorisations requises par l'assistant AI Agent intégré à la session (mode
/agent).ecs-workbench:EndSessionsFerme la session Workbench (appelé par
session closeet par le nettoyage automatique des sessions).ram:CreateServiceLinkedRoleCrée le rôle lié au service Workbench lors de la première utilisation et utilise
Conditionpour restreindre la création au rôle lié au serviceworkbench.ecs.aliyuncs.com.La stratégie ci-dessus accède par défaut à toutes les instances. Pour réduire la portée à des instances spécifiques, utilisez les ARN d'instance uniquement pour les opérations qui prennent en charge l'autorisation au niveau de l'instance, et divisez-les en plusieurs éléments
Statementdistincts si nécessaire afin de modifier le champResource:chmod 600 ~/.workbench/config.jsonRemarqueLes actions
ecs-workbench:ChatMessagesetram:CreateServiceLinkedRolene permettent pas de restreindre la portée par ARN d'instance et doivent conserver la valeur"Resource": "*". Accordez la stratégie à l'utilisateur RAM. Accédez à la page de détails de l'utilisateur RAM créé à l'étape 1 et sélectionnez l'onglet Permissions. Cliquez sur Grant Permission, sélectionnez la stratégie personnalisée créée à l'étape précédente et finalisez l'autorisation. Pour plus d'instructions, consultez la rubrique Gérer les autorisations d'un utilisateur RAM.
-
Créez un AccessKey pour l'utilisateur RAM. Sur la page de détails de l'utilisateur RAM, accédez à l'onglet et cliquez sur Create AccessKey. Sur la page qui s'affiche, sélectionnez Use the AccessKey in the CLI, cochez la case I confirm that I must create an AccessKey, puis cliquez sur Continue. Pour plus d'instructions, consultez la rubrique Créer une paire de clés AccessKey.
ImportantLe secret AccessKey n'est affiché qu'une seule fois, lors de sa création, et ne peut plus être consulté une fois la page fermée. Enregistrez immédiatement l'ID AccessKey et le secret AccessKey dans un gestionnaire de mots de passe ou un keystore. En cas de perte, vous devrez créer une nouvelle paire de clés AccessKey.
Un AccessKey est un identifiant de longue durée ; en cas de fuite, il peut faire l'objet d'un abus prolongé. Dans les environnements de production, basculez vers un mode d'identification à actualisation automatique tel que RamRoleArn dès que vous avez terminé la configuration à l'étape 3. Pour plus de détails, consultez la section Autres méthodes de configuration.
Étape 3 : Configurer la paire de clés AccessKey dans la CLI locale
Exécutez la commande suivante et saisissez l'ID AccessKey ainsi que le secret AccessKey obtenus à l'étape 2 lorsque vous y êtes invité.
chmod 600 ~/.workbench/config.json
Une fois la configuration terminée, les informations d'identification sont enregistrées dans ~/.workbench/config.json et les autorisations du fichier sont automatiquement définies sur 0600 (lecture et écriture réservées à l'utilisateur actuel). Voici un exemple du contenu du fichier :
chmod 600 ~/.workbench/config.json
Exécutez la commande suivante pour vérifier que la connexion fonctionne (remplacez cn-hangzhou par votre région réelle) :
chmod 600 ~/.workbench/config.json
Dans des conditions normales, la liste des instances de la région est renvoyée. Si une erreur telle que InvalidAccessKeyId ou NoPermission s'affiche, consultez la section FAQ.
(Facultatif) Définir la langue de l'interface
Workbench CLI prend en charge le chinois (zh) et l'anglais (en) comme langues d'interface. Par défaut, la langue de l'interface est le chinois. Exécutez la commande suivante pour basculer :
chmod 600 ~/.workbench/config.json
Vous pouvez également définir la langue dans le flux de configuration interactif workbench config ou modifier directement le fichier ~/.workbench/config.json et ajouter le champ language dans le profil correspondant :
chmod 600 ~/.workbench/config.json
Après modification, le changement prend effet lors de la reconnexion. Il n'est pas nécessaire de redémarrer le daemon.
(Facultatif) Gérer plusieurs profils
Si vous devez basculer entre plusieurs comptes Alibaba Cloud ou plusieurs jeux d'informations d'identification, utilisez la fonctionnalité de profil pour éviter de reconfigurer les informations d'identification à chaque fois. Tous les profils sont stockés dans le même fichier ~/.workbench/config.json et le champ current indique le profil actif.
chmod 600 ~/.workbench/config.json
Exemple de fichier config.json contenant plusieurs profils :
chmod 600 ~/.workbench/config.json
Si le fichier de configuration est encore au format plat ancien (sans le champ profiles), la CLI le migre automatiquement vers le nouveau format lors de la première exécution et stocke les informations d'identification existantes dans un profil nommé default. Aucune action manuelle n'est requise.
Autres méthodes de configuration
Une clé d'accès (AccessKey) statique constitue un identifiant à long terme. En cas de fuite, elle peut être exploitée de manière abusive pendant une période prolongée. Dans les environnements de production ou lorsque des exigences de sécurité plus strictes s'appliquent, privilégiez l'une des six autres modes suivants :
|
Mode |
Scénario applicable |
Commande de configuration |
|
AK (étapes 2 à 3 de cette rubrique) |
Clé d'accès statique. Prise en main rapide dans les environnements de développement. |
|
|
StsToken |
Identifiants de sécurité temporaires (paire de clés d'accès et jeton STS). Adapté lorsque vous disposez déjà d'identifiants temporaires STS. |
|
|
RamRoleArn |
Recommandé pour les environnements de production : une clé d'accès aux privilèges limités endosse un rôle RAM aux privilèges élevés, et les identifiants temporaires STS sont actualisés automatiquement. |
|
|
CredentialsCmd |
Obtient dynamiquement les identifiants depuis un programme externe, en s'intégrant au système de distribution d'identifiants ou de gestion des secrets déjà utilisé par votre entreprise. |
|
|
CredentialsURI |
Obtient dynamiquement les identifiants depuis un service HTTP, tel qu'un service de métadonnées ou un sidecar. |
|
|
EcsRamRole |
L'interface CLI s'exécute sur une instance ECS associée à un rôle RAM et obtient automatiquement les identifiants depuis le service de métadonnées de l'instance (IMDS). |
|
|
AliyunCLI |
Réutilise les identifiants déjà configurés dans Alibaba Cloud CLI sur votre machine locale ( |
|
Utiliser des identifiants temporaires STS (StsToken)
Ce mode authentifie directement l'utilisateur à l'aide des identifiants de sécurité temporaires (ID de clé d'accès + secret de clé d'accès + jeton STS) obtenus via STS. Utilisez-le lorsque vous disposez déjà d'identifiants temporaires. Ces derniers possèdent une date d'expiration ; vous devez les reconfigurer après leur expiration. Pour actualiser automatiquement les identifiants, utilisez Utiliser un rôle RAM (RamRoleArn).
Méthode de configuration
chmod 600 ~/.workbench/config.json
Saisissez les éléments suivants dans l'ordre, selon les invites :
Access Key ID : l'ID de clé d'accès temporaire.
AccessKey Secret : le secret de la clé d'accès temporaire.
STS Token : l'identifiant d'accès temporaire.
Aperçu du résultat de la configuration
Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json. Voici un exemple de configuration complète :
chmod 600 ~/.workbench/config.json
Utiliser un rôle RAM (RamRoleArn)
Ce mode convient aux scénarios où une clé d'accès aux privilèges limités est utilisée pour endosser un rôle RAM aux privilèges élevés. L'interface CLI appelle automatiquement STS AssumeRole pour obtenir des identifiants temporaires et les actualise avant leur expiration. Pour plus d'informations sur l'endossement de rôle RAM, consultez la rubrique Endosser un rôle RAM.
Méthode de configuration
chmod 600 ~/.workbench/config.json
Spécifiez les informations suivantes dans l'ordre, selon les invites :
Access Key ID : l'ID de clé d'accès disposant de l'autorisation
AliyunSTSAssumeRoleAccess.Access Key Secret : le secret correspondant à l'ID de clé d'accès.
RAM Role ARN : l'ARN du rôle RAM à endosser (format :
acs:ram::<account-id>:role/<role-name>)Role Session Name : l'identifiant de session, utilisé pour les journaux d'audit (par défaut :
workbench-session).
Aperçu du résultat de la configuration
Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json.
Vous pouvez ajouter des champs avancés (tels que expired_seconds, sts_region et external_id, utilisé pour la prévention des attaques par confusion inter-comptes) en modifiant manuellement le fichier config.json. Pour plus d'informations sur le mécanisme STS, consultez la rubrique Qu'est-ce que STS ?.
Voici un exemple de configuration complète :
chmod 600 ~/.workbench/config.json
Utiliser un identifiant via commande externe (CredentialsCmd)
Ce mode convient aux scénarios où les identifiants sont obtenus dynamiquement via un outil externe, tel que aliyun-zerotrust-credential-provider, ou un script personnalisé. Chaque fois que l'interface CLI nécessite des identifiants, elle exécute la commande configurée et analyse la sortie JSON de celle-ci comme étant les identifiants.
Méthode de configuration
chmod 600 ~/.workbench/config.json
Spécifiez les informations suivantes selon les invites :
-
Process Command — le chemin complet et les paramètres de la commande d'obtention d'identifiants externe. La commande externe doit respecter les exigences suivantes :
Le code de sortie doit être 0. Un code de sortie non nul est considéré comme un échec.
-
La sortie standard doit être au format JSON. Les deux formats suivants sont pris en charge :
Format AK (identifiants statiques) :
chmod 600 ~/.workbench/config.jsonFormat StsToken (identifiants temporaires) :
chmod 600 ~/.workbench/config.json
Exemple 1 : Utiliser aliyun-zerotrust-credential-provider
aliyun-zerotrust-credential-provider est l'interface de ligne de commande zéro confiance d'Alibaba Cloud pour la gestion des identifiants.
chmod 600 ~/.workbench/config.json
Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json. Voici un exemple de configuration complète :
chmod 600 ~/.workbench/config.json
Exemple 2 : Utiliser un script personnalisé
Vous pouvez écrire un script servant de source d'identifiants, à condition qu'il respecte le format de sortie :
chmod 600 ~/.workbench/config.json
Utiliser un URI d'identifiants (CredentialsURI)
Ce mode convient aux scénarios tels qu'un service de distribution d'identifiants auto-géré, le service de métadonnées d'instance ECS ou un endpoint d'identifiants sidecar. L'interface CLI envoie une requête HTTP GET à l'URL configurée pour obtenir dynamiquement des identifiants temporaires et les actualise automatiquement avant leur expiration.
Méthode de configuration
chmod 600 ~/.workbench/config.json
Spécifiez les éléments suivants selon les invites :
-
Credentials URI : l'adresse HTTP/HTTPS du service d'identifiants. La réponse du service d'identifiants doit respecter les exigences suivantes :
Le code d'état de la réponse doit être 200.
-
Le corps de la réponse utilise le format suivant :
chmod 600 ~/.workbench/config.jsonImportantLe champ
Codedoit être exactementSuccess(sensible à la casse). Le champExpirationest au format ISO 8601, et le SDK récupère automatiquement les nouveaux identifiants avant leur expiration.
Aperçu du résultat de la configuration
Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json. Voici un exemple de configuration complète :
chmod 600 ~/.workbench/config.json
Utiliser un rôle RAM d'instance ECS (EcsRamRole)
S'applique aux scénarios où l'interface CLI s'exécute sur une instance ECS Alibaba Cloud et où l'instance possède un rôle RAM attaché. L'interface CLI obtient automatiquement des identifiants STS temporaires directement depuis le service de métadonnées de l'instance (IMDS http://100.100.100.200) et ne nécessite aucune clé d'accès. IMDS actualise automatiquement les identifiants avant leur expiration.
Disponible uniquement sur les instances ECS/ECI Alibaba Cloud. Les environnements non-ECS (machines locales, autres clouds) ne peuvent pas accéder à IMDS, ce qui empêche l'obtention des identifiants avec ce mode. Dans ce cas, utilisez un mode tel que AK, RamRoleArn ou CredentialsURI.
Méthode de configuration
chmod 600 ~/.workbench/config.json
Spécifiez les éléments suivants selon les invites :
RAM Role Name : le nom du rôle RAM attaché à l'instance. Peut être laissé vide. Lorsqu'il est vide, l'interface CLI détecte automatiquement le rôle actuellement attaché à l'instance via IMDS (cohérent avec le comportement optionnel
--ram-role-namede l'interface CLI officielle Alibaba Cloud).IMDSv2 hardening mode (y/n) : la valeur par défaut est
y(active le renforcement IMDSv2). Si l'instance est ancienne et ne prend pas en charge IMDSv2, répondeznpour revenir à IMDSv1.
Une fois la configuration terminée, utilisez les commandes comme d'habitude. La récupération et l'actualisation des identifiants sont entièrement automatiques.
Aperçu du résultat de la configuration
Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json.
Champs du fichier de configuration :
mode: valeur fixeEcsRamRolerole_name(facultatif) : laissez vide pour la détection automatiquedisable_imds_v1(facultatif) : omettre ou définir surtruesignifie renforcement IMDSv2 (par défaut) ;falsesignifie que le retour à IMDSv1 est autorisé
Voici des exemples de configuration complète :
-
Exemple de configuration minimale (détection automatique du rôle + renforcement IMDSv2) :
chmod 600 ~/.workbench/config.json -
Spécifier un nom de rôle et autoriser le retour à IMDSv1 :
chmod 600 ~/.workbench/config.json
Réutiliser les identifiants d'Alibaba Cloud CLI (AliyunCLI)
Lorsqu'Alibaba Cloud CLI est installé et configuré sur votre machine, vous pouvez réutiliser directement sa configuration d'identifiants sans stocker d'ID de clé d'accès ni de secret de clé d'accès distincts dans Workbench.
Prérequis
Alibaba Cloud CLI est installé et configuré (
aliyun configure).Le fichier de configuration se trouve à l'emplacement
~/.aliyun/config.json, ou est spécifié viaALIBABA_CLOUD_CONFIG_FILE. Workbench lit uniquement ce fichier de configuration et n'en modifie pas le contenu.
Les modes Alibaba Cloud CLI tels que AK, StsToken, RamRoleArn, EcsRamRole, OIDC, CloudSSO, OAuth et ChainableRamRoleArn sont pris en charge. Pour les identifiants dynamiques (tels que RamRoleArn), les jetons temporaires Security Token Service sont actualisés automatiquement.
Méthode de configuration
chmod 600 ~/.workbench/config.json
Spécifiez les éléments suivants selon les invites :
aliyun_profile(facultatif) : le nom du profil Alibaba Cloud CLI à réutiliser. Si vous laissez ce champ vide, le profil Alibaba Cloud CLI actuel est utilisé.
Aperçu du résultat de la configuration
Une fois la configuration terminée, vérifiez le résultat en consultant le fichier ~/.workbench/config.json. Voici un exemple de configuration complète :
chmod 600 ~/.workbench/config.json
Mettre à niveau Workbench CLI
Workbench CLI prend en charge la mise à niveau automatique en une étape. Exécutez la commande suivante pour passer à la dernière version :
chmod 600 ~/.workbench/config.json
Le processus de mise à niveau télécharge et vérifie automatiquement le binaire de la dernière version, puis remplace la version actuelle.
Si le binaire est installé dans un répertoire nécessitant des privilèges d'administrateur (par exemple, /usr/local/bin sous Linux ou macOS), utilisez sudo workbench upgrade.
Désinstaller
Workbench CLI n'enregistre aucun service système ni ne modifie les configurations système. Pour le désinstaller, arrêtez le démon, supprimez le binaire et, éventuellement, supprimez le répertoire de configuration local.
Les commandes précédentes nettoient uniquement l'interface CLI locale et les informations d'identification locales. L'utilisateur RAM et la clé AccessKey dans le cloud ne sont pas supprimés. Pour les supprimer également, connectez-vous à la console RAM et supprimez l'utilisateur RAM correspondant ou désactivez la clé AccessKey.
FAQ
La commande workbench renvoie « command not found » après l'installation
Cause : Le répertoire ajouté au PATH par le script d'installation n'est pas pris en compte dans la session shell actuelle.
Solution :
Linux ou macOS : rouvrez le terminal, exécutez
source ~/.bashrc(ou~/.zshrc), ou utilisez le chemin absolu/usr/local/bin/workbench versionpour vérifier.Windows : fermez puis rouvrez la fenêtre PowerShell.
La commande workbench config renvoie une erreur d'autorisation sur le fichier de configuration
Cause : L'interface CLI rejette le fichier ~/.workbench/config.json si ses autorisations sont trop larges (par exemple, 0644 ou accessible en lecture par le groupe) afin d'empêcher les autres utilisateurs de la même machine de lire vos informations d'identification.
Solution : sous Linux ou macOS, exécutez la commande suivante pour corriger les autorisations :
chmod 600 ~/.workbench/config.json
La commande workbench list ecs renvoie InvalidAccessKeyId.NotFound ou IncompleteSignature
Cause : il s'agit généralement de l'une des situations suivantes :
L'ID AccessKey ou la clé secrète AccessKey saisis lors de la configuration sont incorrects (par exemple, ils comportent des espaces au début ou à la fin, ou n'ont pas été copiés intégralement).
La clé AccessKey correspondante a été désactivée ou supprimée dans la console RAM.
Solution : réexécutez workbench config et vérifiez que l'ID AccessKey et la clé secrète AccessKey appartiennent à la même paire, sont complets et ne contiennent aucun espace supplémentaire ; ou confirmez dans la console RAM que le statut de la clé AccessKey est Enabled.
Références
Se connecter à l'aide de Workbench CLI : rubrique parente qui couvre le positionnement de l'outil, la matrice des capacités et le démarrage rapide.
Gérer les instances ECS à l'aide de Workbench CLI : descriptions détaillées de chaque commande et des scénarios courants.
Exploiter les instances ECS avec Workbench CLI dans les agents IA : intégration de Workbench CLI dans les outils de codage IA.
Linux ou macOS
Exécutez les commandes suivantes dans l'ordre :
chmod 600 ~/.workbench/config.json
La troisième commande (qui supprime ~/.workbench) est facultative et permet de supprimer tous les identifiants et fichiers de configuration locaux.
Windows
Exécutez les commandes suivantes dans l'ordre sous PowerShell :
chmod 600 ~/.workbench/config.json
La suppression du répertoire .workbench est facultative et permet de supprimer tous les identifiants et fichiers de configuration locaux.