Azure Windows VM 扩展故障排除

2025-09-15

Azure 资源管理器模板概述

注释

对于在 GitHub 存储库“azure-quickstart-templates”中下载或引用的模板，必须进行修改，以适应 Azure 中国云环境。例如，替换某些终结点（将“blob.core.windows.net”替换为“blob.core.chinacloudapi.cn”，将“cloudapp.azure.com”替换为“chinacloudapp.cn”）；必要时更改某些不受支持的 VM 映像、VM 大小、SKU 以及资源提供程序的 API 版本。

Azure 资源管理器模板允许用户通过定义资源之间的依赖关系，使用 JSON 语言以声明方式指定 Azure IaaS 基础结构。

若要详细了解如何创作可使用扩展的模板，请参阅创作扩展模板。

本文介绍如何对一些常见的 VM 扩展故障进行故障排除。

查看扩展状态

可以从 Azure PowerShell 执行 Azure 资源管理器模板。一旦执行该模板，就可以从 Azure 资源浏览器或命令行工具查看扩展状态。

下面是一个示例：

Azure PowerShell：

Get-AzVM -ResourceGroupName $RGName -Name $vmName -Status

下面是示例输出：

Extensions:  {
  "ExtensionType": "Microsoft.Compute.CustomScriptExtension",
  "Name": "myCustomScriptExtension",
  "SubStatuses": [
    {
      "Code": "ComponentStatus/StdOut/succeeded",
      "DisplayStatus": "Provisioning succeeded",
      "Level": "Info",
      "Message": "    Directory: C:\\temp\\n\\n\\nMode                LastWriteTime     Length Name
          \\n----                -------------     ------ ----                              \\n-a---          9/1/2015   2:03 AM         11
          test.txt                          \\n\\n",
                  "Time": null
      },
    {
      "Code": "ComponentStatus/StdErr/succeeded",
      "DisplayStatus": "Provisioning succeeded",
      "Level": "Info",
      "Message": "",
      "Time": null
    }
  ]
}

扩展故障排除

验证 VM 代理是否正在运行且就绪

需要 VM 代理来管理、安装和执行扩展。如果 VM 代理未运行或未能向 Azure 平台报告就绪状态，则扩展无法正常工作。

以下页面用于排查 VM 代理问题：

对 Windows Azure 来宾代理进行故障排除（针对 Windows VM）
对 Azure Linux 代理进行故障排除（针对 Linux VM）

查看特定扩展故障排除指南

某些扩展有一个特定页面，用于描述如何对其进行故障排除。可以在对扩展进行故障排除中查找这些扩展和页面的列表。

查看扩展状态

如前所述，可以通过运行 PowerShell cmdlet 找到扩展的状态：

Get-AzVM -ResourceGroupName $RGName -Name $vmName -Status

或 CLI 命令：x

az vm extension show -g <RG Name> --vm-name <VM Name>  --name <Extension Name>

或在 Azure 门户中，通过浏览到 VM 边栏选项卡/设置/扩展。然后，可以单击扩展并检查其状态和消息。

在 VM 上重新运行扩展

如果使用自定义脚本扩展在 VM 上运行脚本，则有时可能会遇到错误：VM 已成功创建，但脚本失败。在这些情况下，从此错误中恢复的建议方法是删除该扩展并再次重新运行该模板。

注释

将来，此功能将得到增强，以消除卸载扩展的需要。

从 Azure PowerShell 删除扩展

Remove-AzVMExtension -ResourceGroupName $RGName -VMName $vmName -Name "myCustomScriptExtension"

删除扩展后，可以重新执行模板以在 VM 上运行脚本。

触发 VM 的新 GoalState

你可能会看到扩展未运行，因为缺少“Windows Azure CRP 证书生成器”。此证书有助于在传输过程中保护扩展的设置。通过从虚拟机内部重启 Windows 来宾代理来自动重新生成该证书：

打开任务管理器
转到“详细信息”选项卡
找到 WindowsAzureGuestAgent.exe 进程
右键单击并选择“结束任务”。进程会自动重启

还可以通过执行“VM 重新应用”来触发 VM 的新 GoalState。 VM 重新应用是一个在 2020 年引入的 API，用于重新应用 VM 的状态。建议在可以容忍 VM 短暂停机时执行此操作。重新应用通常不会重新启动 VM，但在极少数情况下，它可能会触发需要重启的挂起更新。

Azure 门户：

在门户中，选择 VM，并在左侧窗格中的“支持 + 故障排除”下，选择“重新部署 + 重新应用”，然后选择“重新应用” 。

Azure PowerShell（将“RG 名称”和“VM 名称”替换为你的值）：

Set-AzVM -ResourceGroupName <RG Name> -Name <VM Name> -Reapply

Azure CLI（将“RG 名称”和“VM 名称”替换为你的值）：

az vm reapply -g <RG Name> -n <VM Name>

如果“VM Reapply”不起作用，可以从 Azure 管理门户将新的空数据磁盘添加到 VM，然后在证书添加回来后将其删除。

查看 VM 中的扩展日志

如果前面的步骤不起作用，并且扩展仍处于失败状态，则下一步是在虚拟机中查看其日志。

在 Windows VM 上，扩展日志默认驻留在

C:\WindowsAzure\Logs\Plugins

默认情况下，扩展设置和状态文件处于

C:\Packages\Plugins

在 Linux VM 上，扩展日志默认驻留在

/var/log/azure/

详细信息提供的扩展设置和状态文件位于

/var/lib/waagent/

每个扩展都不同，但它们通常遵循类似的原则：

扩展包和二进制文件在 VM 上下载（例如： 适用于 Linux 的“/var/lib/waagent/custom-script/download/1” 或 “C：\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\Downloads\0” for Windows）。

