通過會話管理CLIali-instance-cli）串連執行個體 - Elastic Compute Service

您可以在本機命令列通過會話管理CLI串連到ECS執行個體，支援免密串連無公網執行個體。相比於傳統的SSH或RDP直連的方式更加安全方便。本文為您介紹會話管理CLI的基本使用。

什麼是會話管理CLI？

會話管理CLI，即ali-instance-cli，是阿里雲為您提供的命令列工具，在您的個人電腦上安裝並配置該工具後，即可通過命令列的方式使用會話管理串連執行個體。

此外，在使用ali-instance-cli時，您可以配合使用阿里雲CLI工具，實現純命令列操作，關於阿里雲CLI的更多資訊，請參見什麼是阿里雲CLI。

準備工作

開啟會話管理服務

在使用ali-instance-cli之前，需要先確保當前阿里雲帳號已開啟會話管理服務。開啟會話管理服務僅可以在控制台操作，具體操作如下：

訪問ECS控制台-執行個體。
在頁面左側頂部，選擇目標資源所在的資源群組和地區。
在實例頁面，找到待串連的執行個體，單擊對應操作列的遠端連線。
單擊展開其他登入方式，找到通過會話管理遠端連線，將會話管理已關閉右側的按鈕開啟，並根據介面提示完成開通操作。

檢查執行個體運行狀態是否為運行中

僅支援通過會話管理串連到運行中狀態的執行個體。

控制台

執行個體運行狀態可以在ECS控制台中的執行個體模組查看，運行中的執行個體如圖所示：

查看執行個體狀態的操作說明，請參見查看執行個體資訊。

阿里雲CLI

如果您已經配置好了阿里雲CLI，您可以通過以下命令查詢執行個體運行狀態。關於該API的更多參數說明，請參見DescribeInstanceStatus - 查詢執行個體的狀態資訊列表。

以查詢杭州地區下執行個體ID為i-bp1******執行個體為例，輸入以下命令查詢執行個體運行狀態。

aliyun ecs DescribeInstanceStatus --region cn-hangzhou --RegionId 'cn-hangzhou' --InstanceId.1 'i-bp1******'

如果查詢出對應執行個體的Status為Running則執行個體為運行中。

{
  "TotalCount": 1,
  "RequestId": "A413****-****-****-****-****611B",
  "PageSize": 1,
  "PageNumber": 1,
  "InstanceStatuses": {
    "InstanceStatus": [
      {
        "Status": "Running",
        "InstanceId": "i-bp1******"
      }
    ]
  }
}

除此API外，您還可以通過其他API查詢執行個體運行狀態，請參見DescribeInstances - 查詢執行個體的詳細資料列表。

API

如果需要通過API查詢執行個體運行狀態，請參見DescribeInstanceStatus - 查詢執行個體的狀態資訊列表、DescribeInstances - 查詢執行個體的詳細資料列表。

檢查執行個體雲助手Agent是否已安裝

會話管理雲端式助手的功能實現，您可以通過以下方式查詢執行個體是否已經安裝雲助手Agent。

2017年12月01日之後使用官方公用鏡像建立的ECS執行個體，預設預裝了雲助手Agent。如果您的執行個體是2017年12月01日之前購買的或使用自行上傳的自訂鏡像建立的執行個體，需自行安裝雲助手Agent，請參見安裝雲助手Agent。

控制台

會話管理雲端式助手的功能實現，需要在執行個體中安裝雲助手Agent。雲助手Agent狀態可以在ECS控制台的雲助手模組查看，已經安裝雲助手的執行個體如圖所示：

2017年12月01日之後使用官方公用鏡像建立的ECS執行個體，預設預裝了雲助手Agent。如果您的執行個體是2017年12月01日之前購買的或使用自行上傳的自訂鏡像建立的執行個體，需自行安裝雲助手Agent，請參見安裝雲助手Agent。

查看雲助手Agent狀態以及處理異常狀態的具體操作，請參見查看雲助手狀態及異常狀態處理。

阿里雲CLI

如果您已經配置好了阿里雲CLI，您可以通過以下命令查詢執行個體是否安裝雲助手且雲助手版本是否支援使用會話管理。具體參數說明，請參見DescribeCloudAssistantStatus - 查詢雲助手安裝狀態。

