管道运行故障排除

Azure Pipelines |Azure DevOps Server 2020 |Azure DevOps Server 2019 |TFS 2018 - TFS 2015

本主题提供常规的故障排除指南。 有关 .NET Core 的具体故障排除,请参阅 .Net core 故障排除

备注

在 Microsoft Team Foundation Server (TFS) 2018 和更低版本中,生成和发布管道被称为“定义”,运行被称为“生成”,服务连接被称为“服务终结点”,阶段被称为“环境”,而作业被称为“阶段” 。

你可以使用以下故障排除部分来帮助诊断管道问题。 大多数管道故障都属于其中一种类别。

管道不触发

如果管道根本没有启动,请检查以下常见触发器相关问题。

备注

可能无法启动的另一个原因是,在上一个用户注销 Azure DevOps 后,你的组织将进入睡眠状态5分钟。 之后,每个生成管道将运行一次。 例如,当你的组织处于睡眠状态时:

  • 你的组织中的每夜代码生成将仅运行一夜,直到有人再次登录。
  • 其他 Git 存储库的 CI 版本将停止运行,直到有人再次登录。

UI 设置替代 YAML 触发器设置

YAML 管道可以 trigger pr 在管道设置 UI 中重写其和触发器设置。 如果 triggerpr 触发器看起来没有触发,请检查该设置。 编辑管道时,请选择 " ... ",然后单击 " 触发器"。

管道设置 UI

选中 "在 此处替代 YAML 触发器" 设置,以查看适用于你的存储库的 (持续集成拉取请求验证) 。

从此处替代 YAML 触发器。

Azure Repos 不支持拉取请求触发器

如果 pr 触发器未激发,并且您使用的是 Azure Repos,则这是因为 pr Azure Repos 不支持触发器。 在 Azure Repos Git 中,分支策略用于实现拉取请求生成验证。 有关详细信息,请参阅 用于拉取请求验证的分支策略

CI 和 PR 触发器中的分支筛选器配置错误

定义 YAML PR 或 CI 触发器时,可以 include exclude 为分支和路径指定 and 子句。 确保 include 子句与提交的详细信息匹配,并且 exclude 子句不会排除它们。

重要

定义 YAML PR 或 CI 触发器时,只有显式配置为包含的分支才会触发运行。 首先处理包含,然后从列表中删除 "排除"。 如果指定排除但不指定任何包含,则不会触发任何内容。 有关详细信息,请参阅触发器

定义 YAML PR 或 CI 触发器时,可以 include exclude 为分支、标记和路径指定 and 子句。 确保 include 子句与提交的详细信息匹配,并且 exclude 子句不会排除它们。 有关详细信息,请参阅触发器

备注

如果指定 exclude 不带子句的子句 include ,则等效于 * 在子句中指定 include

计划的触发器时区转换

YAML 计划的触发器是使用 UTC 时区设置的。 如果计划的触发器看起来不是在正确的时间触发,请确认 UTC 与本地时区之间的转换,同时考虑了日期设置。 有关详细信息,请参阅 计划触发器

UI 设置替代 YAML 计划触发器

如果 YAML 管道同时具有 YAML 计划的触发器和 UI 定义的计划触发器,则仅运行 UI 定义的计划触发器。 若要在 YAML 管道中运行 YAML 定义的预定触发器,必须删除在管道设置 UI 中定义的计划触发器。

若要从 YAML 管道访问管道设置 UI,请编辑管道,选择 " ... ",然后单击 " 触发器"。

管道设置 UI

删除所有计划的触发器。

删除管道设置 UI 中的计划触发器。

删除所有 UI 计划的触发器后,必须执行推送,YAML 计划的触发器才能开始运行。 有关详细信息,请参阅 计划触发器

管道队列,但从不获取代理

如果管道排队但从不获取代理,请检查以下各项。

备注

以下方案不会使用并行作业:

  • 如果使用 release 管道或多阶段 YAML 管道,则运行仅在主动部署到阶段时才会消耗并行作业。 当发布正在等待批准或手动干预时,它不会使用并行作业。
  • 使用 release 管道运行服务器作业或部署到部署组时,不会使用任何并行作业。

了解详细信息:管道如何使用并行作业,如何添加预先部署审批服务器作业部署组

并行作业限制-无可用代理或已达到免费限制

如果当前正在运行其他管道,则可能没有任何剩余的并行作业,或者可能已达到了 免费限制