它们的配置和设置通过 VM 代理从 Azure 平台传递到扩展处理程序（例如：适用于 Windows 的 “/var/lib/waagent/Microsoft.Azure.Extensions.CustomScript-2.1.3/config” 或 “C：\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\RuntimeSettings” for Windows）

VM 中的扩展处理程序正在写入状态文件（例如： “/var/lib/waagent/Microsoft.Azure.Extensions.CustomScript-2.1.3/status/1.status/1.status” 或“ C：\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\Status” for Windows）报告给 Azure 平台。该状态是通过 PowerShell、CLI 或 Azure 门户中 VM 的扩展边栏选项卡报告。

他们还编写其执行的详细日志（例如：适用于 Linux 的“/var/log/azure/custom-script/handler.log” 或 “C：\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\CustomScriptHandler.log” for Windows）。

若从现有 VM 重新创建 VM

有可能出现这种情况，即你创建的 Azure VM 基于来自另一个 Azure VM 的专用磁盘。在这种情况下，旧 VM 可能包含扩展、二进制文件、日志和状态文件。新的 VM 模型不知道以前的 VM 扩展状态，并且可能会报告这些扩展的错误状态。强烈建议先删除旧 VM 中的扩展，再创建新 VM，然后在创建新 VM 后重新安装这些扩展。从现有 Azure VM 创建通用映像时，也可能发生此种情况。请删除扩展，以免扩展中的状态不一致。

已知问题

PowerShell 无法识别为内部或外部命令

在 RunCommand 扩展的输出中发现以下错误条目：

RunCommandExtension failed with "'powershell' isn't recognized as an internal or external command,"

分析

扩展在本地系统帐户下运行，因此，在 RDP 进入 VM 时，powershell.exe 正常，但在使用 RunCommand 运行时失败。

Solution

检查 PATH 环境变量中是否已正确列出 PowerShell：
- 打开“控制面板”
- 共享和安全性
- System
- “高级”选项卡 -> 环境变量
在“系统变量”下单击“编辑”，并确保 PowerShell 位于 PATH 环境变量中（通常为：“C:\Windows\System32\WindowsPowerShell\v1.0”）
重启 VM 或 WindowsAzureGuestAgent 服务，然后再次尝试运行命令。

命令无法识别为内部或外部命令

C:\WindowsAzure\Logs\Plugins<ExtensionName><Version>\CommandExecution.log 文件中包含以下内容：

Execution Error: '<command>' isn't recognized as an internal or external command, operable program or batch file.

分析

扩展在本地系统帐户下运行，因此，在 RDP 进入 VM 时，powershell.exe 正常，但在使用 RunCommand 运行时失败。

Solution

在 VM 中打开命令提示符并执行命令以重现错误。 VM 代理使用管理员 cmd.exe，可能需要在每次启动 cmd 时执行一些预先配置的命令。
也可能是 PATH 变量配置错误，但这取决于存在问题的命令。

VMAccessAgent 失败，无法更新管理员帐户的远程桌面连接设置。错误：System.Runtime.InteropServices.COMException (0x800706D9)：终结点映射器中没有更多可用的终结点。

可在扩展的状态中看到以下内容：

Type Microsoft.Compute.VMAccessAgent
Version 2.4.8
Status Provisioning failed
Status level Error
Status message Cannot update Remote Desktop Connection settings for Administrator account. Error: System.Runtime.InteropServices.COMException (0x800706D9): There are no more endpoints available from the endpoint mapper. (Exception from HRESULT: 0x800706D9) at NetFwTypeLib.INetFwRules.GetEnumerator() at 
Microsoft.WindowsAzure.GuestAgent.Plugins.JsonExtensions.VMAccess.RemoteDesktopManager.EnableRemoteDesktopFirewallRules() 
at Microsoft.WindowsAzure.GuestAgent.Plugins.JsonExtensions.VMAccess.RemoteDesktopManager.EnableRemoteDesktop() at

分析

当 Windows 防火墙服务未运行时，可能会发生此错误。

Solution

检查 Windows 防火墙服务是否已启用并且正在运行。如果不是，请启用并启动它 - 然后重试运行 VMAccessAgent。

根据验证过程，远程证书无效。

将在 WaAppAgent.log 中看到以下内容

System.Net.WebException: The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel. ---> System.Security.
Authentication.AuthenticationException: The remote certificate is invalid according to the validation procedure.

分析

你的 VM 可能缺少“受信任的根证书颁发机构”中的 Baltimore CyberTrust 根证书。

Solution

使用 certmgr.msc 打开证书控制台，然后检查证书是否在此处。

第三方 SSL 检查工具（如 ZScaler）可能会中断证书链。应将此类工具配置为绕过 SSL 检查。

共用方式為

Azure Windows VM 扩展故障排除

Azure 资源管理器模板概述

查看扩展状态

扩展故障排除

验证 VM 代理是否正在运行且就绪

查看特定扩展故障排除指南

查看扩展状态

在 VM 上重新运行扩展

从 Azure PowerShell 删除扩展

触发 VM 的新 GoalState

查看 VM 中的扩展日志

若从现有 VM 重新创建 VM

已知问题

PowerShell 无法识别为内部或外部命令

命令无法识别为内部或外部命令

VMAccessAgent 失败，无法更新管理员帐户的远程桌面连接设置。 错误：System.Runtime.InteropServices.COMException (0x800706D9)：终结点映射器中没有更多可用的终结点。

根据验证过程，远程证书无效。

其他資源

VMAccessAgent 失败，无法更新管理员帐户的远程桌面连接设置。错误：System.Runtime.InteropServices.COMException (0x800706D9)：终结点映射器中没有更多可用的终结点。