以查詢杭州地區下執行個體ID為i-bp1******執行個體為例，輸入以下命令查詢執行個體運行狀態。

aliyun ecs DescribeCloudAssistantStatus --region cn-hangzhou --RegionId 'cn-hangzhou' --InstanceId.1 'i-bp1******'

如果查詢出CloudAssistantStatus（雲助手運行狀態）為true且SupportSessionManager（是否支援會話管理）也為true，即該執行個體支援通過會話管理串連執行個體。

{
  "TotalCount": 1,
  "PageSize": 1,
  "RequestId": "DB34****-****-****-****-****A749",
  "NextToken": "",
  "PageNumber": 1,
  "InstanceCloudAssistantStatusSet": {
    "InstanceCloudAssistantStatus": [
      {
        "CloudAssistantVersion": "2.2.3.857",
        "SupportSessionManager": true,
        "InstanceId": "i-bp1******",
        "InvocationCount": 4,
        "OSType": "Linux",
        "CloudAssistantStatus": "true",
        "LastHeartbeatTime": "2024-12-10T02:38:04Z",
        "LastInvokedTime": "2024-12-08T16:02:45Z",
        "ActiveTaskCount": 0
      }
    ]
  }
}

API

如果需要通過API查詢執行個體雲助手Agent狀態，請參見DescribeCloudAssistantStatus - 查詢雲助手安裝狀態。

準備用於使用會話管理的RAM使用者的憑證

在使用 ali-instance-cli 工具時，設定階段要求設定RAM使用者的AccessKey、STS Token。當通過會話管理操作串連執行個體時，系統會驗證此憑證對應的RAM使用者是否擁有ecs:StartTerminalSession許可權，這是允許通過會話管理建立與ECS執行個體串連的必要許可權。

此外，在自訂權限原則時，可以通過指定Resource欄位來限定RAM使用者能夠通過會話管理串連的具體ECS執行個體。權限原則樣本如下：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ecs:StartTerminalSession",
      "Resource": "*"
    }
  ]
}

關於CredentialsURI、STS Token的更多說明，請參見建立AccessKey、什麼是STS。

為RAM使用者授權，請參見管理RAM使用者的許可權。

1. 安裝&配置會話管理CLI

說明

如果您已經安裝並配置完成會話管理CLI，可跳過本步驟。

1.1 安裝

首先需要在您的個人電腦中安裝會話管理CLI（ali-instance-cli），不同作業系統安裝方式不同，具體操作如下。

Windows

點擊下載Windows版ali-instance-cli，並儲存到本地檔案夾中。

本文以將ali-instance-cli.exe儲存在C:\Users\test檔案夾中為例。

macOS

在macOS的終端中，輸入以下命令下載mac版ali-instance-cli。

curl -O https://aliyun-client-assist.oss-accelerate.aliyuncs.com/session-manager/mac/ali-instance-cli

下載完成後，輸入以下命令為ali-instance-cli賦予可執行許可權。

chmod a+x ali-instance-cli

Linux

輸入以下命令安裝Linux版ali-instance-cli。

x86架構

curl -O https://aliyun-client-assist.oss-accelerate.aliyuncs.com/session-manager/linux/ali-instance-cli

arm架構

curl -O https://aliyun-client-assist.oss-cn-beijing.aliyuncs.com/session-manager/linux_arm/ali-instance-cli

下載完成後，輸入以下命令為ali-instance-cli賦予可執行許可權。

chmod a+x ali-instance-cli

1.2 配置

在您的個人電腦使用ali-instance-cli串連阿里雲執行個體時，需要配置相關身份憑證，即AccessKey，具體說明，請參見準備用於使用會話管理的RAM使用者的憑證。

Windows

選擇開始 > 運行，輸入cmd，按Enter鍵，開啟命令提示字元視窗。
切換到ali-instance-cli.exe所在目錄，本文以C:\Users\test為例。
```
cd C:\Users\test
```
配置憑證。支援以下三種配置方式：
AccessKey

執行如下命令，並根據介面提示配置Access Key Id、Access Key Secret、Region Id。
```
ali-instance-cli.exe configure --mode AK
```
STS Token

