排查 EC2Launch v2 代理的问题 - Amazon Elastic Compute Cloud
常见场景Windows 事件日志EC2Launch v2 控制台日志输出
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

排查 EC2Launch v2 代理的问题

本节介绍 EC2Launch v2 的常见故障排除场景以及有关查看 Windows 事件日志及控制台日志输出和消息的信息。

常见故障排除场景

本节介绍常见的故障排除场景和解决步骤。

服务无法设置壁纸

解决方案

  1. 确保存在 %AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk 。

  2. 检查 %ProgramData%\Amazon\EC2Launch\log\agent.log 是否发生任何错误。

服务无法运行用户数据

可能的原因：服务可能在运行用户数据之前失败。

解决方案

  1. 检查 %ProgramData%\Amazon\EC2Launch\state\previous-state.json。

  2. 查看 boot、network、preReady 和 postReadyLocalData 是否全部标记为成功。

  3. 如果其中一个阶段失败，请检查 %ProgramData%\Amazon\EC2Launch\log\agent.log 中的具体错误。

服务只运行一次任务

解决方案

  1. 检查任务的频率。

  2. 如果服务已在 Sysprep 之后运行，并且任务频率设置为 once，则该任务不会再次运行。

  3. 如果您希望任务在每次运行 EC2Launch v2 时运行，请将任务的频率设置为 always。

服务无法运行任务

解决方案

  1. 检查 %ProgramData%\Amazon\EC2Launch\log\agent.log 中的最新条目。

  2. 如果没有发生错误，请尝试从 "%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run 手动运行服务以查看任务是否成功。

服务多次运行用户数据

解决方案

用户数据在 EC2Launch v1 和 EC2Launch v2 之间的处理方式不同。将 persist 设置为 true 时，EC2Launch v1 在实例上将用户数据作为计划任务运行。如果 persist 设置为 false，则即使重新启动后退出或运行时中断，也不会计划该任务。

EC2Launch v2 将用户数据作为代理任务运行并跟踪其运行状态。如果用户数据发出计算机重启或用户数据在运行时中断，则运行状态将保持不变，pending 并且用户数据将在下次实例启动时再次运行。如果要阻止用户数据脚本多次运行，请使脚本具有幂等性。

以下示例幂极脚本设置计算机名称并加入域。

<powershell>
  $name = $env:computername
  if ($name -ne $desiredName) {
	Rename-Computer -NewName $desiredName
  }
  $domain = Get-ADDomain
  if ($domain -ne $desiredDomain) 
  {
	Add-Computer -DomainName $desiredDomain
  }
  $telnet = Get-WindowsFeature -Name Telnet-Client
  if (-not $telnet.Installed)
  {
	Install-WindowsFeature -Name "Telnet-Client"
  }
</powershell>
<persist>false</persist>

EC2Launch v1 中的计划任务在迁移到 EC2Launch v2 后无法运行

解决方案

迁移工具不会检测任何链接到 EC2Launch v1 脚本的计划任务；因此，它不会在 EC2Launch v2 中自动设置这些任务。要配置这些任务，请编辑 agent-config.yml 文件或使用 EC2Launch v2 设置对话框。例如，如果实例的计划任务正在运行 InitializeDisks.ps1，则在运行迁移工具之后，您必须在 EC2Launch v2 设置对话框中指定要初始化的卷。请参阅 使用 EC2Launch v2 设置对话框更改设置 程序的步骤 6。

服务初始化不为空的 EBS 卷

解决方案

在初始化卷之前，EC2Launch v2 会尝试检测该卷是否为空。如果卷不为空，则会跳过初始化。不初始化任何检测到不为空的卷。如果卷的前 4 KiB 为空，或者卷没有 Windows 可识别的驱动器布局，则该卷被视为空。在 Linux 系统上初始化和格式化的卷没有 Windows 可识别的驱动程序布局，例如 MBR 或 GPT。因此，它将被视为空并已初始化。如果要保留此数据，请不要依赖 EC2Launch v2 空驱动器检测。相反，请指定要在 EC2Launch v2 设置对话框（请参阅步骤 6）或 agent-config.yml 中初始化的卷。

