Azure DevOps Pipeline无法识别正常运行的Self-Hosted Agent

问题表现 #

• 个人PC部署的Azure DevOps Self-Hosted Agent进程正常启动，在DevOps组织的代理池列表中显示在线，状态参考：
  
• 触发Pipeline运行时直接抛出调度失败、找不到可用代理的报错，报错参考：
  

核心排查方向 #

绝大多数这类问题都是配置遗漏导致的，按以下优先级逐一核对即可：

1. 代理池与权限配置校验 #

• 核对Pipeline中指定的代理池名称，和你部署代理时选择加入的代理池完全一致，常见低级错误是代理加入了Default池，但Pipeline配置里指定了其他自定义代理池
• 进入代理池的Security配置页，确认两个账号的权限：
  • Project Collection Build Service (你的组织名称)
  • 你项目对应的Build Service (组织名/项目名)
    以上两个账号需要被授予User及以上权限，不能有任何权限项被设置为Deny
• 跨项目使用代理池的场景，需要手动在代理池配置中开放对应项目的访问权限，默认跨项目调度是被拦截的

2. 代理能力(Capabilities)匹配校验 #

• 打开对应代理的详情页，切到Capabilities标签，对比Pipeline中demands字段声明的所有要求，必须完全匹配才能被调度：

  高频踩坑场景：Pipeline里声明了npm、dotnet、java这类工具依赖，但部署代理的PC没有把对应工具的路径加到系统环境变量，代理启动时识别不到对应能力，哪怕在线也不会被分配任务

• 不需要的demand配置直接从Pipeline里删掉，确实需要的依赖要么在代理机器上装好并配置好环境变量，要么手动在代理的Capabilities页加对应键值对

3. 代理运行身份与连通性校验 #

• 不建议用默认的SYSTEM账号运行代理服务（尤其是Windows环境），个人PC存在安全软件、域权限限制的情况下，优先用你日常登录PC的本地用户账号运行代理服务，给代理安装目录、Pipeline工作目录全开读写权限
• 在代理所在PC上执行连通性检测：Windows环境进入代理安装目录执行.\config.cmd --checknetwork，Linux/Mac环境执行./config.sh --checknetwork，根据返回结果排查是否有出站请求被防火墙、VPN、系统代理拦截
• 如果你开了全局代理、VPN，记得把Azure DevOps的服务地址加到直连白名单，很多时候代理显示在线只是因为长连接没断开，实际任务调度的请求被拦截就会触发报错

4. 代理状态与版本校验 #

• 代理版本和Azure DevOps服务端版本差太多的话，哪怕显示在线也会被判定为不可用，直接在代理详情页点「Update agent」升级到最新版本即可
• 重启一次代理服务：Windows环境找到服务列表里的Azure Pipelines Agent对应服务重启，命令行前台启动的就停掉进程重新执行.\run.cmd/./run.sh，等1-2分钟状态同步完成后再触发Pipeline，很多时候是服务端和代理的状态同步卡住导致的

内容的提问来源于stack exchange，提问作者zip