執行以下命令完成配置操作：
```
ali-instance-cli.exe configure set --mode StsToken --region "<region>" --access-key-id "<ak>"  --access-key-secret "<sk>"   --sts-token "<sts_token>"
```
<region>、<ak>、<sk>、<sts_token>要修改為實際的Region ID、AccessKey ID、AccessKey Secret和STS Token。
CredentialsURI

執行如下命令，根據介面提示，輸入Credentials URI和Region Id。
```
ali-instance-cli.exe configure --mode=CredentialsURI
```
配置完成後，顯示如下內容證明配置完成。

macOS/Linux

進入ali-instance-cli所在目錄，本文以目前使用者根目錄~為例。
```
cd ~
```
配置憑證。
AccessKey

執行如下命令，並根據介面提示配置Access Key Id、Access Key Secret、Region Id。
```
./ali-instance-cli configure --mode AK
```
STS Token

執行以下命令完成配置操作：
```
./ali-instance-cli configure set --mode StsToken --region "<region>" --access-key-id "<ak>"  --access-key-secret "<sk>"   --sts-token "<sts_token>"
```
<region>、<ak>、<sk>、<sts_token>要修改為實際的Region ID、AccessKey ID、AccessKey Secret和STS Token。
CredentialsURI

執行如下命令，根據介面提示，配置Credentials URI和Region Id。
```
./ali-instance-cli configure --mode=CredentialsURI
```
配置完成後，顯示如下內容證明配置完成。

2. 通過會話管理串連執行個體

2.1 擷取待串連執行個體的ID

通過會話管理串連執行個體時，需要先擷取到目標執行個體的執行個體ID。

控制台

訪問ECS控制台-執行個體。
在頁面左側頂部，選擇目標資源所在的資源群組和地區。
在實例頁面，找到待串連的執行個體，執行個體ID如圖所示。

阿里雲CLI

如果您已經配置好了阿里雲CLI，您可以通過以下命令擷取執行個體ID。具體參數說明，請參見DescribeInstances - 查詢執行個體的詳細資料列表。

以查詢杭州地區下名稱為SessionManager-example的執行個體為例。

aliyun ecs DescribeInstances --region cn-hangzhou --RegionId 'cn-hangzhou' --InstanceName 'SessionManager-example'

返回結果中InstanceId即執行個體ID。

API

通過API查詢執行個體ID，請參見DescribeInstances - 查詢執行個體的詳細資料列表。

2.2 使用ali-instance-cli的會話管理功能

本機為Windows

進入命令提示字元，在ali-instance-cli.exe所在目錄，輸入命令遠端連線執行個體。其中<instance_id>為步驟2.1中擷取的執行個體ID。

ali-instance-cli.exe session --instance <instance_id>

例如串連執行個體ID為i-bp1******的執行個體時，可輸入以下命令完成串連操作。

ali-instance-cli.exe session --instance i-bp1******

如圖所示，串連成功後，會進入對應執行個體的命令列介面。

本機為macOS/Linux

在終端中，進入ali-instance-cli所在目錄，輸入命令遠端連線執行個體。其中<instance_id>為步驟2.1中擷取的執行個體ID。

./ali-instance-cli session --instance <instance_id>

例如串連執行個體ID為i-bp1******的執行個體時，可輸入以下命令完成串連操作。

./ali-instance-cli session --instance i-bp1******

如圖所示，串連成功後，會進入對應執行個體的命令列介面。

常見問題

執行命令後卡住沒反應（執行個體非運行中狀態）

如果執行ali-instance-cli命令後命令列卡住沒反應，可能是執行個體沒有處於運行中狀態，如何查看執行個體狀態，請參見本文準備工作章節下的檢查執行個體運行狀態是否為運行中。

執行命令後卡住沒反應（安全性群組設定問題）

如果執行ali-instance-cli命令後命令列卡住沒反應，可能是沒有在安全性群組出方向放通對應的連接埠。預設情況下普通安全性群組會在出方向放通所有連接埠的訪問，如果更改了出方向規則或者使用了企業安全性群組，則可能會出現該問題。相關安全性群組說明如下：

通過會話管理串連ECS執行個體時，需要確保ECS中啟動並執行雲助手Agent與雲助手服務端的網路連通性，即在安全性群組出方向設定以下規則：

