腾讯云 CNB 构建 Docker 镜像：从 Dockerfile 到制品库的全流程

摘要：

本文介绍如何用腾讯云 CNB 通过声明式 .cnb.yml 流水线构建 Docker 镜像并推送至制品库，涵盖环境准备、配置编写、镜像标签命名、推送操作与计费说明，帮助开发者实现镜像的一键自动化构建。

一、腾讯云 CNB 与 Docker 镜像构建

腾讯云云原生构建（Cloud Native Build，简称 CNB）是腾讯云推出的 AI Native Git 平台，基于 Docker 生态，通过声明式语法将代码托管、云原生构建、制品库等能力整合在同一平台中。对于需要交付容器镜像的团队而言，CNB 的核心价值在于：把「编写 Dockerfile → 构建镜像 → 推送制品库」这一传统上依赖本地命令行的流程，全部沉淀为一份可版本管理的 .cnb.yml 配置文件，实现镜像构建过程的自动化与可复现。

在这套流程中，三个组件协同工作：

CNB 的构建节点规格覆盖较广：amd64 架构支持 1～64 核 CPU，arm64/v8 架构支持 1～16 核 CPU，GPU 节点则固定为 16 核加 48GB 显存，所有节点的最大构建时长为 18 小时。对于常规的镜像构建任务，开发者可根据镜像体积和编译负载，在配置中按需声明节点规格。

二、构建前的准备工作

在编写流水线之前，需要完成两项基础准备：一是仓库中准备好可构建的 Dockerfile，二是确认构建所需的资源配额。

首先，确保代码仓库根目录存在一份结构正确的 Dockerfile。以下是一个以 Node.js 应用为例的多阶段构建文件：

# 构建阶段
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 运行阶段
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/main.js"]

其次，了解构建资源的免费额度有助于控制成本。社区版每月提供云原生构建 CPU 160 核时的免费额度，对象存储 100 GiB 的免费额度用于存放制品、LFS 对象等。以 8 核节点为例，160 核时约可换算出 20 小时的构建时长（即免费额度按节点核数折算的可用时长），足够覆盖日常迭代中的镜像构建需求。

三、编写 .cnb.yml 构建配置

.cnb.yml 是 CNB 流水线的核心配置文件。构建 Docker 镜像的最小配置包含三个要素：声明 docker 服务、设置镜像标签、执行 build 与 push。下面是一份可直接运行的配置，用于在 main 分支发生 push 事件时自动构建并推送镜像：

main:
  push:
    - services:
        - docker
      stages:
        - name: set docker tag
          script: echo -n "${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest"
          exports:
            info: IMAGE_TAG
        - name: docker build
          script: docker build -t $IMAGE_TAG .
        - name: push image
          script: docker push $IMAGE_TAG

配置说明：

• services 中的 docker 声明当前 Job 需要 Docker 环境，平台会自动提供 docker 命令与守护进程。
• set docker tag 阶段利用 CNB 内置环境变量 CNB_DOCKER_REGISTRY（制品库地址）和 CNB_REPO_SLUG_LOWERCASE（仓库路径小写）拼接出完整的镜像标签，并通过 exports 将结果导出为 IMAGE_TAG 变量供后续阶段使用。
• docker build 与 push image 阶段依次完成镜像构建与推送，整个流程在一次流水线执行中串行完成。

流水线的触发方式灵活多样，除 push 事件外，还支持 commit.add、branch.create、pull_request、定时任务（schedule）以及 web_trigger 手动触发等。团队可以按需在 main、develop 等不同分支上配置差异化的构建策略，例如仅在合并到主干时推送正式镜像，在特性分支上只执行构建而不推送。

四、镜像标签命名与多版本管理

镜像标签（Tag）是制品库中区分镜像版本的关键。CNB 提供了多个内置环境变量，便于在标签中注入分支、提交等上下文信息，实现自动化的版本标记：

在实际项目中，建议避免长期使用 latest 作为单一标签，而是采用「固定标签 + 提交哈希标签」的组合策略。做法是先用主标签构建镜像，再用 docker tag 为同一镜像追加一个提交哈希标签，最后一次性推送两个标签：

main:
  push:
    - services:
        - docker
      stages:
        - name: set docker tag
          script: echo -n "${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest"
          exports:
            info: IMAGE_TAG
        - name: docker build
          script: docker build -t $IMAGE_TAG .
        - name: add commit tag
          script: docker tag $IMAGE_TAG ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT_SHORT}
        - name: push image
          script: |
            docker push $IMAGE_TAG
            docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:${CNB_COMMIT_SHORT}

这样既能通过 latest 标签快速拉取最新镜像，又能通过提交哈希标签精确定位某一次构建的产物，便于问题排查与版本回滚。

五、推送镜像至制品库

CNB 流水线内置了触发者的访问凭据，因此推送到 CNB 自有 Docker 制品库时无需额外配置登录信息，直接 docker push 即可。这与推送到第三方制品库存在明显区别：若目标为外部仓库（如 Docker Hub 或企业私有 Harbor），则需要在配置中通过 imports 导入预先存放在密钥仓库中的凭据，并增加 docker login 阶段完成认证。

推送到第三方制品库的配置示例如下：

main:
  push:
    - services:
        - docker
      imports: https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/docker-envs.yml
      stages:
        - name: docker login
          script: echo "${DOCKER_PWD}" | docker login -u ${DOCKER_USER} --password-stdin ${DOCKER_REGISTRY}
        - name: set docker tag
          script: echo -n "${DOCKER_REGISTRY}/${DOCKER_GROUP}/${DOCKER_REPO_NAME}:$CNB_COMMIT_SHORT"
          exports:
            info: IMAGE_TAG
        - name: docker build
          script: docker build -t $IMAGE_TAG .
        - name: push image
          script: docker push $IMAGE_TAG

其中 docker-envs.yml 文件用于存放第三方仓库的登录凭据，内容包含用户名、密码、仓库地址等信息，通过 imports 以安全方式注入流水线，避免将敏感信息硬编码进 .cnb.yml。

镜像推送成功后，可在源码仓库的「制品库」中查看产出的 Docker 镜像，自由切换 Docker 或 Helm 制品类型，查看制品地址、标签列表、推送时间与下载量等信息。Docker 制品的推送遵循两种命名规则：同名制品的路径与仓库路径一致，非同名制品则以仓库路径作为命名空间，在仓库路径后追加制品名称。

结语

从一份 Dockerfile 到一份 .cnb.yml，腾讯云 CNB 把镜像构建的各个环节封装为声明式的流水线配置，让开发者无需在本地反复执行构建命令，即可在代码推送时自动完成镜像的构建、标签管理与制品库推送。配合灵活的触发规则、多版本标签策略以及清晰的计费体系，CNB 为个人开发者和研发团队都提供了一套可落地的容器镜像构建方案。

如果你想体验基于 Docker 生态的声明式云原生构建，可以了解腾讯云 CNB的完整能力。