本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 疑難排解使用 EC2Launch v2 代理程式的問題 本節說明 EC2Launch v2 的常見故障診斷案例、有關檢視 Windows 事件日誌的資訊，以及主控台日誌輸出和訊息。 **Topics** + [常用案例](#ec2launchv2-troubleshooting-scenarios) + [Windows 事件日誌](#ec2launchv2-windows-event-logs) + [EC2Launch v2 主控台日誌輸出](#ec2launchv2-console-output) ## 常見的疑難排解案例： 本節說明常見的疑難排解案例和解決步驟。 **Topics** + [服務無法設定桌布](#ec2launchv2-troubleshooting-wallpaper) + [服務無法執行使用者資料](#ec2launchv2-troubleshooting-user-data) + [服務只執行一次任務](#ec2launchv2-troubleshooting-task-once) + [服務無法執行任務](#ec2launchv2-troubleshooting-task-failed) + [服務會多次執行使用者資料](#ec2launchv2-troubleshooting-user-data-more-than-once) + [在移轉至 EC2Launch v2 後，來自 EC2Launch v1 的排程任務無法執行](#ec2launchv2-troubleshooting-scheduled-tasks-migration) + [服務會初始化不為空的 EBS 磁碟區](#ec2launchv2-troubleshooting-ebs-initialize) + [`setWallpaper` 任務未啟用，但桌布會在重新啟動時重設](#ec2launchv2-troubleshooting-wallpaper-resets) + [服務卡在執行狀態](#ec2launchv2-troubleshooting-service-stuck-running) + [無效的 `agent-config.yml` 導致無法開啟 EC2Launch v2 設定對話方塊](#ec2launchv2-troubleshooting-invalid-agent-config) + [`task:executeScript should be unique and only invoked once`](#ec2launchv2-troubleshooting-executescript) ### 服務無法設定桌布 **Resolution** 1. 檢查 `%AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk` 是否存在。 1. 檢查 `%ProgramData%\Amazon\EC2Launch\log\agent.log` 是否發生任何錯誤。 ### 服務無法執行使用者資料 **可能原因**：服務可能在執行使用者資料之前失敗。 **Resolution** 1. 檢查 `%ProgramData%\Amazon\EC2Launch\state\previous-state.json`。 1. 查看 `boot`、`network`、`preReady` 和 `postReadyLocalData` 是否已全部標記為成功。 1. 如果其中一個階段失敗，請檢查 `%ProgramData%\Amazon\EC2Launch\log\agent.log` 是否有特定的錯誤。 ### 服務只執行一次任務 **Resolution** 1. 檢查任務的頻率。 1. 如果服務已經在 Sysprep 之後執行，且任務頻率設定為 `once`，則任務將不會再次執行。 1. 如果您希望 EC2Launch v2 每次執行時都能執行任務，請將任務的頻率設定為 `always`。 ### 服務無法執行任務 **Resolution** 1. 檢查 `%ProgramData%\Amazon\EC2Launch\log\agent.log` 中的最新項目。 1. 如果沒有發生錯誤，請嘗試從 `"%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run` 手動執行服務，以查看任務是否成功。 ### 服務會多次執行使用者資料 **Resolution** EC2Launch v1 和 EC2Launch v2 處理使用者資料的方式不同。當 `persist` 設定為 `true` 時，EC2Launch v1 會將使用者資料視為執行個體上的排程任務來執行。如果將 `persist` 設定為 `false`，即使任務由於重新啟動而退出或在執行時中斷，也不會進行排程。 EC2Launch v2 會將使用者資料視為代理程式任務執行，並追蹤其執行狀態。如果使用者資料導致電腦重新啟動，或是使用者資料在執行時中斷，執行狀態將一直保持為 `pending`，且使用者資料將會在下次執行個體啟動時再次執行。如果您想防止使用者資料指令碼多次執行，請使指令碼等冪。 下列範例等冪指令碼會設定電腦名稱並加入網域。 ``` $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" } false ``` ### 在移轉至 EC2Launch v2 後，來自 EC2Launch v1 的排程任務無法執行 **Resolution** 遷移工具不會偵測任何連結至 EC2Launch v1 指令碼的排程任務；因此，不會自動在 EC2Launch v2 中設定這些任務。若要設定這些任務，請編輯 [`agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-task-configuration) 檔案，或使用 [EC2Launch v2 設定對話方塊](ec2launch-v2-settings.md#ec2launch-v2-ui)。例如，如果執行個體有執行 `InitializeDisks.ps1` 的排程任務，則執行遷移工具後，您必須在 EC2Launch v2 設定對話方塊中指定要初始化的磁碟區。請參閱 [使用 EC2Launch v2 設定對話方塊變更設定](ec2launch-v2-settings.md#ec2launch-v2-ui) 程序的步驟 6。 ### 服務會初始化不為空的 EBS 磁碟區 **Resolution** 在初始化磁碟區之前，EC2Launch v2 會嘗試偵測磁碟區是否為空。如果磁碟區不為空，則會略過初始化程序。偵測為非空白的任何磁碟區都不會初始化。如果磁碟區的前 4 KiB 為空，或磁碟區沒有 [Windows 可辨識的磁碟機配置](https://learn.microsoft.com/en-us/windows/win32/api/winioctl/ns-winioctl-drive_layout_information_ex)，磁碟區會被視為空。在 Linux 系統上初始化並格式化的磁碟區沒有 Windows 可辨識的磁碟機配置，例如 MBR 或 GPT。因此，該磁碟區將視為空磁碟區且已初始化。如果您想要保留此資料，請勿依賴 EC2Launch v2 空白磁碟機偵測。而是在 [EC2Launch v2 設定對話方塊](ec2launch-v2-settings.md#ec2launch-v2-ui) (請參閱步驟 6) 或 [`agent-config.yml`](ec2launch-v2-task-definitions.md#ec2launch-v2-initializevolume) 中指定要初始化的磁碟區。 ### `setWallpaper` 任務未啟用，但桌布會在重新啟動時重設 `setWallpaper` 任務會在每個現有使用者啟動資料夾中，建立 `setwallpaper.lnk` 捷徑檔案。使用者在執行個體啟動後第一次登入時，此捷徑檔案會執行。這會使用顯示執行個體屬性的自訂桌布，設定執行個體。移除 `setWallpaper` 任務不會刪除此捷徑檔案。您必須手動刪除此檔案，或使用指令碼將其刪除。 捷徑路徑為： `$env:SystemDrive/Users//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 執行個體](troubleshoot-using-serial-console.md#troubleshooting-sac)。 **Resolution** 請嘗試下列步驟來解決此問題： + 停用正在使用序列連接埠的服務。 + 如果希望服務繼續使用序列連接埠，請編寫自訂指令碼來執行啟動代理程式任務，並將其做為排程任務呼叫。 ### 無效的 `agent-config.yml` 導致無法開啟 EC2Launch v2 設定對話方塊 **Description** EC2Launch v2 設定將嘗試剖析 `agent-config.yml` 檔案，然後開啟對話方塊。如果 YAML 組態檔案不遵循支援的結構描述，對話方塊將顯示以下錯誤： `Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.` **Resolution** 1. 驗證組態檔案是否遵循[支援的結構描述](ec2launch-v2-settings.md#ec2launch-v2-schema-agent-config)。 1. 如果要從頭開始，請將預設組態檔案複製到 `agent-config.yml`。您可以使用「任務組態」區段中提供的[範例 `agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config)。 1. 您也可以透過刪除 `agent-config.yml` 重新開始。EC2Launch v2 設定產生空的組態檔案。 ### `task:executeScript should be unique and only invoked once` **Description** 不能在同一階段重複任務。 **Resolution** 某些任務必須作為陣列輸入，如 [**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript) 和 [**executeProgram**](ec2launch-v2-task-definitions.md#ec2launch-v2-executeprogram)。如需將指令碼編寫為陣列的範例，請參閱 [**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript)。 ## Windows 事件日誌 EC2Launch v2 會針對重要事件發佈 Windows 事件日誌，例如服務啟動、Windows 已就緒，以及任務成功和失敗。事件 ID 會唯一識別特定事件。每個事件都包含階段、任務和層級資訊，以及說明。您可以使用事件 ID 來設定特定事件的觸發程序。 事件 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 包括關於階段、任務和事件嚴重性的資訊。 **Topics** + [事件 ID 格式](#ec2launchv2-windows-event-logs-format) + [事件 ID 範例](#ec2launchv2-windows-event-logs-id-examples) + [Windows 事件日誌結構描述](#ec2launch-v2-windows-event-logs-schema) ### 事件 ID 格式 下表顯示 EC2Launch v2 事件識別符的格式。 | 3 | 2 1 | 0 | | --- | --- | --- | | S | T | L | 表格中的字母和數字代表下列事件類型和定義。 | Event type | 定義 | | --- | --- | | S (階段) | 0 - 服務層級訊息 1 - 開機 2 - 網路 3 - 預備就緒 5 - Windows 已準備就緒 6 - 後備就緒 7 - 使用者資料 | | T (任務) | 由對應的兩個值所代表的任務對每個階段都不同。若要檢視完整的事件清單，請參閱 [Windows 事件日誌結構描述](#ec2launch-v2-windows-event-logs-schema)。 | | L (活動等級) | 0 - 成功 1 - 資訊 2 - 警告 3 - 錯誤 | ### 事件 ID 範例 以下是範例事件 ID 。 + `5000` - Windows 已做好使用準備 + `3010` - 在預備就緒階段啟動視窗任務成功 + `6013` - 在後備就緒本機資料階段設置桌布任務時發生錯誤 ### 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\$1root\$1partition | | 2000 | Network | | 2010 | Network - add\$1routes | | 3000 | PreReady | | 3010 | PreReady - activate\$1windows | | 3020 | PreReady - install\$1egpu\$1manager | | 3030 | PreReady - set\$1monitor\$1on | | 3040 | PreReady - set\$1hibernation | | 3050 | PreReady - set\$1admin\$1account | | 3060 | PreReady - set\$1dns\$1suffix | | 3070 | PreReady - set\$1wallpaper | | 3080 | PreReady - set\$1update\$1schedule | | 3090 | PreReady - output\$1log | | 3100 | PreReady - enable\$1open\$1ssh | | 5000 | Windows is Ready to use | | 6000 | PostReadyLocalData | | 7000 | PostReadyUserData | | 6010/7010 | PostReadyLocal/UserData - set\$1wallpaper | | 6020/7020 | PostReadyLocal/UserData - set\$1update\$1schedule | | 6030/7030 | PostReadyLocal/UserData - set\$1hostname | | 6040/7040 | PostReadyLocal/UserData - execute\$1program | | 6050/7050 | PostReadyLocal/UserData - execute\$1script | | 6060/7060 | PostReadyLocal/UserData - manage\$1package | | 6070/7070 | PostReadyLocal/UserData - initialize\$1volume | | 6080/7080 | PostReadyLocal/UserData - write\$1file | | 6090/7090 | PostReadyLocal/UserData - start\$1ssm | | 7100 | PostReadyUserData - enable\$1open\$1ssh | | 6110/7110 | PostReadyLocal/UserData - enable\$1jumbo\$1frames | ## EC2Launch v2 主控台日誌輸出 本節包含 EC2Launch v2 的範例主控台日誌輸出，並列出所有 EC2Launch v2 主控台日誌錯誤訊息，以協助您針對問題進行故障診斷。如需執行個體主控台輸出及存取方式的詳細資訊，請參閱 [執行個體主控台輸出](troubleshoot-unreachable-instance.md#instance-console-console-output)。 **Topics** + [EC2Launch v2 主控台日誌輸出](#ec2launchv2-console-log-output) + [EC2Launch v2 主控台日誌訊息](#ec2launchv2-console-log-messages) ### EC2Launch v2 主控台日誌輸出 以下是 EC2Launch v2 的範例主控台日誌輸出。本範例中的部分值已取代為置於大括號內的代表性文字。 ``` 2025/07/22 21:26:53Z: Windows sysprep configuration complete. 2025/07/22 21:26:53Z: Message: Waiting for access to metadata... 2025/07/22 21:26:53Z: Message: Meta-data is now available. 2025/07/22 21:26:53Z: AMI Origin Version: 2024.12.13 2025/07/22 21:26:53Z: AMI Origin Name: Windows_Server-2022-English-Full-Base 2025/07/22 21:26:53Z: OS: Microsoft Windows NT 10.0.20348 2025/07/22 21:26:53Z: OsVersion: 10.0 2025/07/22 21:26:53Z: OsProductName: Windows Server 2022 Datacenter 2025/07/22 21:26:53Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500 2025/07/22 21:26:53Z: OsCurrentBuild: 20348 2025/07/22 21:26:53Z: OsReleaseId: 2009 2025/07/22 21:26:53Z: Language: en-US 2025/07/22 21:26:53Z: TimeZone: UTC 2025/07/22 21:26:53Z: Offset: UTC +0000 2025/07/22 21:26:53Z: Launch: EC2 Launch v2.2.63 2025/07/22 21:26:53Z: AMI-ID: ami-1234567890abcdef1 2025/07/22 21:26:53Z: Instance-ID: i-1234567890abcdef0 2025/07/22 21:26:54Z: Instance Type: t3.xlarge 2025/07/22 21:26:54Z: Driver: AWS NVMe Driver v1.6.0.35 2025/07/22 21:26:54Z: SubComponent: 1.6.0.35; EnableSCSIPersistentReservations: 0 2025/07/22 21:26:54Z: Driver: AWS PV Driver Package v8.5.0 2025/07/22 21:26:55Z: Driver: Amazon Elastic Network Adapter v2.8.0.0 2025/07/22 21:26:55Z: HOSTNAME: EC2AMAZ-9FJG5CC 2025/07/22 21:26:55Z: RDPCERTIFICATE-SUBJECTNAME: {certificate subject name} 2025/07/22 21:26:55Z: RDPCERTIFICATE-THUMBPRINT: {thumbprint hash} 2025/07/22 21:26:56Z: SSM: Amazon SSM Agent v3.3.2746.0 2025/07/22 21:26:57Z: User data format: no_user_data 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsTelemetryEnabled=true 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentCommandErrorCode=1 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0 2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentErrorLocation=execute_windows.go:410 2025/07/22 21:26:57Z: EC2LaunchTelemetry: IpConflictDetectionCode=0 2025/07/22 21:26:57Z: Message: Windows is Ready to use {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...} {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...} ``` ### EC2Launch v2 主控台日誌訊息 以下是所有 EC2Launch v2 主控台日誌訊息的清單。 ``` Error EC2Launch service is stopping. {error message} ``` 已停止服務的錯誤詳細資訊： + `Error setting up EC2Launch agent folders` + `See instance logs for detail` + `Error stopping service` + `Error initializing service` ``` Windows sysprep configuration complete ``` ``` Invalid administrator username: {invalid username} ``` ``` Invalid administrator password Username: {username} Password: {encrypted password} ``` 下列訊息是包含 AMI 詳細資訊的資訊區塊： ``` 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} HOSTNAME: {computer name} 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} SSM: Amazon SSM Agent {version} AWS VSS Version: {version} ``` ``` Windows sysprep configuration complete. Windows is being configured. 'SysprepState is {state}' Windows is still being configured. 'SysprepState is {state}' Windows is Ready to use Waiting for access to metadata... Meta-data is now available. Metadata is not available for this instance. Timed out waiting for access to metadata. User data format: {format} ``` EC2Launch v2 遙測訊息包含了啟動遙測屬性值。自版本 2.2.63 起，EC2 代理程式遙測資料會格式化為 JSON 物件。 ``` EC2LaunchTelemetry: {telemetry property} ``` ``` {"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... } ```