使用串行控制台进行问题排查

此页面介绍如何启用对实例串行控制台的交互式访问，以调试启动和网络问题、排查实例故障、与 GRand Unified Bootloader (GRUB) 交互以及执行其他问题排查任务。

虚拟机 (VM) 实例具有四个虚拟串行端口。与串行端口交互类似于使用终端窗口，因为输入和输出完全在文本模式下进行，并且没有图形界面或鼠标支持。实例的操作系统、BIOS 以及其他系统级实体通常将输出写入串行端口，并且可以接受输入，例如命令或提示的答案。这些系统级实体通常使用第一个串行端口（端口 1），该端口通常称为串行控制台。

如果您只需要查看串行端口输出，而不需要向串行控制台发出任何命令，则可以调用 getSerialPortOutput 方法或使用 Cloud Logging 读取您的实例已写入其串行端口的信息；具体请参阅查看串行端口日志。但是，如果您在通过 SSH 访问实例时遇到问题，或者需要对未完全启动的实例进行问题排查，您可以启用对串行控制台的交互式访问，从而连接到您的实例的任何串行端口并与其交互。例如，您可以通过串行端口直接运行命令并响应提示。

启用或停用串行端口时，您可以使用元数据服务器所能接受的任何布尔值。如需了解详情，请参阅布尔值。

准备工作

• 设置身份验证（如果尚未设置）。身份验证是通过其进行身份验证以访问 Google Cloud 服务和 API 的过程。如需从本地开发环境运行代码或示例，您可以按如下方式向 Compute Engine 进行身份验证。
  

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

  2. Set a default region and zone.

  REST

  如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭据。

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

启用对串行控制台的交互式访问权限

为单个虚拟机实例或整个项目启用交互式串行控制台访问。

针对项目启用访问

如果您对某个项目启用交互式串行控制台访问，则会同时对该项目下的所有虚拟机实例启用这一访问。

默认情况下，交互式串行端口访问权限处于停用状态。您也可以通过将 serial-port-enable 键设置为 FALSE 来明确停用这项访问权限。对于这两种情况，任何针对个别实例的设置都将替换项目级的设置或默认设置。

gcloud compute project-info add-metadata \
    --metadata serial-port-enable=TRUE

{
 "fingerprint": "FikclA7UBC0=",
 "items": [
  {
   "key": "serial-port-enable",
   "value": "TRUE"
  }
 ]
}

针对虚拟机实例启用访问权限

针对特定实例启用交互式串行控制台访问权限。基于个别实例的设置（如果存在）会替换任何项目级的设置。也就是说，即使您在项目级启用了访问权限，也可以通过将 serial-port-enable 设置为 FALSE（而非 TRUE）来针对特定实例停用访问权限。同样，即使您明确或默认针对项目停用了访问权限，也仍然可以针对一个或多个实例启用访问权限。

gcloud compute instances add-metadata instance-name \
    --metadata serial-port-enable=TRUE

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata
{
 "fingerprint": "zhma6O1w2l8=",
 "items": [
  {
   "key": "serial-port-enable",
   "value": "TRUE"
  }
 ]
}

为裸金属实例配置串行控制台

对于裸机实例，请将串行控制台的比特率（也称为波特率）提高到 115,200 bps（约 11.5kB/秒）。使用较低的速度会导致控制台输出内容乱码或缺失。

引导加载程序配置因操作系统和操作系统版本而异。如需相关说明，请参阅操作系统发行方的文档。

如果要在命令行中为当前会话修改比特率，请使用类似如下的命令：

console=ttyS0,115200

如果要修改 GRUB 配置，请使用类似如下的命令：

serial --speed=115200

请确保更新实际的引导加载程序配置。可以使用 update-grub、grub2-mkconfig 或类似的命令来执行此操作。

连接到串行控制台

Compute Engine 为每个 Google Cloud 区域提供区域串行控制台网关。为虚拟机的串行控制台启用交互式访问权限后，您可以连接到区域串行控制台。

串行控制台使用 SSH 密钥对用户进行身份验证。具体而言，您必须将 SSH 公钥添加到项目或实例元数据中，并将私钥存储在您要建立连接的来源本地机器上。gcloud CLI 和 Google Cloud 控制台会自动为您将 SSH 密钥添加到项目中。如果您使用的是第三方客户端，则可能需要手动添加 SSH 密钥。

  gcloud compute connect-to-serial-port VM_NAME 

      --port=PORT_NUMBER
  

与串行控制台断开连接

