腾讯云 CNB 流水线配置从入门到精通

摘要：

腾讯云云原生构建（CNB）通过一份 .cnb.yml 文件定义代码拉取、构建、测试、部署全流程。本文从配置结构、触发规则、节点选型到计费约束，系统讲解流水线配置方法，附多个可运行示例。

一、认识腾讯云 CNB 流水线

腾讯云云原生构建（Cloud Native Build，简称 CNB）是腾讯云推出的 AI Native Git 平台，基于 Docker 生态，通过声明式语法实现代码托管、云原生构建、云原生开发、制品库等功能。流水线配置的核心是一份名为 .cnb.yml 的 YAML 文件，放在代码仓库根目录，与代码同源管理、版本可追溯。

CNB 的流水线采用 Pipeline / Stage / Job 三层结构：

• Pipeline（流水线）：由一次触发事件产生的一次完整执行过程。
• Stage（阶段）：流水线中的执行单元，同一 Stage 内的多个 Job 并行执行。
• Job（任务）：最小执行单元，在独立的 Docker 容器中运行。

这种分层设计让开发者可以清晰地把「安装依赖 → 执行测试 → 构建镜像 → 推送制品」拆成若干阶段，每个阶段再细分为多个并行任务。相比传统需要自己维护 CI 服务器的方案，CNB 把整套基础设施完全托管化，开发者只需编写声明式配置，平台即可自动完成后续的资源调度与执行。

二、配置文件结构与首个流水线

.cnb.yml 的基本结构由三部分组成：顶层的分支匹配规则、中间的事件触发器、底层的流水线定义。一个最简配置通常长这样：

# 匹配 main 分支
main:
  push:
    - stages:
        - name: hello world
          image: node:20
          script: node -v

这段配置的含义是：当 main 分支收到 push 事件（即代码推送）时，拉起一条流水线，在 node:20 镜像中执行 node -v 打印 Node.js 版本。

一个更贴近真实开发的完整示例，覆盖安装依赖、测试、构建并推送 Docker 镜像到 CNB 制品库：

main:
  push:
    - docker:
        image: node:20
        volumes:
          - /root/.npm:copy-on-write
      stages:
        - name: 安装依赖
          script: npm ci --frozen-lockfile
        - name: 执行测试
          script: npm test
        - name: 构建并推送镜像
          script: |
            docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT} .
            docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT}

配置中几个内置变量值得记住：

• ${CNB_DOCKER_REGISTRY}：CNB 制品库的 Docker 仓库地址。
• ${CNB_REPO_SLUG_LOWERCASE}：当前仓库路径的小写形式。
• ${CNB_COMMIT}：当前提交的 commit 哈希。

使用这些内置变量，可以让镜像 Tag 自动与提交版本绑定，实现构建产物的版本追溯。volumes 声明的缓存目录配合 copy-on-write（写时复制），能在并发构建时避免缓存读写冲突，同时把 node_modules、/root/.npm 等目录缓存下来加速后续构建。

三、触发规则与分支匹配

流水线的触发由「分支 + 事件」共同决定。顶层键是分支匹配规则，支持 glob 模式；其下是事件名，再往下才是具体的流水线列表。

常见的 Git 操作事件包括：

• push：代码推送到分支时触发。
• commit.add：有新提交加入分支时触发。
• branch.create / branch.delete：分支创建或删除时触发。
• pull_request 系列：PR 创建、更新、合并等事件触发。

除了 Git 事件，CNB 还支持页面操作事件（如 web_trigger 手动触发、云原生开发事件）、API 请求事件（api_trigger）、定时任务事件（schedule）以及 Issue 事件等。通过组合这些事件，可以为不同分支配置差异化的构建流程，例如「开发分支只跑测试、主分支才构建并推送镜像」。

下面示例展示为不同分支配置不同行为：

# 主分支：构建并推送镜像
main:
  push:
    - stages:
        - name: build and push
          image: node:20
          script: |
            npm ci
            npm run build
            docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
            docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

# 开发分支：仅执行测试
develop:
  push:
    - stages:
        - name: run tests
          image: node:20
          script: npm ci && npm test

四、构建节点选型与资源规格

CNB 将构建任务分发到各构建节点执行，集群以 Docker 镜像作为构建环境。通过 runner.tags 指定节点架构，通过 runner.cpus 配置 CPU 核数。平台官方提供的构建节点规格如下表所示：