setWallpaper 任务未启用，但壁纸会在重新启动时重置

setWallpaper 任务在每个现有用户的启动文件夹中创建 setwallpaper.lnk 快捷方式文件，但 Default User 除外。当用户在实例启动后首次登录时，此快捷方式文件就会运行。使用显示实例属性的自定义壁纸设置实例。删除 setWallpaper 任务不会删除此快捷方式文件。您必须手动删除此文件或使用脚本将其删除。

快捷方式路径是：

$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk

解决方案

手动删除此文件，或使用脚本将其删除。

删除快捷方式文件的 PowerShell 脚本示例

foreach ($userDir in (Get-ChildItem "C:\Users" -Force -Directory).FullName)
{
	$startupPath = Join-Path $userDir -ChildPath "AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup"
	if (Test-Path $startupPath)
	{
		$wallpaperSetupPath = Join-Path $startupPath -ChildPath "setwallpaper.lnk"
		if (Test-Path $wallpaperSetupPath)
		{
			Remove-Item $wallpaperSetupPath -Force -Confirm:$false
		}
	}
}

服务停留在运行状态

描述

EC2Launch v2 被阻止，日志消息（agent.log）与以下类似：

2022-02-24 08:08:58 Info: *****************************************************************************************
2022-02-24 08:08:58 Info: EC2Launch Service starting
2022-02-24 08:08:58 Info: Windows event custom log exists: Amazon EC2Launch
2022-02-24 08:08:58 Info: ACPI SPCR table not supported. Bailing Out
2022-02-24 08:08:58 Info: Serial port is in use. Waiting for Serial Port...
2022-02-24 08:09:00 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:02 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:04 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:06 Info: ACPI SPCR table not supported. Use default console port.
可能的原因

SAC 已启用并使用串行端口。有关更多信息，请参阅使用 SAC 排查 Windows 实例的问题。

解决方案

请尝试以下步骤来解决该问题：

  • 禁用使用串行端口的服务。

  • 如果您希望服务继续使用串行端口，请编写自定义脚本来执行启动代理任务，并将其作为计划的任务调用。

无效的 agent-config.yml 会阻止打开 EC2Launch v2 设置对话框

描述

EC2Launch v2 设置在打开对话框之前尝试解析 agent-config.yml 文件。如果 YAML 配置文件不遵循支持的架构，则对话框将显示以下错误：

Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.

解决方案

  1. 验证配置文件是否遵循支持的架构。

  2. 如果想从头开始，请将默认配置文件复制到 agent-config.yml 中。您可以使用“任务配置”部分中提供的示例 agent-config.yml。

  3. 您也可以通过删除 agent-config.yml 重新开始。EC2Launch v2 设置会生成空配置文件。

task:executeScript should be unique and only invoked once

描述

不能在同一阶段重复一个任务。

解决方案

有些任务必须作为数组输入，例如 executeScript 和 executeProgram。有关如何将脚本编写为数组的示例，请参阅 executeScript。

Windows 事件日志

EC2Launch v2 发布重要事件的 Windows 事件日志，例如服务启动、Windows 已就绪以及任务成功和失败。事件标识符唯一标识特定事件。每个事件都包含阶段、任务和级别信息以及描述。您可以使用事件标识符为特定事件设置触发器。

事件 ID 提供有关事件的信息，并唯一标识某些事件。事件 ID 的最低有效位表示事件的严重性。

活动 最低有效位
Success . . .0
Informational . . .1
Warning . . .2
Error . . .3

当服务启动或停止时生成的与服务相关的事件，包括个位数事件标识符。

活动 个位数标识符
Success 0
Informational 1
Warning 2
Error 3

EC2LaunchService.exe 事件的事件消息以 Service: 开头。EC2Launch.exe 事件的事件消息不以 Service: 开头。

