Azure Windows VM 扩展故障排除

2025-07-07

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 命令：

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 重启，而且，在绝大多数情况下，调用“重新应用”也不会重启 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 重新应用”未起作用，则可从 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”或 Windows 的“C：\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\Downloads\0”）。

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

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

它们还会写入其执行的详细日志（例如，Linux 的“/var/log/azure/custom-script/handler.log”或 Windows 的“C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\CustomScriptHandler.log”）。

若从现有 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 运行时失败。

解决方案

检查 PATH 环境变量中是否已正确列出 PowerShell：
- 打开“控制面板”
- 共享和安全性
- 系统
- “高级”选项卡 -> 环境变量
在“系统变量”下单击“编辑”，并确保 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 运行时失败。

解决方案

在 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 防火墙服务未运行时，可能会发生此错误。

解决方案

检查 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 根证书。

解决方案

使用 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)：终结点映射器中没有更多可用的终结点。