與SSH、RDP等串連方式不同，由於會話管理是由雲助手Agent主動與會話管理服務端建立WebSocket串連，因此僅需允許存取出方向的雲助手服務端的WebSocket連接埠。關於會話管理的原理，請參見會話管理工作原理。

重要

如果使用普通安全性群組（包括預設安全性群組），預設情況下會允許存取所有的出方向流量，無需配置。
如果使用企業安全性群組，預設情況下會禁用所有出方向的流量，需要配置以下規則。更多關於企業安全性群組的說明，請參見普通安全性群組與企業級安全性群組。

添加安全性群組規則的具體操作，請參見添加安全性群組規則。

授權策略	優先順序	協議類型	連接埠範圍	授權對象	描述
允許	1	自訂TCP	443	`100.100.0.0/16`	用於訪問雲助手服務端。
允許	1	自訂TCP	443	`100.0.0.0/8`	訪問雲助手Agent安裝包所在伺服器，用於安裝或更新雲助手Agent。
允許	1	自訂UDP	53	`0.0.0.0/0`	用於解析網域名稱。

此外，如果計劃僅通過會話管理串連執行個體，為了增加ECS執行個體的安全性，可以取消允許存取安全性群組入方向上的SSH連接埠（預設22）或者RDP連接埠（預設3389）的規則。

執行命令後出現DeliveryTimeout提示（雲助手Agent不線上）

如圖所示，如果執行ali-instance-cli的命令時出現DeliveryTimeout提示，可能是雲助手Agent不線上，檢查雲助手狀態，請參見檢查執行個體雲助手Agent是否已安裝。

執行命令報錯session manager is disabled, please enable first

如果執行ali-instance-cli的命令出現session manager is disabled, please enable first報錯，代表會話管理功能未開啟，請通過控制台開啟會話管理功能，具體操作，請參見開啟會話管理服務。

長時間未串連自動斷開

使用會話管理串連到目標執行個體後，如果長時間沒有任何操作串連會自動斷開。預設的串連空閑時間為3分鐘，可以通過--idle-timeout參數自訂最大空閑時間。

例如執行以下命令串連到目標執行個體後，串連空閑達到10分鐘就會自動斷開。

./ali-instance-cli session --instance instance-id --idle-timeout 600

說明

此功能需確保ali-instance-cli不低於以下版本：

Linux：1.2.0.48
Windows：1.1.0.48
macOS：1.3.0.48

如何分析ali-instance-cli的日誌

當使用會話管理CLI出現問題時，可以通過查看log分析具體問題。

查看會話管理CLI工具的日誌：在使用會話管理CLI（ali-instance-cli）時，會在該工具所在目錄下產生log目錄，如~/log/aliyun_ecs_session_log.2022XXXX，可以進入該目錄查看相關日誌。

查看雲助手Agent日誌：

Linux

/usr/local/share/aliyun-assist/雲助手版本號碼/log/

Windows

C:\ProgramData\aliyun\assist\雲助手版本號碼\log

什麼是會話管理CLI？

準備工作

開啟會話管理服務

檢查執行個體運行狀態是否為運行中

控制台

阿里雲CLI

API

檢查執行個體雲助手Agent是否已安裝

控制台

阿里雲CLI

API

準備用於使用會話管理的RAM使用者的憑證

1. 安裝&配置會話管理CLI

1.1 安裝

Windows

macOS

Linux

x86架構

arm架構

1.2 配置

Windows

AccessKey

STS Token

CredentialsURI

macOS/Linux

AccessKey

STS Token

CredentialsURI

2. 通過會話管理串連執行個體

2.1 擷取待串連執行個體的ID

控制台

阿里雲CLI

API

2.2 使用ali-instance-cli的會話管理功能

本機為Windows

本機為macOS/Linux

更多功能

常見問題

執行命令後卡住沒反應（執行個體非運行中狀態）

執行命令後卡住沒反應（安全性群組設定問題）

執行命令後出現DeliveryTimeout提示（雲助手Agent不線上）

執行命令報錯session manager is disabled, please enable first

長時間未串連自動斷開

如何分析ali-instance-cli的日誌