四位数的事件 ID 包括有关事件阶段、任务和严重性的信息。

事件 ID 格式

下表显示了 EC2Launch v2 事件标识符的格式。

3 2 1 0

S

T

L

表中的字母和数字代表以下事件类型和定义。

Event type 定义

S（阶段）

0 – 服务级别消息

1 – Boot

2 – Network

3 – PreReady

5 – Windows 准备就绪

6 – Postready

7 – UserData

T（任务）

由相应的两个值表示的任务在每个阶段都不同。要查看事件的完整列表，请参阅 Windows 事件日志架构。
L（事件级别）

0 – 成功

1 – 信息性

2 – 警告

3 – 错误

事件 ID 示例

以下是示例事件 ID。

  • 5000 – Windows 已准备好使用

  • 3010 – PreReady 阶段中的激活 Windows 任务已成功执行

  • 6013 – Postready 本地数据阶段中的设置壁纸任务遇到错误

Windows 事件日志架构

消息/事件 ID 事件消息
. . .0 Success
. . .1 Informational
. . .2 Warning
. . .3 Error
x EC2Launch service-level logs
0 EC2Launch service exited successfully
1 EC2Launch service informational logs
2 EC2Launch service warning logs
3 EC2Launch service error logs
10 Replace state.json with previous-state.json
100 Serial Port
200 Sysprep
300 PrimaryNic
400 Metadata
x000 Stage (1 digit), Task (2 digits), Status (1 digit)
1000 Boot
1010 Boot - extend_root_partition
2000 Network
2010 Network - add_routes
3000 PreReady
3010 PreReady - activate_windows
3020 PreReady - install_egpu_manager
3030 PreReady - set_monitor_on
3040 PreReady - set_hibernation
3050 PreReady - set_admin_account
3060 PreReady - set_dns_suffix
3070 PreReady - set_wallpaper
3080 PreReady - set_update_schedule
3090 PreReady - output_log
3100 PreReady - enable_open_ssh
5000 Windows is Ready to use
6000 PostReadyLocalData
7000 PostReadyUserData
6010/7010 PostReadyLocal/UserData - set_wallpaper
6020/7020 PostReadyLocal/UserData - set_update_schedule
6030/7030 PostReadyLocal/UserData - set_hostname
6040/7040 PostReadyLocal/UserData - execute_program
6050/7050 PostReadyLocal/UserData - execute_script
6060/7060 PostReadyLocal/UserData - manage_package
6070/7070 PostReadyLocal/UserData - initialize_volume
6080/7080 PostReadyLocal/UserData - write_file
6090/7090 PostReadyLocal/UserData - start_ssm
7100 PostReadyUserData - enable_open_ssh
6110/7110 PostReadyLocal/UserData - enable_jumbo_frames

EC2Launch v2 控制台日志输出

本部分包含 EC2Launch v2 的示例控制台日志输出，并列出所有 EC2Launch v2 控制台日志错误消息，以帮助您排查问题。有关实例控制台输出及如何进行访问的更多信息，请参阅 实例控制台输出。

EC2Launch v2 控制台日志输出

以下是 EC2Launch v2 的示例控制台日志输出。

