如何使用本地 Python 镜像作为 GitLab Runner 的构建环境

 在 CI/CD 流程中，为了加快构建速度、保证环境一致性并减少外部依赖，我们可以使用预先拉取好的本地 Python 3.11 Docker 镜像（在线下载很困难）。本文将详细介绍如何通过 docker-compose 部署 GitLab Runner，并配置使用本地 Python 3.11 镜像，包括注册时配置与注册后修改配置的两种方式。

前提条件

1. 宿主机安装 Docker
   请确保宿主机已安装 Docker，并能正常使用。

2. 本地存在 Python 3.11 镜像
   在宿主机上拉取 Python 3.11 镜像(可以梯子)，避免每次构建时在线下载。执行以下命令：

   docker pull python:3.11

3. 已注册 GitLab Runner
   GitLab Runner 可以通过 docker-compose 部署，并挂载宿主机的 Docker Socket 与配置目录。

1. 使用 docker-compose 部署 GitLab Runner

创建或修改 docker-compose 配置文件，例如 docker-compose.yml，内容如下(版本根据自己gitlab而定)：

gitlab-runner:
  image: gitlab/gitlab-runner:alpine3.18-v17.9.1
  container_name: gitlab-runner
  restart: always
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - /home/gitlab-runner/config:/etc/gitlab-runner

说明：

• Docker Socket 挂载：允许 Runner 调用宿主机 Docker 引擎，从而启动和管理构建所需的容器。
• 配置目录挂载：将 /etc/gitlab-runner 挂载到宿主机上，这样 Runner 的配置文件（config.toml）可以持久化，方便后续修改。

2. 确保宿主机已有 Python 3.11 镜像

使用如下命令在宿主机上拉取 Python 3.11 镜像（如果还未拉取）：

docker pull python:3.11

这样，在运行 CI 作业时，GitLab Runner 会直接使用本地缓存的 Python 3.11 镜像，无需在线下载，提升构建效率。

3. 修改 GitLab Runner 的 config.toml 配置

在 GitLab Runner 的配置文件中（通常位于挂载目录 /home/gitlab-runner/config/config.toml），我们需要设置 Runner 使用 Docker executor，并指定使用本地的 Python 3.11 镜像。这里有两种方式：

3.1 注册时直接配置 Docker executor

在注册 GitLab Runner 时，可以通过命令行参数直接指定 Docker executor 及所需的镜像（选择了shell也没问题，3.2可以改）。例如：

gitlab-runner register \
  --non-interactive \
  --url "http://192.168.31.63:8081/" \
  --registration-token "YOUR_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image "python:3.11" \
  --description "python" \
  --tag-list "python" \
  --run-untagged="true" \
  --locked="false"

这样，在注册过程中会自动生成 Docker executor 的配置，并将 python:3.11 镜像作为默认执行环境。

3.2 注册后修改配置文件

如果你已经注册了 Runner，但未在注册时配置 Docker executor，也可以直接修改配置文件。编辑 config.toml 文件，找到对应的 Runner 配置块，并修改为如下内容：

[[runners]]
  name = "python"
  url = "http://192.168.31.63:8081/"
  id = 6
  token = "tYPsoczmdeyt-zCvVp1x"
  token_obtained_at = 2025-03-14T05:18:43Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"  # 使用 Docker executor
  [runners.docker]
    image = "python:3.11"  # 指定使用本地 Python 3.11 镜像
    privileged = false

注意事项：

• 配置文件持久化：由于通过 docker-compose 挂载了配置目录，修改后的配置文件会被持久保存，并在 Runner 重启后生效。
• 镜像版本一致性：确保 image 字段中指定的版本（例如 python:3.11）在宿主机上已拉取，避免首次构建时仍需下载。
• 权限设置：通常情况下 privileged 保持为 false 即可，除非构建任务需要更高的权限。

4. 在 .gitlab-ci.yml 中指定 Python 3.11 镜像

在项目根目录下创建或修改 .gitlab-ci.yml 文件，指定全局镜像为 python:3.11，示例如下：

image: python:3.11

stages:
  - build
  - test

build_job:
  stage: build
  script:
    - python --version
    - pip install -r requirements.txt
    - python setup.py build

test_job:
  stage: test
  script:
    - python -m unittest discover

这样，所有作业都会默认在 Python 3.11 环境中运行，并使用已在宿主机中缓存的镜像，无需在线下载。

gitlab-runner 运行日志

Running with gitlab-runner 17.9.1 (bbf75488)

on python tYPsoczm, system ID: r_eTuqmAjrLAza

Preparing the "docker" executor00:06

Using Docker executor with image python:3.11 ...

Pulling docker image python:3.11 ...

Using docker image sha256:78553a4d82cb4da60dd65fbade310bee7c4c86e7575e4bbbb208b2ea089402ad for python:3.11 with digest python@sha256:68a8863d0625f42d47e0684f33ca02f19d6094ef859a8af237aaf645195ed477 ...

宿主机使用命令查看哈希值一致 for python:3.11 with digest xxxx，如果 匹配，则 Runner 正在使用本地镜像

docker inspect --format '{{index .RepoDigests 0}}' python:3.11

python@sha256:68a8863d0625f42d47e0684f33ca02f19d6094ef859a8af237aaf645195ed477

总结

通过以上配置，你可以实现以下目标：

• 使用本地镜像加速构建：预先在宿主机拉取 Python 3.11 镜像，CI 作业启动时直接使用，无需重复在线下载。
• 环境隔离：利用 Docker executor 确保每个作业在独立的容器中运行，容器与宿主机环境完全隔离，数据不共享，确保构建过程的干净和安全。
• 灵活配置：无论是在 Runner 注册时直接配置 Docker executor，还是注册后修改 config.toml 文件，都能方便地调整构建环境。

通过这些步骤，你的 GitLab Runner 将稳定高效地使用本地 Python 3.11 镜像作为构建环境，保证 CI/CD 流程顺利进行。如果需要更换或升级镜像，只需在宿主机上更新镜像并相应调整配置即可，整个过程简单而灵活。

---