若要检查限制,请导航到 Project 设置"、"并行作业"。

Pipelines 并发作业

查看限制后,检查并发以查看当前正在运行的作业数以及可用的作业数。

如果当前正在运行其他管道,则可能没有任何剩余的并行作业,或者可能已达到了 免费限制

无法从 Azure DevOps 访问防火墙后面的 Azure Key Vault

如果无法从管道访问 Azure Key Vault,则可能是防火墙阻止了 Azure DevOps Services 代理的 IP 地址。 每周 JSON 文件中发布的 IP 地址必须为 allowlisted。 有关详细信息,请参阅 Microsoft 托管的代理:网络

你没有足够的并发性

若要检查有多少并发性,请执行以下操作:

  1. 若要检查限制,请导航到 Project 设置"、"并行作业"。

    并发管道限制

    你还可以通过导航到 https://dev.azure.com/{org}/_settings/buildqueue?_a=concurrentJobs 或从日志中选择 " 管理并行作业 " 来访问此页。

    管理并行作业

  2. 确定要在 (Microsoft 托管或自承载池) 上检查并发的池,然后选择 " 查看正在进行的作业"。

  3. 你将看到显示 当前正在运行 x/x 作业 的文本。 如果两个数字相同,则作业将等待,直到当前正在运行的作业完成。

    查看正在进行的作业

    可以通过从 " Project" 设置 中选择 "代理池" 来查看所有作业,包括已排队的作业。

    查看已排队的作业

    在此示例中,并发作业限制为1,其中一个作业正在运行,一个处于排队状态。 当所有代理都忙于运行作业(如本示例所示)时,当其他作业排队时,将显示以下消息: The agent request is not running because all potential agents are running other requests. Current position in queue: 1 。 在此示例中,作业在队列中,因此其位置为1。

你的作业可能正在等待审批

你的管道可能不会移动到下一阶段,因为它正在等待批准。 有关详细信息,请参阅 定义审核和检查

正在使用所有可用的代理

如果所有代理当前都处于繁忙状态,作业可能会等待。 检查代理:

  1. 导航到 https://dev.azure.com/{org}/_settings/agentpools

  2. 选择要检查的代理池,在此示例中为 FabrikamPool,然后选择 " 代理"。

    代理状态

    此页显示所有当前联机/脱机和使用中的代理。 还可以从此页面向池中添加其他代理。

不符合代理功能的要求

如果管道具有不符合任何代理功能的要求,则管道将无法启动。 如果只有部分代理具有所需的功能,且当前正在运行其他管道,则管道将停止,直到其中一个代理可用为止。

若要检查为代理和管道指定的功能和需求,请参阅功能

备注

功能和要求通常仅用于自承载代理。 如果管道具有与代理的系统功能不匹配的要求,除非已使用匹配功能显式标记了代理,否则管道将不会获得代理。

TFS 代理连接问题

测试代理连接时,配置失败 (仅限本地 TFS)

Testing agent connection.
VS30063: You are not authorized to access http://<SERVER>:8080/tfs

如果在配置代理时收到上述错误,请登录到 TFS 计算机。 (IIS) 管理器启动 Internet Information Services。 请确保已启用 匿名身份验证

是否启用 TFS 匿名身份验证

代理失去通信

此问题的特征在于错误消息:

The job has been abandoned because agent did not renew the lock. Ensure agent is running, not sleeping, and has not lost communication with the service.

此错误可能表示代理在数分钟内失去了与服务器的通信。 检查以下内容以排除代理计算机上的网络或其他中断:

  • 验证是否关闭了自动更新。 从更新重新启动计算机将导致生成或发布失败,并出现上述错误。 以受控的方式应用更新,以避免此类中断。 在重新启动代理计算机之前,应该先在 "池管理" 页中将代理标记为 "已禁用",并让任何正在运行的生成完成。
  • 验证是否关闭了睡眠设置。
  • 如果代理在虚拟机上运行,则应避免任何实时迁移或其他 VM 维护操作,这些操作可能会严重影响计算机的运行状况。
  • 如果代理在虚拟机上运行,则相同的操作系统更新建议和睡眠设置建议适用于主计算机。 以及对宿主计算机有多个影响的任何其他维护操作。
  • 性能监视器日志记录或其他运行状况指标日志记录有助于将此类错误关联到 (磁盘、内存、页面文件、处理器、网络) 上的代理计算机上的资源可用性。
  • 将错误与网络问题相关联的另一种方法是无限期地 ping 服务器,并将输出转储到文件以及时间戳。 使用正常的间隔,例如20或30秒。 如果使用 Azure Pipelines,则需要对 internet 域进行 ping 操作,例如 bing.com。 如果你使用的是本地 TFS 服务器,则需要对同一网络上的服务器进行 ping 操作。
  • 验证计算机的网络吞吐量是否充足。 可以执行联机速度测试来检查吞吐量。
  • 如果使用代理,请验证是否已将代理配置为使用代理。 请参阅代理部署主题。