2023/11/30 20:18:53Z: Windows sysprep configuration complete.
2023/11/30 20:18:57Z: Message: Waiting for access to metadata...
2023/11/30 20:18:57Z: Message: Meta-data is now available.
2023/11/30 20:18:57Z: AMI Origin Version: 2023.11.15
2023/11/30 20:18:57Z: AMI Origin Name: Windows_Server-2022-English-Full-Base
2023/11/30 20:18:58Z: OS: Microsoft Windows NT 10.0.20348
2023/11/30 20:18:58Z: OsVersion: 10.0
2023/11/30 20:18:58Z: OsProductName: Windows Server 2022 Datacenter
2023/11/30 20:18:58Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500
2023/11/30 20:18:58Z: OsCurrentBuild: 20348
2023/11/30 20:18:58Z: OsReleaseId: 2009
2023/11/30 20:18:58Z: Language: en-US
2023/11/30 20:18:58Z: TimeZone: UTC
2023/11/30 20:18:58Z: Offset: UTC +0000
2023/11/30 20:18:58Z: Launch: EC2 Launch v2.0.1643
2023/11/30 20:18:58Z: AMI-ID: ami-1234567890abcdef1
2023/11/30 20:18:58Z: Instance-ID: i-1234567890abcdef0
2023/11/30 20:18:58Z: Instance Type: c5.large
2023/11/30 20:19:00Z: Driver: AWS NVMe Driver v1.5.0.33
2023/11/30 20:19:00Z: SubComponent: AWS NVMe Driver v1.5.0.33; EnableSCSIPersistentReservations: 0
2023/11/30 20:19:00Z: Driver: AWS PV Driver Package v8.4.3
2023/11/30 20:19:01Z: Driver: Amazon Elastic Network Adapter v2.6.0.0
2023/11/30 20:19:01Z: RDPCERTIFICATE-SUBJECTNAME: EC2AMAZ-SO1T009
2023/11/30 20:19:01Z: RDPCERTIFICATE-THUMBPRINT: 1234567890ABCDEF1234567890ABCDEF1234567890
2023/11/30 20:19:09Z: SSM: Amazon SSM Agent v3.2.1705.0
2023/11/30 20:19:13Z: Username: Administrator
2023/11/30 20:19:13Z: Password: <Password>
1234567890abcdef1EXAMPLEPASSWORD
</Password>
2023/11/30 20:19:14Z: User data format: no_user_data	
2023/11/30 20:19:14Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2023/11/30 20:19:14Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2023/11/30 20:19:14Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2023/11/30 20:19:14Z: EC2LaunchTelemetry: AgentCommandErrorCode=0
2023/11/30 20:19:14Z: Message: Windows is Ready to use

EC2Launch v2 控制台日志消息

以下是所有 EC2Launch v2 控制台日志消息的列表。

Message: Error EC2Launch service is stopping. {error message}
 Error setting up EC2Launch agent folders
 See instance logs for detail
 Error stopping service
 Error initializing service
Message: Windows sysprep configuration complete
Message: Invalid administrator username: {invalid username}
Message: Invalid administrator password
Username: {username}
Password: <Password>{encrypted password}</Password>
AMI Origin Version: {amiVersion}
AMI Origin Name: {amiName}
Microsoft Windows NT {currentVersion}.{currentBuildNumber}
OsVersion: {currentVersion}
OsProductName: {productName}
OsBuildLabEx: {buildLabEx}
OsCurrentBuild: {currentBuild}
OsReleaseId: {releaseId}
Language: {language}
TimeZone: {timeZone}
Offset: UTC {offset}
Launch agent: EC2Launch {BuildVersion}
AMI-ID: {amiId}
Instance-ID: {instanceId}
Instance Type: {instanceType}
RDPCERTIFICATE-SUBJECTNAME: {certificate subject name}
RDPCERTIFICATE-THUMBPRINT: {thumbprint hash}
SqlServerBilling: {sql billing}
SqlServerInstall: {sql patch leve, edition type}
Driver: Amazon NVMe Driver {version}
Driver: Inbox NVMe Driver {version}
Driver: Amazon PV Driver Package {version}
Microsoft-Hyper-V is installed.
Unable to get service status for vmms
Microsoft-Hyper-V is {status}
SSM: Amazon SSM Agent {version}
Amazon VSS Version: {version}
Message: Windows sysprep configuration complete
Message: Windows is being configured. SysprepState is {state}
Windows is still being configured. SysprepState is {state}
Message: Windows is Ready to use
Message: Waiting for meta-data accessibility...
Message: Meta-data is now available.
Message: Still waiting for meta-data accessibility...
Message: Failed to find primary network interface...retrying...
User data format: {format}