所有节点的最大构建时长均为 18 小时。为防止滥用，集群可能会对最大时长进行动态管控，以实际管控为准。内存规格默认按 CPU 核数的 2 倍计算，例如申请 8 核即对应 16GB 内存。

在流水线中按需声明节点资源的写法如下：

main:
  push:
    - runner:
        tags: cnb:arch:amd64
        cpus: 8
      stages:
        - name: uname
          script: uname -a

对于需要特定硬件的场景（例如 iOS 构建、Windows 桌面应用打包），根组织管理员还可以自助接入 Mac、Windows 自托管构建机作为组织专属构建资源。接入路径为：进入 根组织 / 组织设置 / 构建节点 页面，点击「新增 Runner」，填写名称、标签后保存，再在目标构建机上执行弹窗提供的一键接入脚本，节点状态变为「在线」即接入成功。接入后通过 runner.namespace: group 加 runner.tags 即可调度到该节点。

五、环境变量与密钥管理

流水线中常常需要引用数据库密码、第三方 API Token 等敏感信息。CNB 提供两种方式管理这类配置：

• 环境变量（envs）：在流水线配置中直接声明 env 字段，适合非敏感或临时性配置。
• 密钥仓库（imports）：把敏感信息单独存放在一个私有仓库的 YAML 文件中，通过 imports 字段在流水线中引用，避免密钥硬编码进主配置。

引用密钥仓库的示例：

main:
  push:
    - imports: https://cnb.cool/你的组织/密钥仓库/-/blob/main/envs.yml
      stages:
        - name: 部署到 EdgeOne
          image: node:20
          script: npx edgeone pages deploy ./dist -n 项目名称 -t $EDGEONE_API_TOKEN

被引用的 envs.yml 中存放实际的密钥值，例如 EDGEONE_API_TOKEN: 你的令牌。这样密钥与业务代码分离，既便于统一维护，也降低了泄露风险。

六、计费方式与约束限制

配置流水线之前，了解 CNB 的计费规则和约束限制，有助于避免任务中途被终止或产生意外费用。

社区版采用「免费额度 + 超额按量计费」模式，主要计费项与免费额度如下表所示：

核时的计算方式为「CPU 核数 × 使用小时数」，例如 8 核运行 1 小时即消耗 8 核时。以云原生构建-CPU 的 160 核时免费额度为例，若使用 8 核节点，可免费运行约 20 小时；使用 16 核节点则约 10 小时。免费额度月底清零，不叠加至次月。GPU 资源（构建和开发）均不提供免费额度，使用即按 0.5 元/核时计费。

用量可在 组织 / 设置 / 用量管理 页面查看组织级别的整体用量，也可在 仓库 / 设置 / 用量统计 查看仓库级详情。免费额度用尽后，相关能力将受限（例如 AI Credits 用尽后，NPC 等 AI 能力将不可用）；如需提升用量上限，可在 组织 / 设置 / 用量管理 中绑定腾讯云预算。社区版采用月结后付费，月初按上个自然月的实际用量自动扣费，无需主动续费。

配置流水线时还需注意以下约束：

• 构建超时：构建节点最大运行时长为 18 小时，超时任务会被终止。
• NPC 事件限制：当 Issue 或 PR 评论数超过 100 条时，对应的 issue.comment、pull_request.comment 及 @npc 事件不再触发流水线，一次最多支持触发 10 个 NPC 事件。
• 企业版部署：企业版部署在客户腾讯云 VPC 中，部署资源消耗（如 TKE 集群费用）由客户自行承担，按注册用户数乘以订阅周期预付费，定价为 1024 元/授权用户/年，100 个授权用户起售，支持 1 个月免费试用。

七、小结

从一份简单的 .cnb.yml 开始，我们可以逐步构建出覆盖多分支、多事件、多节点规格的完整流水线。掌握「分支匹配 → 事件触发 → Stage/Job 编排 → 节点选型 → 密钥管理 → 计费约束」这条主线，就能把 CNB 的声明式构建能力真正落到日常研发中。无论是个人项目的自动测试，还是团队级的镜像构建与部署，CNB 都提供了开箱即用的托管化能力，让你把精力集中在代码本身。

如果你正在寻找一套与代码同源管理、按需弹性伸缩的云原生构建方案，不妨试试腾讯云 CNB，几分钟即可跑通一条流水线。