如需断开与串行控制台的连接，请执行以下操作：

1. 按 ENTER 键。
2. 输入 ~.（即依次输入波浪号和英文句点）。

输入 ~? 或查看 SSH 的手册页，您可以发现其他命令：

man ssh

请勿尝试使用以下任何方法断开连接：

• CTRL+ALT+DELETE 组合键或其他类似组合键。因为串行控制台无法识别 PC 键盘组合，所以组合键不起作用。

• exit 或 logout 命令。因为客机无法感知任何网络或调制解调器连接，所以此方法也不起作用。使用此命令只会使控制台关闭然后再重新打开，而您的会话仍然保持连接。如果您要为会话启用 exit 和 logout 命令，设置 on-dtr-low 选项即可。

使用登录提示连接到串行控制台

如果您尝试排查已完全启动的虚拟机的问题，或者尝试排查虚拟机启动已进入单用户模式后发生的问题，系统可能会在您尝试访问串行控制台时提示您输入登录信息。

默认情况下，不会将 Google 提供的 Linux 系统映像配置为允许本地用户使用密码登录。但是，Google 提供的 Windows 映像配置为允许本地用户使用密码登录。

如果您的虚拟机正在运行预先配置了串行端口登录的映像，您需要在虚拟机上设置本地密码，以便在出现提示时可以登录串行控制台。您可以在连接到虚拟机或使用启动脚本后设置本地密码。

使用启动脚本设置本地密码

您可以使用启动脚本来设置本地密码，以便在创建虚拟机期间或之后连接到串行控制台。

以下说明介绍如何在创建虚拟机后设置本地密码。

1. 在 Google Cloud 控制台中，转到虚拟机实例页面。

   转到虚拟机实例

2. 选择要添加本地密码的虚拟机。

3. 点击修改。

   Linux

   1. 转到元数据 > 自动化部分。

   2. 如果虚拟机已有启动脚本，请复制该脚本并粘贴到安全的位置。

   3. 添加以下启动脚本：

      #!/bin/bash
      useradd USERNAME
      echo USERNAME:PASSWORD | chpasswd
      usermod -aG google-sudoers USERNAME
      

      替换以下内容：

      • USERNAME：您要添加的用户名
      • PASSWORD：用户名的密码。避免使用简单的密码，因为某些操作系统可能对密码长度和复杂度有最低要求。

   Windows

   1. 进入到自定义元数据部分。
   2. 如果虚拟机已有启动脚本，请复制该脚本并粘贴到安全的位置。
   3. 点击 Add item（添加项目）。
   4. 在密钥字段中，输入 windows-startup-script-cmd。

   5. 在值字段中，输入以下脚本：

      net user USERNAME PASSWORD /ADD /Y
      net localgroup administrators USERNAME /ADD
      

      替换以下内容：

      • USERNAME：您要添加的用户名
      • PASSWORD：用户名的密码

4. 点击保存。

5. 如需重新启动虚拟机，请点击重置。如需了解详情，请参阅重置虚拟机。

6. 连接到串行控制台。

7. 出现提示时输入您的登录信息。

8. 在创建用户后从虚拟机移除启动脚本。

在虚拟机上使用 passwd 设置本地密码

以下说明介绍如何在虚拟机上为用户设置本地密码，以便用户可以使用指定的密码登录该虚拟机的串行控制台。

1. 连接到虚拟机。 将 instance-name 替换为您的实例名称。

   gcloud compute ssh instance-name

2. 在虚拟机上，使用以下命令创建本地密码。这样做将为您当前登录的用户设置密码。

   sudo passwd $(whoami)

3. 按照提示创建密码。

4. 接下来，退出该实例并连接到串行控制台。

5. 出现提示时输入您的登录信息。

在其他串行端口上设置登录

默认情况下，大多数 Linux 操作系统会在端口 1 上启用登录提示。 但是，端口 1 通常会因日志记录数据以及输出到该端口的其他信息而不堪重负。您也可以选择在其他端口（例如端口 2 (ttyS1)）上启用登录提示，方法是在您的虚拟机上执行下列命令之一。您可以在了解串行端口编号中查看虚拟机的可用端口列表。

下表列出了预配置有串行控制台登录和默认端口的映像。

如需在其他串行端口上启用登录提示，请按照以下说明进行操作。

 sudo sed -i~ -e 's/^#T([01])/T\1/' /etc/inittab
 sudo telinit q

了解串行端口编号

