SRE – HDUO Lab

核心结论：Jenkins Pipeline 中的 Groovy 并非标准 Groovy，底层强制执行 CPS（Continuation Passing Style）转换以支持跨节点和重启的断点续跑。在 Shared Library 中滥用大对象、复杂闭包或未实现 Serializable 的原生 Java 类，会使 Master JVM 在状态序列化时直接 OOM。必须通过 @NonCPS 隔离重度计算逻辑，并结合 JCasC 实现基础设施不可变。

故障现场：Master 的静默死亡

排查过程中接到告警，某核心业务构建集群的 Jenkins Master（版本 2.440.1 LTS，JDK 17）Load Average 突然飙升至 80+，UI 完全无响应，所有挂载在 K8S 上的动态 Agent 任务卡死在 Pending 或执行态断联。

登机排查，直接看 JVM 指标：

# jstat -gcutil <pid> 1000 5
  S0     S1     E      O      M     CCS    YGC     YGCT    FGC    FGCT     GCT   
  0.00 100.00 100.00  99.98  95.21  92.14  14521  124.512   512  1421.112 1545.624

Old Gen 打满，FGC 极其频繁且回收率几乎为 0。查看业务监控看板，并发构建数仅为平时的高峰期均值（~150 concurrent builds），排除了纯粹的并发量冲击。

立刻通过 jmap -dump:format=b,file=heap.hprof 抓取现场，并重启服务恢复业务。 MAT 分析 Heap Dump 显示，com.cloudbees.groovy.cps.Next 和 java.util.LinkedHashMap 对象占据了 85% 的堆内存。进一步展开引用链，发现全部指向 workflow-cps 插件的 ProgramData 对象。这说明：Pipeline 的状态持久化机制正在吞噬内存。

为什么简单的 Groovy 循环会拖垮 Jenkins Master？

很多人习惯把 Jenkins 当成一个能够运行 Groovy 脚本的普通 Cron Server，这在 Pipeline As Code 时代是致命的认知误区。

为了实现 Pipeline 可以在 Master 重启后从中断处继续执行（Resiliency），Jenkins 引入了 CPS（Continuation Passing Style）转换。当你编写一段看似普通的 for 循环时，Jenkins 在编译期会对抽象语法树（AST）进行劫持和重写：

每执行一行代码，CPS 引擎都会将当前作用域内的所有局部变量、调用栈打包成一个 Continuation 对象。
这些对象会被序列化（基于 XStream）并持久化到磁盘（通常是 builds//program.dat），同时缓存在内存中。

问题代码最终定位在业务团队近期提交的 Shared Library vars/deployK8s.groovy 中：

// 典型的夺命代码：全局作用域的大字典解析 + 跨节点持有
def call(String env) {
    // 1. 读取并解析一个高达 5MB 的 Kubernetes Manifest 集合字典
    def hugeManifestMap = readYaml(file: "manifests/all-services.yaml")

    // 2. 在外层作用域遍历
    hugeManifestMap.each { svcName, config ->
        node('k8s-agent') { // 3. 跨越节点上下文
            sh "echo Deploying ${svcName}"
            // ... 复杂的 YAML 替换与 kubectl apply
        }
    }
}

底层原理解析： 当上述代码执行到 node('k8s-agent') 触发跨节点调度时，Pipeline 会挂起当前线程。此时，CPS 必须保存当前的环境状态以便稍后恢复。而 hugeManifestMap 是闭包外层的局部变量，CPS 不得不把这个 5MB 的嵌套 LinkedHashMap 及其对应的迭代器对象完整序列化。在 150 个并发任务叠加下，这导致了极其可怕的写放大和内存膨胀：每次 sh 步骤执行，CPS 都要在内存里克隆并序列化这个巨大的上下文，最终瞬间撑爆 Master 的 JVM 堆。

防御性架构重构与最佳实践

针对这种滥用 Shared Library 引发的雪崩，必须在代码规范和基础设施配置两方面做防御。

1. 使用 @NonCPS 隔离不可序列化与重度逻辑

对于不需要断点续跑的纯计算、数据转换、大对象解析逻辑，强制使用 @NonCPS 注解。被 @NonCPS 标记的方法会在普通的 Java 线程池中作为原生代码执行，不会进行状态序列化。

