你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

排查 Azure Connected Machine 代理连接问题

项目
10/16/2024

本文提供了有关排查在配置适用于 Windows 或 Linux 的 Azure Connected Machine 代理时可能出现的问题的信息。文中包括配置与服务的连接时的交互式和大规模安装方法。如需常规信息，请参阅已启用 Azure Arc 的服务器概述。

代理错误代码

使用下表确定并解决在使用打印到控制台或脚本输出的 AZCM0000（“0000”可以是任何四位数）配置 Azure Connected Machine 代理时出现的问题。

错误代码	可能的原因	建议的补救措施
AZCM0000	操作成功	空值
AZCM0001	发生未知错误	请联系 Microsoft 支持寻求帮助。
AZCM0011	用户已取消操作 (CTRL+C)	重试上一命令。
AZCM0012	访问令牌无效	如果是通过访问令牌进行身份验证，请获取新令牌，然后重试。如果是通过服务主体或设备登录进行身份验证，请联系 Microsoft 支持部门以获取帮助。
AZCM0016	缺少必需参数	查看输出中的错误消息，以确定缺少哪些参数。若要了解命令的完整语法，请运行 `azcmagent <command> --help`。
AZCM0018	在没有管理权限的情况下执行了命令	在权限提升的用户上下文 (administrator/root) 中重试命令。
AZCM0019	配置文件的路径不正确	确保配置文件的路径正确，然后重试。
AZCM0023	为参数（自变量）提供的值无效	查看错误消息以获取更具体的信息。若要了解自变量的有效值或预期格式，请参阅命令 (`azcmagent <command> --help`) 的语法。
AZCM0026	网络配置存在错误或某些关键服务暂时不可用	检查所需的终结点是否可访问（例如，主机名是否可解析，终结点是否未受阻止）。如果网络是针对专用链接范围配置的，则必须使用 `--private-link-scope` 参数提供专用链接范围资源 ID 以进行加入。
AZCM0041	提供的凭据无效	对于设备登录，请验证指定的用户帐户是否有权访问将创建服务器资源的租户和订阅。对于服务主体登录，请检查客户端 ID 和机密是否正确、机密的到期日期，以及服务主体是否来自将创建服务器资源的同一租户。
AZCM0042	已启用 Azure Arc 的服务器资源创建失败	查看输出中的错误消息，以确定无法创建资源的原因和建议的修正。有关详细信息，请参阅《Connected Machine 代理先决条件所需的权限》。
AZCM0043	已启用 Azure Arc 的服务器资源删除失败	验证指定的用户/服务主体是否有权在指定的组中删除已启用 Azure Arc 的服务器/资源。有关详细信息，请参阅《Connected Machine 代理先决条件所需的权限》。如果资源在 Azure 中不复存在，请使用 `--force-local-only` 标志继续操作。
AZCM0044	已存在同名的资源	请为 `--resource-name` 参数指定其他名称，或者删除 Azure 中现有已启用 Azure Arc 的服务器，然后重试。
AZCM0062	连接服务器时出错	查看输出中的错误消息以获取更具体的信息。如果在创建 Azure 资源后发生错误，请先删除此资源，然后再重试。
AZCM0063	断开服务器连接时出错	查看输出中的错误消息以获取更具体的信息。如果仍然遇到此错误，请在 Azure 中删除该资源，然后在服务器上运行 `azcmagent disconnect --force-local-only`。
AZCM0067	计算机已连接到 Azure	运行 `azcmagent disconnect` 以删除当前连接，然后重试。
AZCM0068	提供了订阅名称，但在查找相应的订阅 GUID 时出错。	使用订阅 GUID（而不是订阅名称）重试该命令。
AZCM0061 AZCM0064 AZCM0065 AZCM0066 AZCM0070	代理服务未响应或不可用	验证该命令是否已在权限提升的用户上下文 (administrator/root) 中运行。确保 HIMDS 服务正在运行（根据需要启动或重启 HIMDS），然后再次尝试该命令。
AZCM0081	下载 Microsoft Entra 托管标识证书时出错	如果尝试将服务器连接到 Azure 时出现此消息，则表示代理无法与 Azure Arc 服务通信。请删除 Azure 中的资源，然后重试连接。
AZCM0101	未成功分析命令	运行 `azcmagent <command> --help` 来查看命令语法。
AZCM0102	检索计算机主机名时出错	重试该命令并指定资源名称（使用参数 --resource-name 或 -n）。仅使用字母数字字符、连字符和/或下划线；请注意，资源名称不能以连字符或下划线结尾。
AZCM0103	生成 RSA 密钥时出错	请联系 Microsoft 支持寻求帮助。
AZCM0105	下载 Microsoft Entra ID 托管标识证书时出错	删除 Azure 中创建的资源，然后重试。
AZCM0147- AZCM0152	在 Windows 上安装 Azcmagent 时出错	查看输出中的错误消息以获取更具体的信息。
AZCM0127- AZCM0146	在 Linux 上安装 Azcmagent 时出错	查看输出中的错误消息以获取更具体的信息。
AZCM0150	安装过程中的一般故障	提交支持票证以获取帮助。
AZCM0153	系统平台不受支持	查看受支持平台的先决条件
AZCM0154	系统上安装的 PowerShell 版本太旧	请升级到 PowerShell 4 或更高版本，然后重试。
AZCM0155	运行安装脚本的用户没有管理员权限	以管理员身份重新运行脚本。
AZCM0156	代理安装失败	确认计算机未在 Azure 上运行。可以在位于 `%TEMP%\installationlog.txt` 的安装日志中找到详细的错误。
AZCM0157	无法下载 Microsoft Linux 软件存储库的存储库元数据	检查防火墙是否阻止访问 `packages.microsoft.com` 并重试。