TFS 作业代理未启动

这可能是由 web 控制台中的消息 "正在等待请求的代理" 来描述的。 验证 TFSJobAgent (显示名称: Visual Studio Team Foundation 后台作业代理) Windows 服务是否已启动。

(1.x 代理版本配置错误的通知 URL)

这可能是由 web 控制台中的消息 "等待来自代理的控制台输出" 来确定的,该过程最终会超时。

不匹配的通知 URL 可能导致工作进程无法连接到服务器。 请参阅 Team Foundation 管理控制台应用层。 1.x 代理使用其配置的 URL 侦听消息队列。 但是,如果从队列中提取作业消息,则工作进程将使用通知 URL 与服务器通信。

检查服务是否降级 Azure DevOps 状态

检查Azure DevOps 服务状态门户中是否存在可能导致服务降级的问题,例如,为代理增加了排队时间。 有关详细信息,请参阅Azure DevOps 服务状态

管道无法完成

如果管道获取代理但未能完成,请检查以下常见问题。 如果你的问题似乎与其中一项不符,请参阅 获取日志以诊断问题

作业超时

管道可能会长时间运行,然后由于作业超时而失败。作业超时非常接近于所使用的代理。 对于专用存储库,免费的 Microsoft 托管代理的每个作业的最大超时为60分钟,公共存储库的最大超时为360分钟。 若要增加作业的最大超时值,可以选择以下任一项。

  • 购买 Microsoft 托管的代理,无论使用哪种存储库,都将为所有作业提供360分钟
  • 使用自承载代理排除代理导致的任何超时问题

详细了解作业 超时

备注

如果 Microsoft 托管的代理作业超时,请确保未指定小于作业的最大超时值的管道超时值。 若要查看,请参阅 超时

下载代码时出现问题

我的管道在结帐步骤中失败

如果你使用的是 checkout 组织中与你的管道不同的项目中的 Azure Repos Git 存储库上的步骤,请确保 "将 作业授权范围限制为当前项目" 设置处于禁用状态,或者按照 范围内的生成标识中的步骤操作,以确保管道有权访问存储库。

如果你的管道由于作业授权范围有限而无法访问存储库,你将会收到错误, Git fetch failed with exit code 128 你的日志将包含类似于以下内容的条目 Remote: TF401019: The Git repository with name or identifier <your repo name> does not exist or you do not have permissions for the operation you are attempting.

如果管道立即失败 Could not find a project that corresponds with the repository ,请确保 checkout 步骤或存储库资源声明中的项目和存储库名称正确。

Team Foundation 版本控制 (TFVC) 问题

获取不下载某些文件的源

这可能是通过 tf get 命令的 "从最新文件开始" 日志中的消息来描述的。 验证内置服务标识是否具有下载源的权限。 标识 Project 收集生成服务Project 生成服务 将需要权限下载源,具体取决于生成管道的 "常规" 选项卡上所选的授权作用域。 在版本控制 web UI 中,你可以在文件夹层次结构的任意级别上浏览项目文件,并检查安全设置。

通过 Team Foundation 代理获取源

若要将代理配置为通过 Team Foundation 代理获取源,最简单的方法是设置环境变量 TFSPROXY ,该变量指向代理的 "以用户身份运行" 的 TFVC 代理服务器。

Windows:

    set TFSPROXY=http://tfvcproxy:8081
    setx TFSPROXY=http://tfvcproxy:8081 // If the agent service is running as NETWORKSERVICE or any service account you can't easily set user level environment variable

macOS/Linux:

    export TFSPROXY=http://tfvcproxy:8081

在 MSBUILD 的命令行步骤中我的管道失败

缩小生成或发布失败是否由代理或任务Azure Pipelines/TFS 产品问题 (很有用) 。 生成和发布失败也可能由外部命令导致。

