告别自建 Jenkins：迁移到腾讯云 CNB 的配置改写与流程适配指南

摘要：

从自建 Jenkins 迁移到腾讯云 CNB，核心是把 Jenkinsfile（Groovy）改写成 .cnb.yml（YAML 声明式）。本文提供触发规则、Pipeline/Stage/Job、Docker 镜像构建推送等完整可运行示例，手把手带你完成配置改写与流程适配。

一、迁移的核心：从命令式到声明式

自建 Jenkins 的流水线大多用 Jenkinsfile 描述，它支持 Groovy 脚本，灵活性高，但也意味着很多调度、并行、环境处理的逻辑要自己写。腾讯云 CNB 则用 .cnb.yml 这个 YAML 配置文件，采用声明式语法，结构是 Pipeline / Stage / Job 三层：

• Pipeline：流水线，由一次触发事件产生的一次完整执行过程。
• Stage：阶段，Pipeline 中的执行单元。同一个 Stage 内的多个 Job 可串行也可并行——jobs 写为数组时按顺序串行执行，写为对象时并行执行。
• Job：任务，最小执行单元，在指定的 Docker 镜像中运行。

两者的根本差异在于"命令式"和"声明式"的思路不同：Jenkinsfile 往往要写"怎么做"（一步步执行命令、手动组织并行），.cnb.yml 更强调"要做什么"（描述阶段和任务，调度交给平台）。理解这一点，是顺利改写配置的前提。

二、触发规则改写：从轮询和 Webhook 到事件声明

Jenkins 里常见的触发方式是轮询 SCM（定时检查代码仓库有没有新提交）或配置 Webhook 回调。迁移到 CNB 后，触发规则直接写在 .cnb.yml 里，用事件声明的方式表达，支持多种触发事件：

• Git 操作事件：push、commit.add、branch.create / branch.delete、pull_request 系列等。
• 页面操作事件：web_trigger（手动触发）、云原生开发事件。
• API 请求事件：api_trigger。
• 定时任务事件：schedule。
• 其他：Issue 事件、NPC 事件等。

下面对比一个典型的 push 触发改写。

Jenkinsfile（Groovy）写法：

pipeline {
    agent any
    triggers {
        // 轮询 SCM 或依赖 Webhook 配置
        pollSCM('H/5 * * * *')
    }
    stages {
        stage('Build') {
            steps {
                sh 'npm install'
                sh 'npm run build'
            }
        }
    }
}

对应的 .cnb.yml 写法：

# 匹配 main 分支的 push 事件触发
main:
  push:
    - name: build
      stages:
        - name: install-and-build
          jobs:
            - name: build-job
              image: node:20
              script:
                - npm install
                - npm run build