每个虚拟机实例都有四个串行端口。为了与 getSerialPortOutput API 保持一致，系统会将各个端口编号为 1 到 4。Linux 和其他类似系统会将其串行端口编号为 0 到 3。例如，在许多操作系统映像中，对应设备为 /dev/ttyS0 到 /dev/ttyS3。Windows 会将串行端口编号为 COM1 到 COM4。如需连接到在 Windows 中编号为 COM3 而在 Linux 中编号为 ttyS2 的端口，应指定端口 3。使用下表帮助您确定要连接的端口。

请注意，许多 Linux 映像都使用端口 1 (/dev/ttyS0) 记录来自内核和系统程序的消息。

发送串行中断

无论系统状态如何，Magic SysRq 组合键功能都可让您执行低层级任务。例如，您可以使用 Magic SysRq 组合键功能同步文件系统、重新启动实例、终止进程、卸载文件系统。

如需使用模拟串行中断发送 Magic SysRq 命令，请执行以下操作：

1. 按 ENTER 键。
2. 输入 ~B（即依次输入波浪号和大写的 B）。
3. 输入 Magic SysRq 命令。

查看串行控制台审核日志

Compute Engine 提供审核日志以跟踪与实例的串行控制台连接和断开连接的用户。要查看日志，您需要具有日志查看器的权限，或者具有项目查看者或编辑者身份。

1. 在 Google Cloud 控制台中，转到 Logs Explorer 页面。

   转到 Logs Explorer

2. 展开下拉菜单，然后选择 GCE VM 实例。
3. 在搜索栏中，输入 ssh-serialport.googleapis.com，然后按 Enter 键。

4. 此时会显示审核日志列表。这些日志记录了与串行控制台连接和断开连接的情况。展开任一条目即可了解详情：

   

对于任何审核日志，您可以执行以下操作：

1. 展开 protoPayload 属性。
2. 查找 methodName 以查看此日志适用的活动（连接或断开连接请求）。例如，如果此日志跟踪与串行控制台断开连接的情况，则方法名称会显示为 "google.ssh-serialport.v1.disconnect"。同样地，连接日志会显示为 "google.ssh-serialport.v1.connect"。串行控制台上的每个会话开始和结束时，系统都会记录审核日志条目。

不同的日志类型有不同的审核日志属性。例如，与连接相关的审核日志具有连接日志的特定属性，而断开连接的审核日志则具有其特定的属性集。还有一些审核日志属性同时适用于这两种日志类型。

所有串行控制台日志

下表提供了所有串行控制台日志的审核日志属性及其值：

连接日志

下表提供了特定于连接日志的审核日志属性及其值：

断开连接日志

下表提供了特定于断开连接日志的审核日志属性及其值：

失败的连接日志

连接失败时，Compute Engine 会创建审核日志条目。失败的连接日志看起来与成功的连接条目非常相似，但具有以下指示连接失败的属性。

停用交互式串行控制台访问

可以通过以下两种方式停用交互式串行控制台访问：更改特定实例或项目上的元数据；设置组织政策，停用对组织中一个或多个项目的所有虚拟机实例的交互式串行控制台访问。

在特定实例或项目中停用交互式串行控制台

项目所有者和编辑者以及已被授予 compute.instanceAdmin.v1 角色的用户可以通过更改特定实例或项目的元数据，来停用对串行控制台的访问权限。与启用串行控制台访问权限类似，即是将 serial-port-enable 元数据设置为 FALSE：

serial-port-enable=FALSE

例如，使用 Google Cloud CLI，您可以将此元数据应用于特定实例，如下所示：

gcloud compute instances add-metadata instance-name \
    --metadata=serial-port-enable=FALSE

要将元数据应用于项目，请执行以下命令：

gcloud compute project-info add-metadata \
    --metadata=serial-port-enable=FALSE

通过组织政策停用交互式串行控制台访问

如果您已被授予组织的 orgpolicy.policyAdmin 角色，则无论元数据服务器是否启用了交互式串行控制台访问权限，您都可以通过设置组织政策来阻止对串行控制台的交互式访问。设置组织政策后，该政策会有效地替换 serial-port-enable 元数据键，且组织或项目的所有用户都将无法启用交互式串行控制台访问权限。默认情况下，此限制设置为 FALSE。

停用交互式串行控制台访问权限的限制如下：

compute.disableSerialPortAccess

请按照以下说明在组织中设置此政策。设置政策后，您可以针对单个项目授予豁免。

gcloud resource-manager org-policies enable-enforce \
    --organization organization-id compute.disableSerialPortAccess

 POST https://cloudresourcemanager.googleapis.com/v1/organization-name:setOrgPolicy