代理详细日志

在遵循本文后面所述的故障排除步骤之前，所需的最少信息为详细日志。使用 verbose (-v) 参数时，它包含 azcmagent 工具命令的输出。对于 Windows，日志文件将写入 %ProgramData%\AzureConnectedMachineAgent\Log\azcmagent.log；对于 Linux，日志文件将写入 /var/opt/azcmagent/log/azcmagent.log。

Windows

下面是执行交互式安装时，使用 Connected Machine Agent 为 Windows 启用详细日志记录的命令示例。

& "$env:ProgramFiles\AzureConnectedMachineAgent\azcmagent.exe" connect --resource-group "resourceGroupName" --tenant-id "tenantID" --location "regionName" --subscription-id "subscriptionID" --verbose

下面是使用服务主体执行大规模安装时，使用 Connected Machine Agent 为 Windows 启用详细日志记录的命令示例。

& "$env:ProgramFiles\AzureConnectedMachineAgent\azcmagent.exe" connect `
  --service-principal-id "{serviceprincipalAppID}" `
  --service-principal-secret "{serviceprincipalPassword}" `
  --resource-group "{ResourceGroupName}" `
  --tenant-id "{tenantID}" `
  --location "{resourceLocation}" `
  --subscription-id "{subscriptionID}"
  --verbose

Linux

下面是执行交互式安装时，使用 Connected Machine Agent 为 Linux 启用详细日志记录的命令示例。

注意

若要运行 azcmagent，必须具有对 Linux 计算机的根访问权限。

azcmagent connect --resource-group "resourceGroupName" --tenant-id "tenantID" --location "regionName" --subscription-id "subscriptionID" --verbose

下面是使用服务主体执行大规模安装时，使用 Connected Machine Agent 为 Linux 启用详细日志记录的命令示例。

azcmagent connect \
  --service-principal-id "{serviceprincipalAppID}" \
  --service-principal-secret "{serviceprincipalPassword}" \
  --resource-group "{ResourceGroupName}" \
  --tenant-id "{tenantID}" \
  --location "{resourceLocation}" \
  --subscription-id "{subscriptionID}"
  --verbose

服务的代理连接问题

下表列出了一些已知错误以及如何排除和解决这些问题的建议。

消息	错误	可能的原因	解决方案
未能获取授权令牌设备流	`Error occurred while sending request for Device Authorization Code: Post https://login.windows.net/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/devicecode?api-version=1.0: dial tcp 40.126.9.7:443: connect: network is unreachable.`	无法访问 `login.windows.net` 终结点	运行 azcmagent check 以查看防火墙是否阻止访问 Microsoft Entra ID。
未能获取授权令牌设备流	`Error occurred while sending request for Device Authorization Code: Post https://login.windows.net/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/devicecode?api-version=1.0: dial tcp 40.126.9.7:443: connect: network is Forbidden`。	代理或防火墙正在阻止对 `login.windows.net` 终结点的访问。	运行 azcmagent check 以查看防火墙是否阻止访问 Microsoft Entra ID。
未能从 SPN 获取授权令牌	`Failed to execute the refresh request. Error = 'Post https://login.windows.net/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/token?api-version=1.0: Forbidden'`	代理或防火墙正在阻止对 `login.windows.net` 终结点的访问。	运行 azcmagent check 以查看防火墙是否阻止访问 Microsoft Entra ID。
未能从 SPN 获取授权令牌	`Invalid client secret is provided`	服务主体机密错误或无效。	验证服务主体机密。
未能从 SPN 获取授权令牌	`Application with identifier 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' wasn't found in the directory 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant`	服务主体和/或租户 ID 不正确。	验证服务主体和/或租户 ID。
获取 ARM 资源响应	`The client 'username@domain.com' with object id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' does not have authorization to perform action 'Microsoft.HybridCompute/machines/read' over scope '/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.HybridCompute/machines/MSJC01' or the scope is invalid. If access was recently granted, please refresh your credentials."}}" Status Code=403`	凭据和/或权限错误	验证你或服务主体是“Azure Connected Machine 加入”角色的成员。
未能 AzcmagentConnect ARM 资源	`The subscription isn't registered to use namespace 'Microsoft.HybridCompute'`	Azure 资源提供程序未注册。	注册资源提供程序。
未能 AzcmagentConnect ARM 资源	`Get https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.HybridCompute/machines/MSJC01?api-version=2019-03-18-preview: Forbidden`	代理服务器或防火墙正在阻止对 `management.azure.com` 终结点的访问。	运行 azcmagent check 以查看防火墙是否阻止访问 Azure 资源管理器。

后续步骤

如果你的问题未在本文中列出，或者无法解决你遇到的问题，请尝试通过以下途径之一获取更多支持：

通过 Microsoft Q&A 获取 Azure 专家的解答。
联系 @AzureSupport，这是用于改进客户体验的官方 Microsoft Azure 帐户。 Azure 支持人员会将你连接到 Azure 社区，从中可以获得解答、支持和专家建议。
提出 Azure 支持事件。请转到 Azure 支持站点并选择“获取支持”。

通过