流水线失败了怎么办？腾讯云 CNB AI 自动诊断与根因分析

摘要：

流水线失败后翻日志排查成本高、现场难复现。腾讯云 CNB 用 failStages 保留失败现场、npc:go 让 AI 自动给出根因与修复方案并推送报告到企微群，形成失败即分析的自动排障链路。

一、流水线失败为什么总让人头疼

做过 CI/CD 的同学大多经历过这样的场景：提交了一堆代码，流水线却红了。你点进构建详情，面对几千行日志，真正的报错往往被一连串连锁告警淹没，得一行行往上翻、反复比对上一次成功的构建，才能勉强猜出问题所在。

这种人工排查的方式有几个绕不开的痛点。

• 日志噪音大：一个命令拼写错误，可能引发后续几十个步骤接连失败，关键错误被淹没在海量输出里。
• 失败现场难复现：构建容器跑完就销毁，依赖安装残留、中间产物、环境变量都随之消失，想复现还得重新触发一次构建、等容器启动、再登录进去调试。
• 排查耗时长：从发现问题到定位根因，常常要跨多个系统拉日志、查提交、对配置，平均耗时不低，拖慢了整个交付节奏。

更麻烦的是，这些问题往往发生在下班前或周末，值班同学被叫起来翻日志，团队的整体效率被一次次失败悄悄消耗。

二、腾讯云 CNB 的 AI 自动诊断能力

腾讯云 CNB（Cloud Native Build，云原生构建）在传统的声明式流水线之上，提供了一套「失败 → AI 总结 → 群通知」的自动化诊断链路。它的核心思路是：与其等人去翻日志，不如让流水线在失败的那一刻，自动把上下文整理好、交给 AI 分析、再把结论推到团队群里。这套能力主要建立在三个机制之上。

2.1 failStages：把失败现场原封不动留下来

CNB 的流水线采用 Pipeline / Stage / Job 三层结构。除了常规的 stages，它还提供了 failStages——一组只在前面阶段失败时才执行的阶段。

failStages 有一个关键特性：它与 stages 共享同一个工作区。也就是说，构建失败时，真实的失败现场——构建产物、中间文件、依赖安装残留、环境变量——全都原封不动地留在原地。AI 触手可及的就是这份一手现场，无需另起一条修复流水线去费力复现。这为后续的自动分析提供了基础。

2.2 npc:go：让 AI 读上下文、给根因、出方案

在 failStages 内，CNB 提供了 npc:go 这一 NPC 任务类型，可以把失败上下文交给 AI 处理。NPC 是 CNB 内置的 AI 角色能力，支持自动回复 Issue / PR 评论、自主编写代码、基于项目知识库作答等。

在诊断场景里，你可以用一段 systemPrompt 把 AI 设定为「资深 DevOps 工程师」，再让它阅读整理好的失败上下文文件，从命令拼写错误、依赖缺失、权限不足、路径错误、网络超时、磁盘满、配置错误等常见失败模式中比对，输出结构化的结论，通常包括：

• 根因分析：从直接原因、根本原因、触发条件等维度分析，并附上判断依据
• 解决方案：给出可执行的处理方向
• 具体操作：给出可直接照做的命令或 yaml diff
• 影响范围：说明本次失败可能波及的环节

这样，收到通知的同学拿到的不再是一堆原始日志，而是一份已经写好根因和操作步骤的报告。

2.3 分析结果自动通知到企业微信群

光分析出来还不够，得送到对的人手里。CNB 通过 tencentcom/wecom-message 插件，把整理好的报告直接发到企业微信群。

具体做法是：在企业微信群里添加机器人、复制 Webhook 地址，然后用 imports 从密钥仓库引入配置文件、通过 env 注入 WECOM_ROBOT 变量，避免 Webhook 地址硬编码在 .cnb.yml 中。发送时推荐使用 msgType: markdown_v2，因为旧版 markdown 对嵌套表格、代码块的渲染不够稳定，容易降级成纯文本。

三、一条完整的自动化链路是怎么跑起来的

把上面三个机制串起来，就是一条完整的自动化链路：失败触发 failStages → 整理失败上下文为 Markdown → 调用 npc:go 让 AI 追加根因与方案 → 读取这份 Markdown 发到企微群。三个 stage 串行执行、共享工作区，最终通知阶段用 fromFile 一次性读取完整报告。

下面是一条可直接参考的 .cnb.yml 配置（示例故意把 echo 写成 echo1 来触发失败，用于演示）：