"constraint": "constraints/compute.disableSerialPortAccess"

 {
   "policy":
   {
     "booleanPolicy":
     {
       "enforced": TRUE
     },
     "constraint": "constraints/compute.disableSerialPortAccess"
   }
 }
 

该政策会立即生效，因此组织下的所有项目都会立即禁止对串行控制台的交互式访问。

如需暂时停用该政策，请使用 disable-enforce 命令：

gcloud resource-manager org-policies disable-enforce \
    --organization organization-id compute.disableSerialPortAccess

或者，您可以发出 API 请求（在请求正文中将 enforced 参数设置为 FALSE）：

{
  "policy":
  {
    "booleanPolicy":
    {
      "enforced": FALSE
    },
    "constraint": "constraints/compute.disableSerialPortAccess"
  }
}

在项目级层设置组织政策

您可以基于每个项目设置相同的组织政策。这将替换组织级设置。

gcloud resource-manager org-policies disable-enforce \
    --project project-id compute.disableSerialPortAccess

POST https://cloudresourcemanager.googleapis.com/v1/projects/project-id:setOrgPolicy

"constraint": "constraints/compute.disableSerialPortAccess"

{
  "policy":
  {
    "booleanPolicy":
    {
      "enforced": FALSE
    },
    "constraint": "constraints/compute.disableSerialPortAccess"
  }
}

提示和技巧

• 如果您在使用标准 SSH 客户端进行连接时遇到问题，但 gcloud compute connect-to-serial-port 连接成功，则建议您运行带有 --dry-run 命令行选项的 gcloud compute connect-to-serial-port 命令，以查看代表您运行的 SSH 命令，并将选项与您正在使用的命令进行比较。

• 设置比特率（也称为波特率）：您可以设置任何所需的比特率（例如 stty 9600），但该功能通常会将有效速率强制设置为 115200 bps（约 11.5kB/秒）。这是因为许多公共映像都会在串行控制台上默认采用较慢的比特率（例如 9600），并且会缓慢启动。

• 某些操作系统映像的串行端口默认值不方便使用。例如，在 CentOS 7 上，控制台中 Enter 键的默认值 stty icrnl 会发送 CR，也就是 ^M。而由于 bash shell 的掩盖，只有在您尝试设置密码，却发现操作在 password: 提示符出现后就停止不动时，才会察觉这一情况。

• 如果您以某种特定方式将 shell 连接到端口，有些公共映像会默认停用一些作业控制键。这些键的示例包括 ^Z 和 ^C。setsid 命令可能会解决这个问题。如果不能的话，当您看到 job control is disabled in this shell 消息时，请注意不要运行需要您输入中断的命令。

• 建议告知系统您正在使用的窗口大小，以便 bash 和编辑器可以妥善管理该窗口。否则，您可能会遇到奇怪的显示行为，因为 bash 或编辑器会尝试根据对可用行数和列数的错误假设来操控显示。使用 stty rows Y cols X 命令和 stty -a 标志查看设置。例如：stty rows 60 cols 120（如果您的窗口是 120 个字符乘 60 行）。

• 例如，如果您使用 SSH 从机器 A 连接到机器 B，然后再连接到机器 C，从而创建嵌套式 SSH 会话，并且您希望使用波浪号 (~) 命令来执行断开连接或发送串行中断信号等操作，则需要在命令中额外添加足够的波浪号 (~) 字符才能连接至正确的 SSH 客户端。机器 A 上的 SSH 客户端会解释单个波浪号后面的命令；机器 B 上的客户端则解释连续两个波浪号 (Enter~~) 后面的命令，依此类推。您只需要按一次 Enter，因为该输入会一直传到最内层的 SSH 目的地。使用任何提供波浪号转义功能的 SSH 客户端都是如此。

  如果您忘记了所需的波浪号字符数，请按 Enter 键，然后逐个输入波浪号字符，直到实例回显波浪号为止。此回显表明您已到达链尾，此时您就知道了如果要向最深层的嵌套 SSH 客户端发送波浪号命令，需要输入的波浪号要比刚才输入的次数少一个。

高级选项

您还可以将以下高级选项与串行端口搭配使用。

控制连接数上限

您可以设置 max-connections 属性来控制此串行端口一次可拥有的并发连接数。连接数的默认值和上限均为 5。例如：

gcloud compute connect-to-serial-port instance-name \
    --port port-number \
    --extra-args max-connections=3

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.max-connections=3@ssh-serialport.googleapis.com

