告别自建 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](https://cloud.tencent.com/product/cnb) 上跑通验证，再逐步把其他流水线迁过来。