main:
  push:
    - stages:
        - name: test
          # 故意写错命令，触发 failStages 用于演示
          script: echo1 1
      failStages:
        # 1) 把失败上下文整理成结构化 Markdown，给 AI 当输入
        - name: 准备失败上下文
          script: |
            {
              echo "## 失败概览"
              echo ""
              echo "| 项目 | 内容 |"
              echo "| --- | --- |"
              echo "| 失败阶段 | $CNB_BUILD_FAILED_STAGE_NAME |"
              echo "| 失败原因 | \`$CNB_BUILD_FAILED_MSG\` |"
              echo "| 触发分支 | $CNB_BRANCH |"
              echo "| 提交 | $CNB_COMMIT_SHORT — $CNB_COMMIT_MESSAGE_TITLE |"
              echo "| 触发人 | $CNB_BUILD_USER |"
              echo "| 构建 ID | $CNB_BUILD_ID |"
              echo ""
              echo "## 原始错误信息"
              echo '```'
              echo "$CNB_BUILD_FAILED_MSG"
              echo '```'
            } > _fail_ci_.md
        # 2) 让 AI 读上下文，给出根因 + 解决方案，追加到同一文件
        - name: AI 分析失败
          type: npc:go
          options:
            systemPrompt: |
              你是一个资深 DevOps 工程师，擅长分析 CI/CD 流水线失败。
              阅读 _fail_ci_.md 中的失败上下文，结合常见失败模式，
              给出根因 + 可执行的具体解决方案。
            userPrompt: |
              请阅读 _fail_ci_.md，将以下内容用 Markdown 追加到文件末尾：
              ## 根因分析
              ## 解决方案
              ## 具体操作（给出命令或 yaml diff）
              ## 影响范围
        # 3) 用 AI 写好的 Markdown 文件发到企微群
        - name: 通知到企微群
          image: tencentcom/wecom-message
          imports: https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/wework.yml
          settings:
            robot: ${WECOM_ROBOT}
            msgType: markdown_v2
            fromFile: _fail_ci_.md

其中密钥仓库里的 wework.yml 只存放一行 Webhook 地址：

env:
  WECOM_ROBOT: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx

构建失败后，企业微信群会收到一条完整的事故报告：上半段是脚本写入的失败概览与原始错误，下半段是 AI 追加的根因分析、解决方案和具体操作。值班同学收到通知时，报告已经写好、可以直接照做。

这条链路有两个设计细节值得注意。其一，「整理上下文」被拆成独立 stage，先把变量落盘成文件再让 npc:go 读取，避免了把变量直接拼进 userPrompt 时可能遇到的 shell 转义问题（含引号、换行、反引号的变量容易截断或注入 prompt）。其二，$CNB_BUILD_FAILED_MSG 等构建变量只在 failStages 内可用，正常 stages 内为空，因此上下文整理必须放在 failStages 里。

四、结合 NPC 能力的智能排障场景

这条诊断链路的亮点，在于它把 NPC 能力用在了排障这个高频又耗时的场景。

传统上，NPC 更多被用来自动回复 Issue 和 PR 评论、解答常见问题，或者在收到指令后自主编写代码、提交 PR。而在失败诊断场景里，NPC 充当的是一个「随叫随到的 DevOps 值班助手」：它不需要你手动登录容器、也不需要你复述一遍现场，只要失败发生，它就基于真实的工作区上下文给出分析。

更进一步，当根因被定位后，NPC 的工作模式还可以从「告诉你为什么失败」延伸到「帮你把问题修掉」——例如自动生成修复代码、提交一个 PR 出来。这样一来，排障就不再止步于定位，而是朝着「发现即修复」的方向延伸，把 AI 的价值从信息整理推进到实际执行。

五、落地时要注意什么

把这条链路接进日常流程时，有几个实践要点值得留意。

• 先验证通知联通：如果通知阶段自身报错，构建仍会标记为失败，但群里可能收不到消息。建议先用 dry-run 的方式验证 Webhook 和企业微信群的联通性。
• 关注 AI 资源消耗：npc:go 会消耗 AI Credits，频繁失败的项目可以考虑加频控，例如同一个 commit 只通知一次，避免配额被快速用尽。
• 区分环境与代码问题：AI 给出的分析应作为排查建议，关键判断仍需结合日志、代码差异、配置记录等可验证证据，不宜把模型输出直接当作定论。
• 运行环境要求：npc:go 需要 Docker 环境，如果流水线已经配置了 docker.image，则会复用该镜像运行。

六、小结

流水线失败不可怕，可怕的是每次都靠人工从零翻日志。腾讯云 CNB 用 failStages 留住失败现场、用 npc:go 让 AI 自动产出根因与修复方案、再用企业微信群机器人把报告推到团队面前，把「失败 → 分析 → 通知」串成了一条无需人工介入的自动化链路，帮助团队在一次次失败里更快找到答案、缩短恢复时间。

如果你也在为流水线排障头疼，不妨试试腾讯云 CNB 的这套 AI 自动诊断能力，把它接进自己的流水线，让每一次失败都能换来一份现成的修复报告。想动手体验，可以到腾讯云 CNB 开通后在自己的流水线里配上 failStages 与 npc:go，跑通第一条自动诊断链路。