管道运行故障排除

Azure DevOps Services |Azure DevOps Server 2022 - Azure DevOps Server 2019 |TFS 2018

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

注意

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

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

管道不会触发

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

注意

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

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

UI 设置替代 YAML 触发器设置

YAML 管道可以在管道设置 UI 中重写其 triggerpr 触发器设置。 trigger如果或pr触发器似乎未触发,请检查该设置。 编辑管道时,选择 ...“ ,然后选择 ”触发器”。

管道设置 UI

在此处检查 “替代 YAML 触发器 ”设置,了解可用于存储库的触发器类型 (持续集成拉取请求) 验证

从此处替代 YAML 触发器。

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

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

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

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

重要

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

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

注意

如果指定没有子句的excludeinclude子句,则等效于在include子句中指定*

计划的触发时区转换

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

UI 设置替代 YAML 计划触发器

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

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

管道设置 UI

删除所有计划触发器。

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

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

管道队列,但永远不会获取代理

如果管道队列但从未获取代理,请检查以下项。

注意

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

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

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

并行作业限制 - 没有可用的代理,或者已达到免费限制

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

若要检查限制,请导航到 “项目”设置“并行 作业

管道并发作业

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

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

无法从 Azure DevOps 访问防火墙后面的 Azure 密钥保管库

如果无法从管道访问 Azure 密钥保管库,防火墙可能会阻止Azure DevOps Services代理 IP 地址。 必须在 每周 JSON 文件中 发布的 IP 地址列入允许列表。 有关详细信息,请参阅 Microsoft 托管的代理:网络

没有足够的并发性

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

  1. 若要检查限制,请导航到 “项目”设置“并行 作业

    并发管道限制

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

    管理并行作业

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

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

    查看正在进行的作业

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

    查看排队作业

    在此示例中,并发作业限制为一个,其中一个作业正在运行,一个作业排队。 当所有代理都忙于运行作业时,如此示例所示,当其他作业排队时,将显示以下消息: The agent request is not running because all potential agents are running other requests. Current position in queue: 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 计算机。 启动 Internet Information Services (IIS) 管理器。 确保已启用 匿名身份验证

已启用 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,则需要 ping Internet 域,例如 bing.com。 如果使用的是本地 TFS 服务器,则需要在同一网络上 ping 服务器。
  • 验证计算机的网络吞吐量是否足够。 可以执行联机速度测试来检查吞吐量。
  • 如果使用代理,请验证代理是否已配置为使用代理。 请参阅代理部署主题。

TFS 作业代理未启动

这可能由 Web 控制台中的消息特征为“等待请求代理”。 验证 TFSJobAgent (显示名称: Visual Studio Team Foundation 后台作业代理) Windows 服务是否已启动。

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

这可能由 Web 控制台中的消息“正在等待代理的控制台输出”进行特征,此过程最终会超时。

不匹配的通知 URL 可能会导致辅助角色无法连接到服务器。 请参阅 Team Foundation 管理控制台应用程序层。 1.x 代理使用配置的消息队列来侦听消息队列。 但是,当从队列拉取作业消息时,工作进程使用通知 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 命令中的日志“所有文件最新”中的消息特征。 验证内置服务标识是否有权下载源。 标识 项目集合生成服务项目生成服务 将需要下载源的权限,具体取决于生成管道的“常规”选项卡上的所选授权范围。 在版本控制 Web UI 中,可以在文件夹层次结构的任何级别浏览项目文件并检查安全设置。

通过 Team Foundation 代理获取源

将代理配置为通过 Team Foundation Proxy 获取源的最简单方法是设置环境变量,该环境变量 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 部分中出现问题 (例如,你使用的是 MSBuildVisual 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 进程 (es) 将在生成完成后保持运行状态。 (es) 的过程在期待潜在的后续生成时会保留一段时间。

MSBuild 的此功能可能会干扰尝试删除或移动目录 - 由于 MSBuild 进程的工作目录发生冲突, (es) 。

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

MSBuild 和 /maxcpucount:[n]

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

尝试将 /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 Boolean 来确定是否提示。 作为 Windows 服务运行时,该值为 false。

进程转储

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

WiX 项目

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

多个平台的行尾

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

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

* text eol=lf

追加了 “ (单引号) 变量

如果管道包含使用 ##vso 命令设置变量的 Bash 脚本,你可能会看到附加 ' 追加到设置的变量的值。 之所以发生这种情况,是因为与 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。 这将导致代理看到 ##vso 命令两次,第二次,Bash 会将字符添加到 ' 末尾。

例如,请考虑以下管道:

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 文件不会执行。

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

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

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

启用存储资源管理器,通过 Azure Pipelines 将 .css 和 .js 等静态内容部署到 Azure DevOps 中的静态网站

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

获取日志以诊断问题

如果上述任何建议都与问题不匹配,则可以使用日志中的信息来诊断失败的管道。

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

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

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

我需要更多帮助。 我发现了一个 bug。 我有一个建议。 我去哪里?

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

开发者社区报告任何问题或提交反馈。

我们欢迎你的建议: