这篇讲流水线显示失败时,怎么找到第一处真正的报错,而不是反复重跑。看完你可以按「运行详情 → 失败的任务 → 失败步骤的日志」往下看,对照退出码和 失败诊断,分辨镜像拉取、代码检出、命令找不到和超时。任务在 YAML 里叫 Job,是一组按顺序执行的步骤;运行器(Runner)是装在构建机上、实际执行这些步骤的程序。
AngusGit 的流水线在团队版和企业版中提供;社区版没有 CI/CD 菜单,本文的操作不适用。
下文的截图以示例仓库 xlliu/test-cicd-example 上的流水线 mcp-sample-fail 为例,对应的是它的 运行 #3。这次运行由手动触发,跑在运行器 priv-1 上,提交是 98d2f2a;失败的任务名是 fail,步骤名是 Fail on purpose。从步骤名可以看出这是一个故意失败的演示步骤,所以日志里只有检出代码的记录,没有编译错误。
1. 找到失败的那次运行
- 打开流水线 侧栏进入 CI/CD → 流水线,点流水线名称。详情页默认打开 运行记录 页签。
- 找到失败的运行 在运行记录里,可以按状态筛选,选 失败;也可以按 触发方式 筛选,例如只看 合并请求 触发的运行;还可以按分支过滤。找到失败的那次运行后,点它的序号进入运行详情。
运行详情的标题是「运行 序号」。顶部有 刷新、对比、重跑 和 重跑失败 Job 几个按钮:重跑 会把这次运行里的任务再跑一遍,重跑失败 Job 只重跑失败的任务;运行还没结束时,还会多出一个 取消运行。按钮下方是 任务、触发参数、制品仓库 三个页签。
对比 用来选另一次运行,比较两次运行的状态和耗时差异。如果昨天还成功、今天就失败了,拿最近一次成功的运行来对比,能很快看出是哪个任务从成功变成了失败。
2. 从失败的任务找到失败的步骤
在 任务 页签里,每个任务占一行,前面是状态,后面是任务名。点任务前的箭头会展开它的步骤,再点步骤前的箭头会展开这一步的日志。
失败和正在运行的任务与步骤会自动展开,不必逐个去点;页面也会自动滚动到第一个失败的任务。下表列出任务列表里常见的几种状态,以及各自应该先看哪里:
| 你在任务列表里看到的 | 含义 | 先看哪里 |
|---|---|---|
| 任务 失败 | 这个任务里有步骤失败了 | 展开它下面状态为 失败 的步骤 |
| 任务 超时 | 任务整体运行时间超过了上限(默认 3600 秒) | 看超时前最后几行日志,或调大 runner.resources.timeout
|
| 任务 已跳过 | 它依赖的上游任务失败了,所以没有执行 | 先修上游失败的任务 |
| 步骤旁的 退出码: 1 | 这一步的命令以非 0 状态退出(为 0 时不显示) | 看该步骤日志的最后二三十行 |
| 步骤日志区显示「步骤尚未开始执行。任务在准备工作区时失败。」 | 任务在准备代码阶段就失败了,所有步骤都没开始 | 看第一个步骤日志里的 Git clone failed: …
|
表里的退出码,是命令结束时返回给系统的数字:0 表示成功,非 0 表示失败。如果多个任务都失败了,先看最早失败、并且状态不是 已跳过 的那一个,因为后面的失败常常是它连带出来的。
3. 在日志里找报错
步骤日志展开在步骤下方,左侧有行号。正在运行的步骤会实时刷新,并自动跟随到最新一行;你向上滚动时,页面会停止跟随,方便查看前面的内容。
日志区有几个常用操作:
-
搜索。 在 搜索日志... 里输入
ERROR、FAILED、Exception,或者你怀疑出问题的文件名。注意,搜索只覆盖已经加载出来的日志;搜不到时,先把更早的日志加载出来再搜。 - 看更早的部分。 日志很长时,页面先只显示末尾一段,并提示「仅显示末尾日志,搜索只覆盖已加载段。完整内容请下载。」点 加载更早日志 可以往前翻。示例运行的日志只有十几行,所以不会出现这句提示。
- 跳到底部。 日志工具条右侧的 跳到底部,用来回到最新一行。
- 下载。 点 下载 可以把这一步的完整日志存到本地,再用你熟悉的编辑器打开查看。
从后往前看。 报错原因通常在日志的最后二三十行,因为编译错误、失败的测试名、command not found 这类信息,都会在命令退出前打印出来。如果最后几行只是「构建失败」这样的总结,就再往上找第一处 ERROR。
日志里的密钥会被替换成 ***,或者显示成 password=***MASKED*** 这样的形式。这是平台自动遮住了密钥,日志本身并没有损坏。
对照上面的运行详情截图:步骤日志左侧是行号,工具条上依次是 搜索日志...、跳到底部 和 下载。示例里这条日志的最后一行是 INFO: git checkout complete,里面没有 ERROR。
4. 让「失败诊断」先看一遍
失败或超时的任务旁边,有一个 失败诊断 按钮。点开后,对话框的说明是「基于失败日志的规则诊断,给出可能根因与修复建议」,内容包括:
- 一个类别,例如 配置错误、鉴权失败、容器错误;
- 置信度,例如 85%;
- 根因:用一句话说明它认为的原因;
- 修复建议:几条可以尝试的改法。
任务失败后,系统会自动做一次诊断。如果打开时显示「暂无诊断结果,可手动触发一次日志规则诊断」,点 触发诊断 即可。
失败诊断默认用预设的规则去匹配日志里的常见错误,给出的只是建议,不会修改你的代码或 YAML。置信度高的建议可以直接照着试;置信度低的,最好回到日志里自己确认。如果诊断不准,可以在对话框下方的 反馈 里写明实际原因,再点 提交反馈。
以示例中的 fail 任务为例,它的日志对不上任何已有规则,所以任务行下面显示的摘要是:未知原因 · 没有规则匹配任务「fail」的步骤「Fail on purpose」;最后一行日志:INFO: git checkout complete。点 失败诊断 后,对话框标题是「任务「fail」的失败诊断」,类别徽章是 未知原因。摘要、根因和修复建议都跟随控制台语言显示;控制台为中文时,根因写着「现有日志规则判断不出原因。最后一行日志:INFO: git checkout complete」,修复建议是「打开这一步的完整日志」和「检查运行器上的环境和依赖」。
这一步没有记录退出码,所以任务行和诊断里都没有出现「退出码」。反过来,如果最后一行日志同样只是 INFO,但步骤或任务记录了非 0 退出码,摘要后面还会接上这个退出码。当日志能匹配上某条规则时,类别会换成 配置错误、鉴权失败 这一类,正文同样按当前控制台语言显示。不过有两种例外:通知和导出使用的是诊断结果保存时的英文快照;没有规则名的旧记录,以及由模型生成的自由文本,继续显示当时保存的原句。
5. 几类常见的失败
下表整理了几类常见失败在日志里的样子、原因和改法:
| 你在日志里看到的 | 原因 | 怎么改 |
|---|---|---|
ERROR: Failed to pull image …,或 Timed out pulling image … after 300s
|
构建机拉不到 image 指定的镜像:地址写错、访问不到镜像仓库,或仓库需要登录 |
在构建机上执行 docker pull <镜像地址> 试一下;内网环境把镜像推到内网镜像仓库,YAML 改用内网地址 |
步骤都没开始,日志区提示「任务在准备工作区时失败」,第一个步骤的日志里有 Git clone failed: …
|
任务开始前拉取代码失败,常见是网络或认证问题 | 看冒号后面的具体原因;认证问题的诊断类别通常是 鉴权失败 |
command not found,退出码 127 |
这一步用到的命令在执行环境里不存在 | DOCKER 任务换一个带这个命令的镜像,或在步骤里先安装;NATIVE 任务到构建机上安装 |
Step timed out after 1800 seconds(容器任务里是 Step timed out after 1800s) |
这一步的运行时间超过了 YAML 里 timeout 设置的秒数,步骤状态显示为 失败
|
先确认是真慢还是卡住:真慢就调大 timeout;卡住就看超时前最后几行日志,常见是在等输入或等网络 |
任务显示 超时(自动重试几次仍超时后显示为 失败),原因是 Job execution exceeded timeout of 3600s
|
整个任务的运行时间超过了上限,默认 3600 秒 | 在任务的 runner.resources.timeout 里调大(单位是秒),或者把任务拆小 |
| 编译错误、测试失败 | 代码本身的问题 | 在本地复现并修复,推送新提交 |
表中的 DOCKER 和 NATIVE 是任务的执行模式:DOCKER 任务在运行器启动的容器里执行,NATIVE 任务直接在构建机(宿主机)上执行。另外,步骤级的 timeout 和任务级的 runner.resources.timeout 单位都是秒;其中步骤的 timeout 可以填 1 到 86400,目前只能在 YAML 里修改,可视化编辑器里没有这一项。
6. 改完之后
- 偶发问题(例如下载依赖时网络抖动):打开那次运行,点 重跑。重跑会基于同一个提交再跑一次,并复制原运行的触发参数。
- 代码或配置问题:修改后提交并推送。推送会按触发规则自动发起一次新的运行,不需要再手动重跑旧的那次。
- 确认已经修好:用 对比 拿新运行和失败的那次对照,确认原来失败的任务已经变成成功。
7. 下次失败时第一时间知道
想在下次失败时第一时间收到消息,可以在 CI/CD → 配置 → 通知管理 里点 新建通知,触发事件勾选 流水线失败 或 任务失败,渠道可选 Slack、钉钉、企业微信、飞书、邮件或 Webhook。保存前可以先点 发送测试,确认渠道能收到消息。
常见问题
步骤日志里没有时间,怎么看哪一步慢?
步骤日志不显示每一行的时间。要看耗时,可以用运行详情里的 对比,它会列出每个任务的耗时和变化;也可以在步骤命令里自己打印时间,例如执行 date 命令。
运行器的日志在哪?和步骤日志有什么区别?
运行器(Runner)是装在构建机上、负责执行任务的程序,它有自己的进程日志。打开 CI/CD → 运行器,进入运行器详情的 运行日志 页签就能看到,页面说明是「Runner 进程日志,包含注册、心跳、接单、拉镜像和步骤执行记录。步骤的标准输出在对应运行详情中查看。」所以,排查构建本身的错误看步骤日志;只有排查运行器接不到任务、拉镜像异常这类问题时,才需要看运行器日志。
任务跑着跑着回到了等待中,是失败了吗?
这不算失败。通常是执行它的运行器中途断开了连接,AngusGit 把任务放回队列,等另一台运行器来接。排查方法见文末参考文章里的「运行器不接任务」一文。
小结
流水线失败时,按顺序往下找:先在 运行记录 里打开失败的运行,再在 任务 页签里找到第一个失败(而不是被跳过)的任务和它下面失败的步骤,然后从这一步日志的最后几十行往上看。日志支持搜索、加载更早的部分和下载完整内容;拿不准原因时,点 失败诊断 看 根因 和 修复建议。镜像拉取、代码检出、命令找不到和超时这几类失败,日志里都有固定的提示文字,可以对照第 5 节的表格处理。偶发问题直接点 重跑,代码或配置问题改完再推送。
结论: 排查流水线失败时,先在运行详情的 任务 页签找到第一个 失败(非 已跳过)的任务和它的失败步骤,再对照退出码、末尾日志和 失败诊断 修复,最后重跑或推送。


Top comments (0)