设置重放选项

默认情况下，每次连接到串行控制台时，无论其他 SSH 客户端是否已看到最后 10 行，您都将收到最后 10 行数据的重放。通过设置以下选项，您可以更改此设置并控制返回的行数与行内容：

• replay-lines=N：将 N 设置为您要重放的行数。例如，如果 N 为 50，则会包含控制台输出的最后 50 行内容。
• replay-bytes=N：重放最新的 N 个字节。您还可以将 N 设置为 new，以重放尚未发送到任何客户端的所有输出。
• replay-from=N：从您提供的绝对字节索引开始重放输出。您可以通过发出 getSerialPortOutput 请求来获取串行控制台输出的当前字节索引。如果您设置了 replay-from，则其他所有重放选项都会被忽略。

使用 Google Cloud CLI，将以下内容附加到 connect-to-serial-port 命令，其中 N 是指定的行数（或字节数或绝对字节索引，具体取决于您选择的重放选项）：

--extra-args replay-lines=N

如果您使用的是第三方 SSH 客户端，请在 SSH 命令中提供此选项：

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.replay-lines=N@ssh-serialport.googleapis.com

您还可以使用这些选项的组合。例如：

replay-lines=N 和 replay-bytes=new

重放指定的行数或重放之前未发送到任何客户端的所有输出，以较大者为准。第一个连接此标志组合的客户端将看到已发送到串行端口的所有输出，后续连接的客户端将只看到最后 N 行。示例：

gcloud compute connect-to-serial-port instance-name--port port-number --extra-args replay-lines=N,replay-bytes=new

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.replay-lines=N.replay-bytes=new@ssh-serialport.googleapis.com

replay-lines=N 和 replay-bytes=M

重放的行数不超过这些标志所描述的行数或字节数（以较小者为准）。此选项不会重放超过 N 行或 M 个字节。

gcloud compute connect-to-serial-port instance-name--port port-number --extra-args replay-lines=N,replay-bytes=M

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.replay-lines=N.replay-bytes=M@ssh-serialport.googleapis.com

处理已丢弃的输出

每个串行端口的最新 1 MiB 输出始终可用，且您的 SSH 客户端通常不应丢失串行端口中的任何输出。 如果由于某种原因，您的 SSH 客户端在一段时间内停止接受输出但并未断开连接，并且产生超过 1 MiB 的新数据，则您的 SSH 客户端可能会丢失部分输出。如果您的 SSH 客户端接受数据的速度不够快，无法与串行控制台端口上的输出保持同步，您可以设置 on-dropped-output 属性来确定控制台的行为方式。

使用此属性设置以下任何适用选项：

• insert-stderr-note：在 SSH 客户端的 stderr 上插入一条注释，指示输出已被丢弃。这是默认选项。
• ignore：静默地丢弃输出并且不执行任何操作。
• disconnect：停止连接。

例如：

gcloud compute connect-to-serial-port instance-name \
    --port port-number \
    --extra-args on-dropped-output=ignore

ssh -i private-ssh-key-file -p 9600 project-id.zone.instance-name.username.on-dropped-output=ignore@ssh-serialport.googleapis.com

启用通过 exit 或 logout 命令断开连接的功能

当您连接到串行控制台时，可以通过将 on-dtr-low 属性设置为 disconnect 来允许使用 exit 或 logout 命令来断开连接。

在 Google Cloud CLI 中，将以下标志附加到 connect-to-serial-port 命令：

--extra-args on-dtr-low=disconnect

如果您使用的是第三方 SSH 客户端，请在 SSH 命令中提供此选项：

ssh -i private-ssh-key-file -p 9600 myproject.us-central1-f.example-instance.jane.port=3.on-dtr-low=disconnect@ssh-serialport.googleapis.com

在您重新启动实例时，启用 disconnect 选项可能会导致实例一次或多次断开连接，因为操作系统会在启动时重置串行端口。

on-dtr-low 选项的默认设置为 none。如果使用默认设置 none，您可以在不断开与串行控制台连接的情况下重新启动您的实例，但控制台不会通过一般方式（例如 exit 或 logout 命令）或一般组合键（如 Ctrl+D）断开连接。

后续步骤

• 详细了解 getSerialPortOutput API。
• 了解如何保留和查看串行端口输出（即使在虚拟机实例被删除之后）。
• 详细了解问题排查提示。
• 详细了解如何应用元数据。
• 了解 SSH 密钥。