本文提供了有关排查在配置适用于 Windows 或 Linux 的 Azure Connected Machine 代理时可能出现的问题的信息。 在配置与服务 的连接时，包含交互式和大规模安装方法 的提示。
有关常规信息，请参阅 已启用 Azure Arc 的服务器概述、 Azure Connected Machine 代理概述以及 管理和维护 Connected Machine 代理。
代理错误代码
使用下表确定并解决在使用输出到控制台或脚本输出的 AZCM0000（“0000”可以是任何四位数）配置 Azure Connected Machine 代理时出现的问题。
| 错误代码 | 可能的原因 | 建议的补救措施 |
|---|---|---|
| AZCM0000 | 操作成功 | 无 |
| AZCM0001 | 发生未知错误 | 请联系 Azure 支持部门获取帮助。 |
| AZCM0011 | 用户已取消操作 (CTRL+C) | 重试上一命令。 |
| AZCM0012 | 访问令牌无效 | 如果是通过访问令牌进行身份验证，请获取新令牌，然后重试。 如果通过服务主体或设备登录进行身份验证，请联系 Azure 支持部门以获取帮助。 |
| AZCM0016 | 缺少必需参数 | 查看输出中的错误消息，以确定缺少哪些参数。 若要了解命令的完整语法，请运行 azcmagent <command> --help。 |
| AZCM0018 | 在没有管理权限的情况下执行了命令 | 在权限提升的用户上下文 (administrator/root) 中重试命令。 |
| AZCM0019 | 配置文件的路径不正确 | 确保配置文件的路径正确，然后重试。 |
| AZCM0023 | 为参数（自变量）提供的值无效 | 检查错误消息中是否有更具体的信息。 若要了解自变量的有效值或预期格式，请参阅命令 (azcmagent <command> --help) 的语法。 |
| AZCM0026 | 网络配置存在错误或某些关键服务暂时不可用 | 检查所需的终结点是否可访问（例如，主机名是否可解析，终结点是否未受阻止）。 如果网络是针对专用链接范围配置的，则必须使用 --private-link-scope 参数提供专用链接范围资源 ID 以进行加入。 |
| AZCM0041 | 提供的凭据无效 | 对于设备登录，请验证指定的用户帐户是否能够访问将创建服务器资源的租户和订阅。 对于服务主体登录，请检查客户端 ID 和机密是否正确和有效的到期日期，并确保服务主体来自要在其中创建服务器资源的同一租户。 |
| AZCM0042 | 已启用 Azure Arc 的服务器资源创建失败 | 查看输出中的错误消息，以确定无法创建资源的原因和建议的修正。 有关详细信息，请参阅所需的权限。 |
| AZCM0043 | 已启用 Azure Arc 的服务器资源删除失败 | 验证指定的用户/服务主体是否有权在指定的组中删除已启用 Azure Arc 的服务器/资源。 有关详细信息，请参阅所需的权限。 如果资源在 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 密钥时出错 | 请联系 Azure 支持部门获取帮助。 |
| 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 | 无法下载 Azure Linux 软件存储库的存储库元数据 | 检查防火墙是否阻止访问 packages.microsoft.com 并重试。 |
代理退出代码
运行 Azure Connected Machine Agent （azcmagent） 命令时，进程可能会以退出代码终止。 这些代码指示作的结果，并帮助诊断问题。 与错误代码不同，当代理进程退出时，作系统会返回退出代码。
| 退出代码 | Description | 建议的修正 |
|---|---|---|
| 0 | 未发生错误。 | 无需任何行动。 |
| 1 | 默认错误 | 确保满足先决条件，检查代理日志并重试。 |
| 2 | 代理中的内部错误。 | 重启代理服务。 |
| 3 | 不支持操作。 | 验证该命令是否对 OS 和代理版本有效。 |
| 4 | Arc 代理服务未运行。 | 确保 Hybrid Instance Metadata Service (himds) 服务正在运行。 |
| 5 | 文件记录器不可用。 | 检查日志目录的磁盘空间和权限。 |
| 6 | 初始化失败。 | 检查先决条件（网络、权限）。 修复问题后重新运行 azcmagent connect 。 |
| 11 | 操作被用户中断（Ctrl+C）。 | 在不中断的情况下重新运行命令。 |
| 12 | 提供的访问令牌无效。 | 使用 az login 或提供有效的令牌刷新 Azure 凭据。 |
| 18 | 需要管理权限。 | 使用提升的权限运行命令（sudo 或提升的命令提示符）。 |
| 19 | 找不到配置文件。 | 请验证配置文件路径或使用azcmagent config重新生成。 |
| 20 | 指定的未知区域。 | 检查区域拼写并确保区域受支持。 |
| 23 | 提供的参数无效。 | 使用 azcmagent --help 查看命令语法。 |
| 26 | 出现网络错误。 | 验证与 Azure 终结点的连接。 检查防火墙和代理设置。 |
| 27 | 检测到配置冲突。 | 请在/etc/azcmagent/config.json或%ProgramData%\AzureConnectedMachineAgent\Config\localconfig.json中删除冲突的设置，然后重试。 |
| 41 | 未能获取访问令牌。 | 确保 az login 成功，如果适用，则启用 MSI。 |
| 42 | 未能创建 Azure 资源。 | 检查订阅权限和资源配额。 |
| 43 | 未能删除 Azure 资源。 | 验证资源是否存在并且你具有删除权限。 |
| 44 | 资源已存在。 | 使用 azcmagent reconnect 而不是 connect。 |
| 45 | 无法更新重新连接公钥。 | 验证网络连接和代理日志后重试。 |
| 61 | 代理通信错误。 | 重启 himds 服务。 |
| 62 | 无法将计算机连接到 Azure。 | 检查网络连接和订阅权限。 |
| 63 | 无法断开计算机与 Azure 的连接。 | 确保计算机处于联机状态且代理正常后重试。 |
| 64 | 无法与 HIMDS 服务器建立通信。 | 重启 himds 服务并验证日志。 |
| 65 | 无法获取代理元数据。 | 检查代理日志并重试。 |
| 66 | 无法获取代理状态。 | 重启代理并验证连接。 |
| 67 | 计算机已连接。 | 使用 azcmagent reconnect 而不是 connect。 |
| 68 | 无法提取订阅 ID。 | 验证 Azure 凭据并重试。 |
| 69 | 更新本地配置时出错。 | 检查文件权限并重试。 |
| 70 | 无法获取本地配置。 | 验证配置文件完整性并重试。 |
| 72 | 运行扩展工具时出错。 | 检查扩展日志并重试。 |
| 73 | 无法获取合作伙伴配置。 | 验证合作伙伴集成设置。 |
| 74 | 添加扩展时出错。 | 确保扩展包有效，然后重试。 |
| 75 | 无法获取云配置。 | 检查与 Azure 终结点的连接。 |
| 76 | 无法打开 TPM 设备。 | 验证 TPM 可用性和权限。 |
| 77 | 无法处理 TPM 密钥。 | 检查 TPM 运行状况并重试。 |
| 78 | 无法使用基于 TPM 的身份验证进行连接。 | 验证 TPM 配置并重试。 |
| 81 | 未能从 HIS 获取 MSI 证书。 | 确保 HIS 服务正在运行并重试。 |
| 82 | 无法使用 TPM 从 HIS 获取 MSI 证书。 | 验证 TPM 配置和 HIS 连接。 |
| 101 | 命令执行错误。 | 验证命令语法并检查日志以了解详细信息。 |
| 102 | 无法生成资源名称。 | 确保主机名满足 Azure 命名要求。 |
| 103 | 无法处理 RSA 密钥。 | 检查 TPM 可用性和权限。 |
| 104 | 未能检索私钥。 | 验证密钥存储并重试。 |
| 105 | 未能收到已签名的消息。 | 检查连接并重试。 |
| 106 | 无法保存参数文件。 | 验证磁盘空间和权限。 |
| 107 | 未能检索证书。 | 验证证书存储和重试。 |
代理详细日志
若要按照本文后面所述的故障排除步骤作，所需的最低信息是详细日志。 当使用详细 （） 参数时，此日志包含 -v 工具命令的输出。 对于 Windows，日志文件将写入 %ProgramData%\AzureConnectedMachineAgent\Log\azcmagent.log；对于 Linux，日志文件将写入 /var/opt/azcmagent/log/azcmagent.log。
Windows操作系统
以下命令是一个示例，用于在执行交互式安装时，通过用于 Windows 的 Connected Machine 代理启用详细日志记录功能。
& "$env:ProgramFiles\AzureConnectedMachineAgent\azcmagent.exe" connect --resource-group "resourceGroupName" --tenant-id "tenantID" --location "regionName" --subscription-id "subscriptionID" --verbose
以下命令是使用服务主体执行大规模安装时，使用适用于 Windows 的 Connected Machine 代理启用详细日志记录的示例。
& "$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
以下命令是执行交互式安装时使用适用于 Linux 的 Connected Machine 代理执行详细日志记录的示例。
注释
若要运行 azcmagent，必须具有对 Linux 计算机的根访问权限。
azcmagent connect --resource-group "resourceGroupName" --tenant-id "tenantID" --location "regionName" --subscription-id "subscriptionID" --verbose
以下命令是使用服务主体执行大规模安装时，使用适用于 Linux 的 Connected Machine 代理启用详细日志记录的示例。
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.chinacloudapi.cn/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/devicecode?api-version=1.0: dial tcp 40.126.9.7:443: connect: network is unreachable. |
无法访问 login.chinacloudapi.cn 终结点 |
运行 azcmagent check 以查看防火墙是否阻止访问 Microsoft Entra ID。 |
未能获取授权令牌设备流：Error occurred while sending request for Device Authorization Code: Post https://login.chinacloudapi.cn/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/devicecode?api-version=1.0: dial tcp 40.126.9.7:443: connect: network is Forbidden。 |
代理或防火墙正在阻止对 login.chinacloudapi.cn 终结点的访问。 |
运行 azcmagent check 以查看防火墙是否阻止访问 Microsoft Entra ID。 |
未能从 SPN 获取授权令牌：Failed to execute the refresh request. Error = 'Post https://login.chinacloudapi.cn/fb84ce97-b875-4d12-b031-ef5e7edf9c8e/oauth2/token?api-version=1.0: Forbidden' |
代理或防火墙正在阻止对 login.chinacloudapi.cn 终结点的访问。 |
运行 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.chinacloudapi.cn/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.HybridCompute/machines/MSJC01?api-version=2019-03-18-preview: Forbidden |
代理服务器或防火墙正在阻止对 management.chinacloudapi.cn 终结点的访问。 |
运行 azcmagent check 以查看防火墙是否阻止了对 Azure 资源管理器的访问。 |
后续步骤
如果你的问题未在本文中列出，或者无法解决你遇到的问题，请尝试通过以下途径之一获取支持：
- 通过 Microsoft Q&A 获取 Azure 专家的解答。
- 提出支持请求以获取帮助。 有关详细信息，请参阅创建 Azure 支持请求。