修复后的 Shared Library 实践：

import com.cloudbees.groovy.cps.NonCPS

def call(String env) {
    // 仅在局部获取所需的小数据集合，避免整个大字典逃逸到 CPS 上下文
    List<String> svcNames = extractServiceNames("manifests/all-services.yaml")

    for (int i = 0; i < svcNames.size(); i++) {
        def svc = svcNames[i]
        node('k8s-agent') {
            sh "echo Deploying ${svc}"
            // 每次部署仅传递当前需要的字符串对象
        }
    }
}

@NonCPS
List<String> extractServiceNames(String filePath) {
    // 这里使用标准的 Java/Groovy 解析逻辑
    // 不会被 CPS 劫持，执行极快，不占用 Pipeline 持久化内存
    def parser = new org.yaml.snakeyaml.Yaml()
    def rawMap = parser.load(new File(filePath).text)
    return rawMap.keySet().toList()
}

注：在 @NonCPS 方法中绝对不能调用任何 Pipeline Step（如 sh, echo, node），否则会导致 IllegalStateException 或静默失败。

2. JCasC 声明式治理 Shared Library

为了避免通过 Jenkins UI 手工配置 Shared Library 带来的不可追溯和版本混乱，我们全面采用 Jenkins Configuration as Code (JCasC) 来固化基础设施。将全局 Shared Library 配置下沉到不可变的代码仓库中（jcasc/jenkins.yaml）：

unclassified:
  globalLibraries:
    libraries:
    - defaultVersion: "v1.5.2" # 严禁使用 master/main 分支，必须绑定 Tag
      name: "ops-shared-lib"
      retriever:
        modernSCM:
          scm:
            git:
              credentialsId: "git-bot-token"
              id: "shared-lib-scm"
              remote: "https://gitlab.internal.com/devops/jenkins-shared-library.git"
              traits:
              - gitBranchDiscovery()
      # 开启缓存以减轻拉取对 Master 的 I/O 压力
      cachingConfiguration:
        refreshTimeMinutes: 1440

配合 K8S Helm Chart 部署 Jenkins，任何配置变更只能通过提交 MR 修改此 YAML 来触发 Pod 滚动更新，彻底掐断了手工污染配置的可能。

常见问题 (FAQ)

Q1：Pipeline 中经常出现 java.io.NotSerializableException: java.util.regex.Matcher 报错，如何根治？ 这是由于正则表达式的 Matcher 对象内部包含 native 指针引用，无法通过 XStream 序列化。如果代码写成 def matcher = text =~ /pattern/，且该变量跨越了 CPS 步骤（例如在 sh 之前定义并在其后使用），就会报错。解决思路：将正则匹配逻辑封装到 @NonCPS 方法中返回基础类型（String/Boolean），或者在需要跨步骤时主动置空：matcher = null。

Q2：Jenkins Master 异常重启后，K8S 上会有大量状态为 Running 的僵尸 Agent Pod，如何自动清理？ 在动态 Agent 架构中，Master 宕机会导致 JNLP 长连接断开。如果不做处理，这些 Pod 将长期挂起。在 JCasC 的 podTemplate 配置中，务必显式设置 activeDeadlineSeconds，并通过 kubernetes-plugin 的清理策略来兜底：

jenkins:
  clouds:
    - kubernetes:
        name: "k8s-cluster"
        serverUrl: "https://kubernetes.default"
        # 定义全局 Agent Pod 的最长存活时间（例如 2 小时）
        podRetention: "never"

同时在业务的 yaml 中确保 activeDeadlineSeconds: 7200 兜底，防止挂起任务长期吃空节点计算资源。

Q3：如何本地单元测试 Jenkins Shared Library，避免每次都要上生产环境试错？ 强推 JenkinsPipelineUnit 框架。可以在本地使用 Spock/JUnit 编写测试用例，框架会模拟 CPS 引擎和所有的内置步骤（sh, node, readYaml）。通过模拟返回结果并断言调用栈，可以在本地完成 90% 的逻辑校验，彻底告别在 Jenkins 上盲目触发几十次构建来 debug 的窘境。

标签： SRE