GitLab Runner: 构建 Docker 镜像

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

👋 欢迎来到 Stackhero 文档！

Stackhero 提供简单易用的 GitLab Runner cloud 解决方案，让您高效、无忧地运行 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 构建文档。