本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 EC2 Windows 執行個體啟動期間，使用 EC2Launch v2 代理程式執行任務
<a name="ec2launch-v2"></a>

根據預設，從 AWS Windows Server 2022 和 Windows Server 2025 AMI 啟動的所有支援 Amazon EC2 執行個體都包含 EC2Launch v2 啟動代理程式 (`EC2Launch.exe`)。 AMIs 我們亦提供將 EC2Launch v2 安裝為預設啟動代理程式的 Windows Server 2016 和 2019 AMI。除了包含 EC2Launch v1 的 Windows Server 2016 和 2019 AMI 之外，亦提供了這些 AMI。您可以從 Amazon EC2 主控台中的 **AMI** 頁面，在搜尋中輸入以下字首來搜尋預設包含 EC2Launch v2 的 Windows AMI：`EC2LaunchV2-Windows_Server-*`。

若要比較啟動代理程式版本功能，請參閱 [比較 Amazon EC2 啟動代理程式](configure-launch-agents.md#ec2launch-agent-compare)。

EC2Launch v2 在執行個體啟動期間執行任務，並在執行個體停止並稍後啟動或重新啟動時執行。EC2Launch v2 也可依據需求執行任務。其中部分作業為自動啟用，其他作業則必須手動啟用。EC2Launch v2 服務支援所有 EC2Config 和 EC2Launch 功能。

此服務會使用組態檔來控制其操作。您可以使用圖形化工具或直接將組態檔編輯為單一 .yml 檔案 (`agent-config.yml`) 來更新組態檔。若要了解關於日誌檔案位置的詳細資訊，請參閱 [EC2Launch v2 目錄結構](#ec2launch-v2-directory)。

EC2Launch v2 會發佈 Windows 事件日誌，協助您疑難排解錯誤並設定觸發程序。如需詳細資訊，請參閱[Windows 事件日誌](ec2launchv2-troubleshooting.md#ec2launchv2-windows-event-logs)。

**支援的作業系統版本**  
EC2Launch v2 代理程式支援下列 Windows Server 作業系統 (OS) 版本：
+ Windows Server 2025
+ Windows Server 2022
+ Windows Server 2019 (長期服務通道和半年通道)
+ Windows Server 2016

**預設會執行的任務**  
EC2Launch v2 代理程式在初始執行個體啟動期間，預設僅會執行以下任務一次。依據任務在其啟動階段執行的順序對其進行整理。

`Boot` 階段
+ extendRootPartition

`PreReady` 階段
+ activateWindows
+ setDnsSuffix
+ setAdminAccount
+ setWallpaper

`PostReady` 階段
+ startSsm

## EC2Launch v2 概念
<a name="ec2launch-v2-concepts"></a>

考慮 EC2Launch v2 時，下列概念有助於理解。

**agent-config**  
`agent-config` 是位於 EC2Launch v2 組態資料夾中的檔案。包括開機、網路、預備就緒和後備就緒階段的組態。此檔案用於指定執行個體組態，設定應在 AMI 第一次啟動或後續啟動時執行的任務。  
依預設，EC2Launch v2 安裝會安裝一個 `agent-config` 檔案，它包含標準 Amazon Windows AMI 中使用的推薦組態。您可以更新該組態檔案，以變更 EC2Launch v2 指定的 AMI 的預設開機經驗。若要了解關於日誌檔案位置的詳細資訊，請參閱 [EC2Launch v2 目錄結構](#ec2launch-v2-directory)。

**Frequency (頻率)**  
任務頻率確定何時執行任務，這取決於開機內容。大多數任務只有一個允許的頻率。您可以指定 `executeScript` 任務的頻率。  
您將在 [EC2Launch v2 任務組態](ec2launch-v2-settings.md#ec2launch-v2-task-configuration) 中看到以下頻率。  
+ 一次 – 當 AMI 已初次啟動 (完成 Sysprep)，執行任務一次。
+ 始終 – 每次啟動代理程式執行時，任務都會執行。啟動代理程式會執行於下列時間：
  + 執行個體啟動或重新啟動
  + 執行 EC2Launch 服務
  + `EC2Launch.exe run` 被叫用

**階段**  
階段是 EC2Launch v2 代理程式所執行任務的邏輯群組。某些工作只能在特定階段中執行。其他人可以在多個階段運行。使用 `agent-config.yml` 時，必須指定階段清單，以及要在每個階段中執行的任務清單。  
此服務會以下列順序執行各階段：    
階段 1：開機  
  
階段 2：網路  
  
階段 3：預備就緒  
  
Windows 已準備就緒  
PreReady 階段完成後，服務會將 `Windows is ready` 訊息傳送到 Amazon EC2 主控台。  
階段 4：後備就緒  
使用者資料會在 *PostReady* 階段執行。部分指令碼版本會在 `agent-config.yml` 檔案*後備就緒*階段之前執行，有些則會在之後執行，如下所示：    
`agent-config.yml` 之前  
+ YAML 使用者資料版本 1.1
+ XML 使用者資料  
`agent-config.yml` 之後  
+ YAML 使用者資料 1.0 版 (舊版供回溯相容性之用)
如需階段和任務的範例，請參閱 [範例：`agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config)。  
使用使用者資料時，您必須指定代理程式要執行的任務清單。此階段是隱含的。如需任務範例，請參閱 [範例：使用者資料](ec2launch-v2-settings.md#ec2launch-v2-example-user-data)。  
EC2Launch v2 會依照您在 `agent-config.yml` 和使用者資料中指定的順序來執行任務清單。階段按順序執行。下一個階段會在前一個階段完成之後開始。任務也會依序執行。

**任務**  
您可以調用任務以在執行個體上執行動作。您可以在 `agent-config.yml` 檔案中或透過使用者資料來設定任務。如需 EC2Launch v2 可用任務的清單，請參閱 [EC2Launch v2 任務](#ec2launch-v2-tasks)。如需了解任務組態結構描述和詳細資訊，請參閱 [EC2Launch v2 任務組態](ec2launch-v2-settings.md#ec2launch-v2-task-configuration)。

**使用者資料**  
使用者資料是啟動執行個體時可設定的資料。您可以更新使用者資料，以動態變更自訂 AMI 或快速入門 AMI 的設定方式。EC2Launch v2 支援 60 kB 的使用者資料輸入長度。使用者資料只包含 UserData 階段，因此在 `agent-config` 檔案之後執行。您可以在使用啟動執行個體精靈啟動執行個體時輸入使用者資料，也可以從 EC2 主控台修改使用者資料。如需處理使用者資料的資訊，請參閱 [Amazon EC2 如何處理 Windows 執行個體的使用者資料](user-data.md#ec2-windows-user-data)。

## EC2Launch v2 任務概觀
<a name="ec2launch-v2-tasks"></a>

EC2Launch v2 可以在每次開機時執行下列任務：
+ 設定新的和選擇性的自訂桌布來呈現執行個體的相關資訊。
+ 設定在本機電腦上建立的系統管理員帳戶的屬性。
+ 將 DNS 尾碼新增至搜尋尾碼清單。只有不存在的尾碼才會加入到清單中。
+ 為任何額外的磁碟區設定磁碟機代號，並將它們延伸至使用可用空間。
+ 將檔案從組態寫入磁碟。
+ 執行 EC2Launch v2 組態檔案指定的指令碼，或從 `user-data` 執行指令碼。`user-data` 的指令碼可以是純文字或壓縮，並以 base64 格式提供。
+ 執行具有指定參數的程式。
+ 設定電腦名稱。
+ 將執行個體資訊傳送到 Amazon EC2 主控台。
+ 傳送 RDP 憑證指紋到 Amazon EC2 主控台。
+ 動態擴充作業系統的分割區，以包含任何尚未分割的空間。
+ 執行使用者資料。如需指定使用者資料的詳細資訊，請參閱[EC2Launch v2 任務組態](ec2launch-v2-settings.md#ec2launch-v2-task-configuration)。
+ 設定非持久性靜態路由以到達中繼資料服務和 AWS KMS 伺服器。
+ 將非開機磁碟分割設定為 `mbr` 或 `gpt`。
+ 在 Sysprep 後啟動 Systems Manager 服務。
+ 最佳化 ENA 設定。
+ 為更新的 Windows 版本啟用開啟 SSH。
+ 啟用巨型訊框。
+ 將 Sysprep 設定為在 EC2Launch v2 中執行。
+ 發佈 Windows 事件日誌。

## EC2Launch v2 目錄結構
<a name="ec2launch-v2-directory"></a>

EC2Launch v2 應該安裝在以下目錄中：
+ 服務二進位檔案： `%ProgramFiles%\Amazon\EC2Launch`
+ 服務資料 (設定、日誌檔和狀態檔)：`%ProgramData%\Amazon\EC2Launch`

**注意**  
根據預設，Windows 會將檔案和資料夾隱藏在 `C:\ProgramData` 下。若要檢視 EC2Launch v2 目錄和檔案，您必須在 Windows 檔案總管中輸入路徑或變更資料夾屬性，才可顯示隱藏的檔案和資料夾。

`%ProgramFiles%\Amazon\EC2Launch` 目錄包含二進位檔案和支援的程式庫。它包括以下子目錄：
+ `settings`
  + `EC2LaunchSettingsUI.exe` – 用於修改 `agent-config.yml` 檔案的使用者介面
  + `YamlDotNet.dll` – 用於支援使用者介面中的某些操作的 DLL
+ `tools`
  + `ebsnvme-id.exe` – 用於檢查執行個體上 EBS 磁碟區工具
  + `AWSAcpiSpcrReader.exe` – 用於確定要使用的正確 COM 連接埠工具
  + `EC2LaunchEventMessage.dll` – 用於支援 EC2Launch 的 Windows 事件日誌記錄的 DLL
+ `service`
  + `EC2LaunchService.exe` – 啟動代理程式以服務方式執行時，所啟動的 Windows 服務可執行檔
+ `EC2AgentTelemetry.dll` – 用於支援 EC2 代理程式遙測的 DLL
+ `EC2Launch.exe` – 主 EC2Launch 可執行檔
+ `EC2LaunchAgentAttribution.txt` – EC2 Launch 中使用的代碼屬性

`%ProgramData%\Amazon\EC2Launch` 目錄包含下列子目錄。服務產生的所有資料，包括日誌、組態和狀態，都會儲存在此目錄中。
+ `config` – 組態

  服務組態檔案儲存在此目錄中為 `agent-config.yml`。此檔案可以更新，以修改、新增或移除服務所執行的預設任務。在此目錄中建立檔案的許可限制為系統管理員帳戶，以防止權限提升。
+ `log` – 執行個體日誌

  服務 (`agent.log`)、效能 (`bench.log`) 和遙測 (`telemetry.log`) 的日誌會存放在此目錄中。當 `agent.log` 達到 1 MB 大小時，會自動輪換，並使用時間戳記格式建立備份檔案 （例如 `agent-2026-03-02T18-56-39.188.log`)。一次只會維護一個備份日誌檔案。
+ `state` – 服務狀態資料

  服務用來判斷應該執行哪些任務的狀態會儲存在此處。有一個 `.run-once` 檔案會指出服務是否已在 Sysprep 之後執行 (因此，下次執行時會略過頻率為一次的任務)。此子目錄包含 `state.json` 和 `previous-state.json` 以追蹤每個任務的狀態。
+ `sysprep` – Sysprep

  此目錄包含的檔案，可用來判斷 Sysprep 在建立可重複使用的自訂 Windows AMI 時要執行哪些作業。
+ `wallpaper` – 桌布

  此桌布映像會存放在此目錄。

## 遙測
<a name="ec2launch-v2-telemetry"></a>

遙測是其他資訊，有助於 AWS 更了解您的需求、診斷問題和提供功能，以改善您使用 的體驗 AWS 服務。

EC2Launch v2 版本 `2.1.592` 及更新版本會收集遙測，例如用量指標和錯誤。這些資料是從執行 EC2Launch v2 的 Amazon EC2 執行個體中收集的資料。這包括 擁有的所有 Windows AMIs AWS。

EC2Launch v2 會收集下列類型的遙測：
+ **用量資訊** – 代理程式命令、安裝方法和排程的執行頻率。
+ **錯誤和診斷資訊** – 代理程式安裝錯誤代碼、執行錯誤代碼和錯誤呼叫堆疊。

從版本 2.0.592 到 2.1.1 所收集資料的範例：

```
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentCommandErrorCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: IpConflictDetectionCode=0
2025/07/18 22:38:52Z: EC2LaunchTelemetry: AgentErrorLocation=addroutes.go:49
```

自版本 2.2.63 起，EC2 代理程式遙測資料將格式化為 JSON 物件：

```
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... }
```

預設為啟用遙測。您可隨時停用遙測收集。

**停用執行個體的遙測**  
若要停用單一執行個體的遙測，您可以設定系統環境變數，或使用 MSI 來修改安裝。

若要藉由設定系統環境變數來停用遙測，請以管理員身分執行下列命令。

```
setx /M EC2LAUNCH_TELEMETRY 0
```

若要使用 MSI 來停用遙測，請在[下載 MSI](ec2launch-v2-install.md) 後執行以下命令。

```
msiexec /i ".\AmazonEC2Launch.msi" Remove="Telemetry" /q
```

**Topics**
+ [EC2Launch v2 概念](#ec2launch-v2-concepts)
+ [EC2Launch v2 任務概觀](#ec2launch-v2-tasks)
+ [EC2Launch v2 目錄結構](#ec2launch-v2-directory)
+ [遙測](#ec2launch-v2-telemetry)
+ [安裝最新版本的 EC2Launch v2](ec2launch-v2-install.md)
+ [設定 Windows 執行個體的 EC2Launch v2 設定](ec2launch-v2-settings.md)
+ [EC2Launch v2 啟動任務的任務定義](ec2launch-v2-task-definitions.md)
+ [疑難排解使用 EC2Launch v2 代理程式的問題](ec2launchv2-troubleshooting.md)
+ [EC2Launch v2 版本歷程記錄](ec2launchv2-versions.md)