检查日志,了解失败任务执行的确切命令行。 尝试从命令行本地运行命令可能会重现此问题。 从自己的计算机本地运行命令和/或登录到计算机,并作为服务帐户运行命令会很有帮助。

例如,在生成管道的 MSBuild 过程中是否出现问题 (例如,你是使用 MSBuild 还是 Visual Studio生成) ? 如果是这样,请尝试使用相同的MSBuild在本地计算机上运行相同的命令。 如果可以在本地计算机上重现问题,则接下来的步骤是调查MSBuild问题。

文件布局

生成所需的工具、库、标头和其他内容在托管代理上的位置可能不同于本地计算机。 如果生成因找不到这些文件之一而失败,可以使用以下脚本检查代理上的布局。 这可以帮助你跟踪缺少的文件。

在临时位置创建新的 YAML 管道 (例如,为排查问题而创建的新) 。 根据编写,脚本将搜索路径上的目录。 可以选择编辑行 SEARCH_PATH= 以搜索其他位置。

# Script for Linux and macOS
pool: { vmImage: ubuntu-latest } # or whatever pool you use
steps:
- checkout: none
- bash: |
    SEARCH_PATH=$PATH  # or any colon-delimited list of paths
    IFS=':' read -r -a PathDirs <<< "$SEARCH_PATH"
    echo "##[debug] Found directories"
    for element in "${PathDirs[@]}"; do
        echo "$element"
    done;
    echo;
    echo;  
    echo "##[debug] Found files"
    for element in "${PathDirs[@]}"; do
        find "$element" -type f
    done
# Script for Windows
pool: { vmImage: windows-2019 } # or whatever pool you use
steps:
- checkout: none
- powershell: |
    $SEARCH_PATH=$Env:Path
    Write-Host "##[debug] Found directories"
    ForEach ($Dir in $SEARCH_PATH -split ";") {
      Write-Host "$Dir"
    }
    Write-Host ""
    Write-Host ""
    Write-Host "##[debug] Found files"
    ForEach ($Dir in $SEARCH_PATH -split ";") {
      Get-ChildItem $Dir -File -ErrorAction Continue | ForEach-Object -Process {
        Write-Host $_.FullName
      }
    }

本地命令提示符与代理之间的差异

请记住,在本地计算机上执行命令以及生成或发布在代理上运行时,存在一些差异。 如果代理配置为在 Linux、macOS 或 Windows 作为服务运行,则代理不在交互式登录会话中运行。 如果没有交互式登录会话,则存在 UI 交互和其他限制。

使用中的文件或文件夹错误

使用中的文件或文件夹错误通常由错误消息指示,例如:

  • Access to the path [...] is denied.
  • The process cannot access the file [...] because it is being used by another process.
  • Access is denied.
  • Can't move [...] to [...]

疑难解答步骤:

检测使用中的文件和文件夹

在Windows,进程监视器等工具可以捕获特定目录下的文件事件的跟踪。 或者,对于实时快照,可以使用进程资源管理器或句柄等工具。

防病毒排除

扫描文件的防病毒软件可能会导致文件或文件夹在生成或发布期间出现使用错误。 为代理目录添加防病毒排除项并配置"工作文件夹"有助于将防病毒软件识别为干扰过程。

MSBuild 和 /nodeReuse:false

如果在生成MSBuild调用参数,请确保将参数 (/nodeReuse:false 形式 /nr:false) 。 否则MSBuild生成 () 进程将继续运行。 由于 (后续) ,此过程会保留一段时间。

此功能MSBuild删除或移动目录的尝试 - 因为与进程的工作目录MSBuild冲突 () 。

生成MSBuild和Visual Studio任务已添加到传递给 MSBuild /nr:false 的参数。 但是,如果MSBuild脚本调用参数,则需要指定 参数。

MSBuild 和 /maxcpucount:[n]

