GitLab Runner: 构建 Docker 镜像

使用 Stackhero runner 和 Docker-in-Docker，从您的 GitLab CI/CD 流水线高效构建并推送 Docker 镜像

👋 欢迎查阅 Stackhero 文档！

Stackhero 提供了一套简单易用的 GitLab Runner 云端解决方案，让您高效、无忧地运行 GitLab CI/CD 任务。您将获得以下优势：

无限制 CI/CD 构建时长：无需按分钟计费，也没有任何隐藏费用，随时运行您的流水线。

多任务并发执行：支持同时运行多个任务，加快开发进度。

支持 Docker executor 及 Docker-in-Docker：轻松在 CI/CD 流程中构建并推送容器镜像。

完美兼容 GitLab.com 及 自建 GitLab 实例。

专属私有基础设施，配备高速 NVMe/SSD 存储，确保构建过程稳定且可预测。

服务覆盖 🇪🇺 欧洲 和 🇺🇸 美国 区域，满足您团队的不同需求。

节省时间：只需几分钟即可连接您的第一个 GitLab Runner，立即开始运行流水线！

简介

使用 Stackhero GitLab Runner，每个作业都在一个全新的容器中运行，采用 Docker executor。通过启用 Docker-in-Docker（DinD），您可以在流水线中直接构建自己的 Docker 镜像。该配置会在您的作业旁边启动一个 Docker 守护进程，因此您可以在 CI/CD 流程中运行 docker build 和 docker push 命令。

每次运行都享有无限制的 CI/CD 分钟数：您可以根据需要随时构建，无需担心使用额度。您的构建缓存存储在 runner 的专用磁盘上，这意味着重复构建时可以复用之前的镜像层，大幅缩短构建时间，加快流水线执行速度。

使用 Docker-in-Docker 构建 Docker 镜像

您可以将以下示例 .gitlab-ci.yml 文件添加到您的代码仓库中。该配置会构建项目根目录下的 Dockerfile：

build-image:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker info
  script:
    # 将 "my-image" 替换为您想要的镜像名称：
    - docker build -t my-image .
    # 可选：对构建好的镜像进行快速测试：
    # - docker run --rm my-image /path/to/tests

本示例使用的是 Docker 镜像 29 版本。您可以根据需要选择更新的版本。最新的标签可在官方 Docker 镜像页面查看。

在此配置中，docker:29-dind 服务会在您的作业旁边启动一个 Docker 守护进程，DOCKER_HOST: "tcp://docker:2375" 告诉 docker CLI 使用该守护进程。声明 docker:dind 服务时务必设置 DOCKER_HOST： 否则 CLI 会静默连接到其他守护进程，导致服务配置错误时构建依然通过，从而隐藏真实问题（并导致依赖该服务的工具如 Testcontainers 失效）。DOCKER_TLS_CERTDIR: "" 表示通过内部作业网络上的非 TLS 明文端口 2375 连接。

作为更简单的替代方案，您可以省略 services 块和相关变量：Stackhero 的 runner 还通过挂载的 socket 暴露了一个可用的 Docker 守护进程，因此直接运行 docker build 也可以，无需额外配置。

使用 Testcontainers 运行测试

Testcontainers 是一个测试库，支持 Java、Go、Node.js、Python、.NET 等多种语言，可以在测试运行期间以临时 Docker 容器的形式启动真实服务。与其模拟数据库或消息中间件，不如让集成测试直接连接真实的 PostgreSQL、MySQL、Redis 或 Kafka 实例，测试前创建，测试后自动清理。该库在 Java 和 Spring 项目中尤为流行。

Testcontainers 需要 Docker 守护进程，因此其配置与上文 Docker-in-Docker 完全一致，无需额外变量：

test:
  stage: test
  # 这里使用测试所需的镜像（如 JDK），不一定要用 docker 镜像：
  image: gradle:jdk21
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  script:
    - gradle test

Testcontainers 通过读取 DOCKER_HOST 找到守护进程，并复用 docker 主机名访问其启动容器所暴露的端口。两者都能独立工作，因为 docker 别名会在作业网络中自动解析。

在 Testcontainers 作业中请保留 DOCKER_HOST。如果没有该变量，Testcontainers 会回退到 runner 挂载的 Docker socket，然后尝试通过主机 IP 访问测试容器，但作业无法连接到该地址。常见症状包括 Ryuk 辅助容器报错 Wait strategy failed. Container is removed 或 Timed out waiting for log output matching '.*Started.*'。

推送到 GitLab 容器镜像仓库

GitLab 提供了预定义变量（CI_REGISTRY、CI_REGISTRY_USER、CI_REGISTRY_PASSWORD、CI_REGISTRY_IMAGE），您的流水线可利用这些变量安全地认证并推送镜像到项目的容器仓库，无需额外配置密钥。

以下是一个构建并推送镜像的作业示例：

build-and-push:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
    # 如果当前分支为默认分支，也可以打标签并推送 "latest"：
    - |
      if [ "$CI_COMMIT_BRANCH" = "$CI_DEFAULT_BRANCH" ]; then
        docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" "$CI_REGISTRY_IMAGE:latest"
        docker push "$CI_REGISTRY_IMAGE:latest"
      fi

如需推送到其他镜像仓库（如 Docker Hub 或私有仓库），可将凭据存储为 CI/CD 变量，并通过 docker login 以同样方式使用。

加速重复构建

您的 runner 磁盘在流水线之间会持续保留，因此可以复用镜像层作为构建缓存，从而大幅提升重复构建速度。以下为示例配置：

build-cached:
  stage: build
  image: docker:29
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
  script:
    # 拉取最新镜像以初始化缓存（如存在）：
    - docker pull "$CI_REGISTRY_IMAGE:latest" || true
    - docker build --cache-from "$CI_REGISTRY_IMAGE:latest" -t "$CI_REGISTRY_IMAGE:latest" .
    - docker push "$CI_REGISTRY_IMAGE:latest"

这种方式可以充分利用 Docker 镜像层缓存，仅重建新增或变更的层。

并行运行作业

您的套餐决定了可并发运行的作业数量。同一阶段的作业会同时启动，最多达到您的并发上限。这样多个独立作业可以并行执行，只需等待最慢的作业完成，而无需依次等待。

示例：

stages:
  - test

unit:
  stage: test
  image: node:22
  script: npm run test:unit

integration:
  stage: test
  image: node:22
  script: npm run test:integration

e2e:
  stage: test
  image: node:22
  script: npm run test:e2e

如果您的并发设置为 1 或更高，unit、integration 和 e2e 作业将会同时运行。

如需了解更多关于在 GitLab CI/CD 流水线中构建 Docker 镜像的信息，请参考官方 GitLab Docker 构建文档。