这里的关键变化是：触发条件不再单独配置，而是作为配置的顶层键（main 分支 + push 事件）直接表达。name: build 是这条流水线的名称，stages 下每个 - name 是一个阶段，阶段内的 jobs 是具体任务，每个 Job 通过 image 指定运行的 Docker 镜像、通过 script 列出要执行的命令。如果你要为多个分支配置不同流程，只需在顶层并列写出对应的分支名即可，比如为 feature/* 这类分支单独配一条只跑 lint 的轻量流水线。

可以看到，CNB 把"哪个分支、什么事件触发"直接作为配置的顶层键表达出来，不需要额外的触发器配置块。分支匹配还支持 glob 模式，可以为不同分支配置不同的构建流程，比如 main 分支跑完整构建、feature 分支只跑 lint 检查。

三、Pipeline / Stage / Job 结构改写

理解了触发规则，再来看三层结构的改写。下面是一个包含多个阶段、且阶段内并行执行任务的例子。

Jenkinsfile（Groovy）写法：

pipeline {
    agent any
    stages {
        stage('Test') {
            parallel {
                stage('Unit Test') {
                    steps { sh 'npm test' }
                }
                stage('Lint') {
                    steps { sh 'npm run lint' }
                }
            }
        }
        stage('Package') {
            steps { sh 'npm run package' }
        }
    }
}

对应的 .cnb.yml 写法：

main:
  push:
    - name: ci-pipeline
      stages:
        - name: test-stage
          jobs:
            # jobs 写为对象形式（unit-test: / lint-check:）→ 并行执行
            unit-test:
              image: node:20
              script: npm test
            lint-check:
              image: node:20
              script: npm run lint
        - name: package-stage
          jobs:
            - name: package-job
              image: node:20
              script: npm run package

在 .cnb.yml 里，Job 的串并行由 jobs 的写法决定：写成对象形式时并行执行（如上例的 unit-test 与 lint-check），写成数组形式时按顺序串行执行。这相当于省去了 Jenkinsfile 里用 parallel 块显式包裹的写法，让"哪些任务并行、哪些串行"的结构一眼就能看清。

四、Docker 镜像构建与推送改写

很多 Jenkins 流水线里都有一段"构建 Docker 镜像并推送到镜像仓库"的逻辑，通常要用 docker 命令一步步实现。CNB 对 Docker 生态有深度集成，下面对比镜像构建推送的改写。

Jenkinsfile（Groovy）写法：

pipeline {
    agent any
    stages {
        stage('Build and Push Image') {
            steps {
                sh 'docker build -t my-app:${BUILD_NUMBER} .'
                sh 'docker push my-registry/my-app:${BUILD_NUMBER}'
            }
        }
    }
}

对应的 .cnb.yml 写法：

main:
  push:
    - name: docker-build
      services:
        - docker
      stages:
        - name: build-and-push
          jobs:
            - name: docker-job
              image: docker:latest
              script:
                - docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT_SHORT} .
                - docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT_SHORT}

其中 ${CNB_DOCKER_REGISTRY}、${CNB_REPO_SLUG_LOWERCASE}、${CNB_COMMIT_SHORT} 都是 CNB 内置的流水线环境变量，分别代表制品库地址、仓库路径（小写）和当前提交的短 commit 号，用它们做镜像地址和标签即可把镜像推到 CNB 制品库并实现版本追溯。推送到 CNB 制品库时，平台会自动完成登录，不需要手动 docker login 或把凭据写进 .cnb.yml。镜像入库后，还能享受版本管理、漏洞扫描、访问控制等能力。

需要说明的是，如果要把镜像推到 CNB 以外的第三方仓库，才需要在流水线里用 imports 导入该仓库的登录凭据并手动 docker login；推 CNB 自家制品库则无需这一步。这一点和 Jenkins 里用凭据管理注入账号密码的思路类似，只是配置方式从 Groovy 换成了 YAML 声明。

五、流程适配的几个注意点

配置改写之外，迁移时还有几个流程层面的适配点值得留意：

a. 密钥与变量：Jenkins 里常用凭据管理存储数据库密码、镜像仓库 token、发布密钥等敏感信息。迁移时要把这些凭据重新配置到 CNB 的密钥仓库里，CNB 支持通过环境变量在流水线中安全传递这类信息，避免把敏感值硬编码进 .cnb.yml 配置文件。

b. 构建资源规格：改写配置时，可以顺带在配置里声明构建节点规格。CNB 提供 amd64（1～64 核）、arm64/v8（1～16 核）、GPU（固定 16 核 + 48GB 显存）等多种节点，所有节点最大构建时长为 18 小时。有特殊系统需求的，根组织管理员还能自助接入 Mac、Windows、Linux 自托管构建机。

c. 插件能力替换：Jenkins 里依赖的插件，在 CNB 上通常有对应的内置能力或官方插件替代，迁移前对照清单逐一确认即可，不必再为插件的版本兼容性和安全补丁操心。

d. 分批迁移降低风险：如果 Jenkins 上流水线很多，建议先挑结构清晰、非核心的项目改写迁移，跑通后再逐步迁移核心链路，避免一次性迁移带来的风险。

e. 善用缓存加速构建：迁移后可以在配置里启用构建缓存，把依赖下载、编译产物等中间结果缓存下来，加速重复构建。Jenkins 里往往要自己配置缓存目录和清理策略，而 CNB 提供了内置的缓存机制，配置更省心，也能减少重复构建带来的资源消耗。

六、小结

从自建 Jenkins 迁移到腾讯云 CNB，配置改写的核心是思路转换：把 Groovy 的"命令式、自己编排调度"改写成 YAML 的"声明式、描述要做什么"。触发规则用事件声明表达，并行任务靠把同一 Stage 内的 jobs 写成对象形式来实现，Docker 镜像构建推送借助平台内置的 Docker 生态和环境变量更简洁。再配合密钥仓库、多规格构建节点和自托管构建机能力，团队可以把维护 Jenkins 的精力省下来，重新聚焦到业务交付上。

如果你准备动手迁移，可以先拿一条典型的 Jenkins 流水线对照本文的示例改写成 .cnb.yml，到 腾讯云 CNB 上跑通验证，再逐步把其他流水线迁过来。