默认情况下,生成任务(如MSBuild 和Visual Studio 生成MSBuild开关 /m 运行。 在某些情况下,这可能会导致问题,例如多个进程文件访问问题。

尝试将 /m:1 参数添加到生成任务,MSBuild一次只运行一个进程。

利用文件的并发进程功能时,可能会导致文件使用MSBuild。 不指定短 (/maxcpucount:[n] 参数) /m:[n] 指示MSBuild使用单个进程。 如果使用生成MSBuild或Visual Studio,可能需要指定"/m:1"以替代默认添加的"/m"参数。

间歇性或不MSBuild故障

如果遇到间歇性或不一致的MSBuild失败,请尝试MSBuild使用单进程。 间歇性或不一致的错误可能表示目标配置与客户端的并发进程功能MSBuild。 请参阅MSBuild 和 /maxcpucount:[n]

进程停止响应

进程停止响应原因和故障排除步骤:

等待输入

停止响应的进程可能指示进程正在等待输入。

从交互式登录会话的命令行运行代理有助于确定进程是否正在提示输入对话框。

将代理作为服务运行可帮助避免程序提示输入。 例如,在 .NET 中,程序可能依赖于 System.Environment.UserInteractive 布尔值来确定是否提示。 作为服务Windows时,该值为 false。

进程转储

分析进程的转储有助于确定死锁进程正在等待什么。

WiX 项目

在启用自定义日志MSBuild生成 WiX 项目可能会导致 WiX 在输出流上出现死锁。 添加其他 MSBuild /p:RunWixToolsOutOfProc=true 参数将解决此问题。

多个平台的行尾

在多个平台上运行管道时,有时可能会遇到不同行尾的问题。 过去,Linux 和 macOS 使用换行符 (LF) 字符,而 Windows 则使用回车符和换行符 (CRLF) 。 Git 尝试通过自动使行在存储库中以 LF 结尾,但在存储库的工作目录中以 CRLF 结尾来Windows。

大多数Windows工具都可以使用仅 LF 结束,这种自动行为可能会导致的问题多于它解决的问题。 如果遇到基于行尾的问题,建议将 Git 配置为首选所有位置的 LF。 为此,将 .gitattributes 文件添加到存储库的根目录。 在该文件中添加以下行:

* text eol=lf

追加了 " (单引号) 变量

如果管道包含一个使用 命令设置变量的 Bash 脚本,则你可能会看到一个附加的追加到所设置的 ##vso ' 变量的值。 发生此情况的原因是与 交互 set -x 。 解决方法是在设置 set -x 变量之前暂时禁用 。 用于执行此操作的 Bash 语法为 set +x

set +x
echo ##vso[task.setvariable variable=MY_VAR]my_value
set -x

为何发生这种情况?

许多 Bash 脚本 set -x 都包括 命令来帮助进行调试。 Bash 将精确跟踪已执行的命令,并回显到 stdout。 这会使代理看到命令两次,第二次,Bash 将字符 ##vso ' 添加到末尾。

例如,请考虑以下管道:

steps:
- bash: |
    set -x
    echo ##vso[task.setvariable variable=MY_VAR]my_value

在 stdout 上,代理将看到两行:

##vso[task.setvariable variable=MY_VAR]my_value
+ echo '##vso[task.setvariable variable=MY_VAR]my_value'

当代理看到第一行时, MY_VAR 将设置为正确的值"my_value"。 但是,当它看到第二行时,代理将处理该行末尾的所有内容。 MY_VAR 将设置为"my_value"。

执行脚本时,不会为 Python 应用程序安装库

部署 Python 应用程序时,在某些情况下,CI/CD 管道会运行并成功部署代码,但负责安装所有依赖项库的 requirements.txt 文件不会执行。

若要安装依赖项,请使用应用服务部署任务中的部署后脚本。 以下示例演示部署后脚本中必须使用的命令。 可以针对方案更新脚本。

D:\home\python364x64\python.exe -m pip install -r requirements.txt

若要排查与服务连接相关的问题,请参阅 服务连接故障排除

启用存储资源管理器,以通过 .js 将静态内容(如 .css)Azure DevOps静态Azure Pipelines

在此方案中,可以使用 Azure 文件 复制任务 将内容上传到网站。 可以使用上传内容中所述的任何工具将内容上传到Web 容器。

获取日志以诊断问题

如果上述建议都不符合你的问题,可以使用日志中的信息来诊断失败的管道。

首先查看已完成的生成或发布中的日志。 可导航到管道运行摘要并选择作业和任务来查看日志。 如果某个任务失败,请检查该任务的日志。

除了在管道生成摘要中查看日志外,还可以下载包含其他诊断信息的完整日志,还可以配置更多详细日志以帮助进行故障排除。

有关配置和使用日志的详细说明,请参阅查看日志以诊断管道问题

我需要更多的帮助。 我发现了一个 bug。 我有一个建议。 我该怎么办?

获取订阅、计费和技术支持

在开发人员服务中报告任何问题或Community。

欢迎你提供建议: