全部产品
Search

搜索本产品

    云服务器 ECS：通过会话管理CLI（ali-instance-cli）连接实例

    文档中心

    云服务器 ECS：通过会话管理CLI（ali-instance-cli）连接实例

    更新时间：Dec 17, 2024

    您可以在本机命令行通过会话管理CLI连接到ECS实例，支持免密连接无公网实例。相比于传统的SSH或RDP直连的方式更加安全方便。本文为您介绍会话管理CLI的基本使用。

    什么是会话管理CLI？

    会话管理CLI，即ali-instance-cli，是阿里云为您提供的命令行工具，在您的个人计算机上安装并配置该工具后，即可以命令行的方式通过会话管理连接实例。

    此外，在使用ali-instance-cli时， 您可以配合使用阿里云CLI工具，实现纯命令行操作，关于阿里云CLI的更多信息，请参见什么是阿里云CLI。

    准备工作

    开启会话管理服务

    在使用ali-instance-cli之前，需要先确保当前阿里云账号已开启会话管理服务。开启会话管理服务仅可以在控制台操作，具体操作如下：

    1. 登录ECS管理控制台。

    2. 在左侧导航栏，选择实例与镜像 > 实例。

    3. 在页面左侧顶部，选择目标资源所在的资源组和地域。

    4. 在实例页面，找到待连接的实例，单击对应操作列的远程连接。

    image

    1. 单击展开其他登录方式。

    2. 找到通过会话管理远程连接，将会话管理已关闭右侧的按钮打开，并根据界面提示完成开通操作。

    image

    image

    检查实例运行状态是否为运行中

    仅支持通过会话管理连接到运行中状态的实例。

    控制台

    实例运行状态可以在ECS控制台中的实例模块查看，运行中的实例如图所示：

    查看实例状态的操作说明，请参见查看实例信息。

    image

    image

    阿里云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。

    image

    image

    查看云助手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。

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

    下载完成后，输入以下命令为ali-instance-cli赋予可执行权限。

    chmod a+x ali-instance-cli

    1.2 配置

    在您的个人计算机使用ali-instance-cli连接阿里云实例时，需要配置相关身份凭证，即AccessKey，具体说明，请参见准备用于使用会话管理的RAM用户的凭证。

    Windows

    1. 选择开始 > 运行，输入cmd，按Enter键，打开命令提示符窗口。

    2. 切换到ali-instance-cli.exe所在目录，本文以C:\Users\test为例。

      cd C:\Users\test

    3. 配置凭证。支持以下三种配置方式：

      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

      配置完成后，显示如下内容证明配置完成。

      image

    macOS/Linux

    1. 进入ali-instance-cli所在目录，本文以当前用户根目录~为例。

      cd ~

    2. 配置凭证。

      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

      配置完成后，显示如下内容证明配置完成。

      image

    2. 通过会话管理连接实例

    2.1 获取待连接实例的ID

    通过会话管理连接实例时，需要先获取到目标实例的实例ID。

    控制台

    1. 登录ECS管理控制台。

    2. 在左侧导航栏，选择实例与镜像 > 实例。

    3. 在页面左侧顶部，选择目标资源所在的资源组和地域。

    4. 在实例页面，找到待连接的实例，实例ID如图所示。

    image

    阿里云CLI

    如果您已经配置好了阿里云CLI，您可以通过以下命令获取实例ID。具体参数说明，请参见DescribeInstances - 查询实例的详细信息列表。

    以查询杭州地域下名称为SessionManager-example的实例为例。
    aliyun ecs DescribeInstances --region cn-hangzhou --RegionId 'cn-hangzhou' --InstanceName 'SessionManager-example'

    返回结果中InstanceId即实例ID。

    image

    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******

    如图所示，连接成功后，会进入对应实例的命令行界面。

    image

    本机为macOS/Linux

    在终端中，进入ali-instance-cli所在目录，输入命令远程连接实例。其中<instance_id>为步骤2.1中获取的实例ID。

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

    例如连接实例ID为i-bp1******的实例时，可输入以下命令完成连接操作。

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

    如图所示，连接成功后，会进入对应实例的命令行界面。

    image

    更多功能

    除了会话管理功能外，会话管理CLI（ali-instance-cli）还有以下功能：

    • 访问无公网的实例（端口转发实现）

      您可以通过ali-instance-cli的端口转发功能，将实例的某个端口映射到您个人计算机的某个端口，支持无公网实例。由此功能，您可以实现免代理，免跳板机的访问无公网实例上的服务。

    • 注册临时SSH公钥

      如果您使用SSH连接实例，您可以选择通过该功能向目标实例中注册临时公钥，此时，您可以通过与之对应的私钥连接实例。

    常见问题

    执行命令后卡住没反应（实例非运行中状态）

    如果执行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是否已安装。

    image

    image

    执行命令报错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