Azure Pipeline 自建 Windows 代理运行失败？看这篇就够了！

2024-12-20 11:03:27

Azure Pipeline 自建 Windows 代理无法运行的常见原因及解决方案

在使用 Azure Pipelines 进行持续集成和持续部署时，通过自建（Self-Hosted）代理能更好控制构建环境和流程。配置好 Windows 代理并用于运行 Java 项目时，却可能遇到一些问题导致其无法正常工作。常见报错例如 "The server data provider for service owner 00000054-0000-8888-8000-000000000000 could not be found." 错误信息模糊，可能源于多种不同原因。此文章将列出若干潜在原因并提供相应排查步骤及解决方案。

一、代理服务运行状态与配置

构建流程依赖于本地代理服务正常运行。需确认代理程序状态。

1. 服务未启动或状态异常

排查方法：

在代理服务器上打开“服务”管理工具（services.msc）。找到名称类似于 "Azure Pipelines Agent (组织名称.代理名称)" 的服务，并检查其状态是否为“正在运行”。如果该服务未启动或状态异常（如“正在停止”或“已停止”），则尝试重新启动服务。

解决方案：

右键点击目标服务。
选择“启动”或“重新启动”。

如果启动失败，在事件查看器（Event Viewer）中查看相关系统或应用程序日志，定位具体错误原因。

代码示例：（PowerShell）

# 检查代理服务状态
Get-Service | Where-Object {$_.Name -like "vstsagent*"}

# 启动代理服务
Start-Service -Name "vstsagent.<Organization Name>.<Agent Name>"

# 重新启动代理服务
Restart-Service -Name "vstsagent.<Organization Name>.<Agent Name>"

2. 代理配置错误

排查方法:

查看代理服务相关文件夹下的 .agent 和 .credentials 文件。.agent文件记录了代理的基本配置信息，如工作目录、代理名称等；.credentials 记录用于与 Azure DevOps 通信的凭据。

解决方案：

如果代理被错误删除或配置发生改动，删除相关文件。
重新运行代理配置脚本 config.cmd。
根据提示，输入 Azure DevOps 组织 URL、Personal Access Token (PAT)、代理池和代理名称等信息。

配置 PAT 时，请确保它有足够权限访问相关资源，至少需具备 "Agent Pools (read, manage)" 权限。PAT 过期将导致代理无法与 Azure DevOps 通信。建议定期更新 PAT。为提高安全性，可限制 PAT 作用范围，并在不使用时及时删除。

二、网络连接与防火墙

代理需要与 Azure DevOps 服务通信才能接收任务和上传结果。任何网络问题都可能导致构建失败。

1. 网络连接问题

排查方法:

在代理服务器上测试能否访问 Azure DevOps 组织 URL。使用 ping 或 Test-NetConnection 命令检测网络连接情况。

代码示例：（PowerShell）

# 使用 Test-NetConnection 检测连接
Test-NetConnection -ComputerName dev.azure.com -Port 443

解决方案：

若无法访问，应检查网络配置。确认代理服务器的网络设置是否正确。检查代理是否设置了网络代理服务器。若已设置网络代理，则确保配置无误。可在运行代理时通过 .\config.cmd --proxyurl <代理地址> --proxyusername <用户名> --proxypassword <密码> 设置。

2. 防火墙阻止

排查方法:

查看防火墙规则。检查 Windows 防火墙或其他安全软件是否阻止了代理与 Azure DevOps 的通信。查看服务器出站规则是否允许了访问端口443的流量。

解决方案:

暂时禁用防火墙，确认问题是否源自防火墙。确认问题由防火墙引发后，应添加入站和出站规则。规则内容为允许代理程序或相关端口访问网络。确保代理安装目录下 bin 文件夹中的 Agent.Listener.exe 可执行文件已配置入站和出站允许规则。配置端口为443或其它设置好的端口号。

三、权限问题

在代理上执行某些任务时，如代码检出、文件操作，可能会遇到权限问题。

1. 运行用户权限不足

排查方法:

查看运行代理服务的用户账户权限。

解决方案:

若使用本地系统账户，应调整其执行的任务权限。使用特定的域用户运行代理。需为用户赋予适当权限。如赋予其访问代码仓库、执行构建工具的权限。根据安全需要将账户分配至合适的安全组。确保安装的Java开发工具等具备对指定文件目录的访问控制权限。
避免在生产环境中使用具有管理员权限的用户。

2. 文件系统权限问题

排查方法:

如果构建过程中涉及到特定目录操作，确保运行代理服务的用户有权限读写这些目录。

解决方案:

给运行代理的用户授予对目标目录及子目录、文件的“读取”和“写入”权限。操作前先尝试暂停agent并查看安装和日志目录，使用管理员运行目录清理脚本，检查是否存在由于用户运行所造成的文件目录独占等。再启用agent进行问题排查，以尽可能排除旧的设置和残留文件的干扰。使用robocopy进行目标文件拷贝。查看目标路径文件夹及子目录下的安全选项卡是否对当前用户授予访问控制。建议创建一个权限范围较小的用户组并将构建用户加入该组来完成工作，减少权限分配不当引起的安全问题。

代码示例：（PowerShell）

# 获取指定文件夹的权限列表
Get-Acl -Path "C:\Agent\_work"

# 为指定用户授予指定文件夹的完全控制权限
$Acl = Get-Acl "C:\Agent\_work"
$AccessRule = New-Object System.Security.AccessControl.FileSystemAccessRule("YourAgentUser","FullControl","ContainerInherit, ObjectInherit","None","Allow")
$Acl.SetAccessRule($AccessRule)
Set-Acl -Path "C:\Agent\_work" -AclObject $Acl

四、服务连接问题 (仅对提问中涉及的服务连接补充)

报错信息有时提到 "service owner"，则可能涉及到服务连接配置问题。

1. 服务连接配置错误

排查方法:

在 Azure DevOps 项目设置中，找到“服务连接”配置页面。查看该类型服务连接是否配置正确，所用凭证是否有效，并且当前构建所指定的服务器可用。验证连接是否被正确引用，并且配置符合相关服务的要求。如为与版本控制的连接，查看token等安全密钥的可用范围以及项目依赖关系。如果为和远端资源的链接，排查是否可以连接到对应远程服务器以及是否已开放相应端口。

解决方案:

若使用的 PAT 过期，更新 PAT。若服务连接本身有问题，则编辑服务连接信息并验证，确保所配置信息正确无误。检查连接配置中是否分配给了合适的应用角色或管理权限。建议在Azure的"Monitoring->Metrics"处配置并查看诊断信息，辅助排查可能的服务连接故障原因。