疑難排解使用 EC2Launch v2 代理程式的問題

本節說明 EC2Launch v2 的常見故障診斷案例、有關檢視 Windows 事件日誌的資訊，以及主控台日誌輸出和訊息。

常見的疑難排解案例：

本節說明常見的疑難排解案例和解決步驟。

服務無法設定桌布

服務無法執行使用者資料

可能原因：服務可能在執行使用者資料之前失敗。

服務只執行一次任務

服務無法執行任務

服務會多次執行使用者資料

Resolution

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 v2 後，來自 EC2Launch v1 的排程任務無法執行

Resolution

遷移工具不會偵測任何連結至 EC2Launch v1 指令碼的排程任務；因此，不會自動在 EC2Launch v2 中設定這些任務。若要設定這些任務，請編輯 agent-config.yml 檔案，或使用 EC2Launch v2 設定對話方塊。例如，如果執行個體有執行 InitializeDisks.ps1 的排程任務，則執行遷移工具後，您必須在 EC2Launch v2 設定對話方塊中指定要初始化的磁碟區。請參閱 使用 EC2Launch v2 設定對話方塊變更設定 程序的步驟 6。

服務會初始化不為空的 EBS 磁碟區

Resolution

在初始化磁碟區之前，EC2Launch v2 會嘗試偵測磁碟區是否為空。如果磁碟區不為空，則會略過初始化程序。偵測為非空白的任何磁碟區都不會初始化。如果磁碟區的前 4 KiB 為空，或磁碟區沒有 Windows 可辨識的磁碟機配置，磁碟區會被視為空。在 Linux 系統上初始化並格式化的磁碟區沒有 Windows 可辨識的磁碟機配置，例如 MBR 或 GPT。因此，該磁碟區將視為空磁碟區且已初始化。如果您想要保留此資料，請勿依賴 EC2Launch v2 空白磁碟機偵測。而是在 EC2Launch v2 設定對話方塊 (請參閱步驟 6) 或 agent-config.yml 中指定要初始化的磁碟區。

setWallpaper 任務未啟用，但桌布會在重新啟動時重設

setWallpaper 任務會在 Default User 以外的每個現有使用者啟動資料夾中，建立 setwallpaper.lnk 捷徑檔案。使用者在執行個體啟動後第一次登入時，此捷徑檔案會執行。這會使用顯示執行個體屬性的自訂桌布，設定執行個體。移除 setWallpaper 任務不會刪除此捷徑檔案。您必須手動刪除此檔案，或使用指令碼將其刪除。

捷徑路徑為：

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

Resolution

手動刪除此檔案，或使用指令碼將其刪除。

刪除捷徑檔案的範例 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
		}
	}
}

服務卡在執行狀態

Description

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 執行個體。

Resolution

請嘗試下列步驟來解決此問題：

無效的 agent-config.yml 導致無法開啟 EC2Launch v2 設定對話方塊

描述

EC2Launch v2 設定將嘗試剖析 agent-config.yml 檔案，然後開啟對話方塊。如果 YAML 組態檔案不遵循支援的結構描述，對話方塊將顯示以下錯誤：

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

task:executeScript should be unique and only invoked once

描述

不能在同一階段重複任務。

Resolution

某些任務必須作為陣列輸入，如 executeScript 和 executeProgram。如需將指令碼編寫為陣列的範例，請參閱 executeScript。

Windows 事件日誌

EC2Launch v2 會針對重要事件發佈 Windows 事件日誌，例如服務啟動、Windows 已就緒，以及任務成功和失敗。事件 ID 會唯一識別特定事件。每個事件都包含階段、任務和層級資訊，以及說明。您可以使用事件 ID 來設定特定事件的觸發程序。

事件 ID 提供事件的相關資訊，並唯一識別某些事件。事件 ID 的最低有效位元顯示事件的嚴重性。

服務啟動或停止時產生的服務相關事件包含單一數字事件識別符。

事件的 EC2LaunchService.exe 事件訊息以 Service: 為開頭。事件的 EC2Launch.exe 事件訊息不是以 Service: 為開頭。

四位數的事件 ID 包括關於階段、任務和事件嚴重性的資訊。

事件 ID 格式

下表顯示 EC2Launch v2 事件識別符的格式。

表格中的字母和數字代表下列事件類型和定義。

事件 ID 範例

以下是範例事件 ID 。

Windows 事件日誌結構描述

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: AWS NVMe Driver {version}
Driver: Inbox NVMe Driver {version}
Driver: AWS 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}
AWS 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}