Gitlab Runner 配置实践

在极狐 GitLab（或 GitLab）上跑 CI 任务时，可以用官方提供的 Runner，也可以在自己的服务器（这里是阿里云的 ECS） 上装自定义Runner，把任务放到自己机器上执行。

概念理解

GitLab CI Runner ：用来执行 CI/CD 流水线里定义的 job 的程序。流水线触发后，由 Runner 拉取代码、按 .gitlab-ci.yml 里的步骤在指定环境里执行（如 build、test、deploy），可以理解成运行在服务器上的任务执行器。

Runner 与标签（tags） ：一个 GitLab 项目/实例下可以有多个 Runner。在 CI 里通过 tags 指定用哪类 Runner 跑某个 job；只有「带对应 tag」的 Runner 会接这个 job。例如给自建 Runner 打上 node、docker，在 job 里写 tags: [node] 就会用这台自建 Runner 跑。

Docker in Docker（DinD）：在Docker容器内部运行Docker守护进程的方式，允许在单个容器中运行多个Docker服务，比如容器里运行在 CI job 里再跑 Docker（例如构建镜像）时，会用到 DinD 服务。

配置步骤

1. 安装启动 gitlab-runner

可用 uname -a 确认系统架构，使用不同的安装方法，在创建 runner 的时候可以找到具体配置方法，这里是以 CentOS7 为例：

# 下载极狐 GitLab 提供的 Runner 二进制（amd64）
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.gitlab.cn/latest/binaries/gitlab-runner-linux-amd64

# 赋予可执行权限
sudo chmod +x /usr/local/bin/gitlab-runner

# 创建专用系统用户
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

# 以 gitlab-runner 用户安装并启动服务
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

2. 创建自定义 Runner

在项目或群组/实例的 CI/CD → Runners 里新增 Runner，设置名称和要绑定的 tags （如 node、docker）

创建完成后页面上会给出 registration token ，后面 gitlab-runner register 会使用上。

自建 Runner 这里的标签（tag）按需填写，CI job 中只有配置符合的 tags 标签时才会使用对应的 Runner，后续也可以编辑。

3. 注册 Runner

在已安装 gitlab-runner 的 服务器上执行注册，按提示填写 runner 名称、url、选择执行器等。

# 交互式注册（将 <runner-token> 换成上一步拿到的 token）
gitlab-runner register \
  --url https://jihulab.com \
  --token <runner-token>

# 按提示：输入 Runner 描述名、选择 executor（如 docker）、默认镜像等
# 执行器类型可查：https://docs.gitlab.cn/docs/runner/executors/#compatibility-chart

# 注册完成后，可前台跑一次，确认能拉取到作业（调试用）
gitlab-runner run

4.确认 Runner 状态

在 CI/CD → Runners 里看该 Runner 是否显示为绿色在线。绿色表示已连上并可接收 job。

5. 使用 Runner

在 .gitlab-ci.yml 里给 job 加上 tags，即可让该 job 只由带对应 tag 的自建 Runner 执行。

build-job:
  stage: build
  tags:
    - node   # 与自建 Runner 上配置的标签一致

问题踩坑

gitlab-runner 用户不在 Docker 组

按官方文档只做默认安装时，gitlab-runner 用户通常不在 docker 组里，用 Docker 执行器或在 job 里执行 docker 命令会权限不足。需要把该用户加入 docker 组并重新登录会话后重启服务。

# 将 gitlab-runner 加入 docker 组
sudo usermod -aG docker gitlab-runner

# 停止 Runner，以便后续用新组权限启动
sudo gitlab-runner stop

# 退出当前 SSH 会话再重连，或执行下面命令使组生效后再启动
exec su - $USER

# 重新启动 Runner
sudo gitlab-runner start

Docker 执行器 + DinD 的 TLS 端口不一致

使用 Docker 执行器且在 job 里需要构建镜像（会用到 DinD）时，阿里云等环境里 Docker 的 DinD 可能只监听 2376（TLS） ，而 GitLab CI 配置时默认连 2375（非 TLS），会导致 job 里连不上 DinD 服务。解决办法是在 Runner 配置里关闭 TLS 校验并清空 TLS 证书目录环境变量，并视情况加长等待时间。

编辑 /etc/gitlab-runner/config.toml，在对应 [[runners]] 下增加或修改如下（name、url、id、token 等按实际填写）：

[[runners]]
  name = "node_runner"
  url = "https://jihulab.com"
  id = 42515
  token = "xxxx"
  token_obtained_at = 2026-02-15T12:08:08Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  # 关闭 DinD 的 TLS，避免只开 2376 时连不上
  environment = ["DOCKER_TLS_CERTDIR="]
  [runners.cache]
    MaxUploadedArchiveSize = 0
  [runners.cache.s3]
  [runners.cache.gcs]
  [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "node:22"
    # DinD 场景下通常需要开启，非必要勿开，会有权限安全问题
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    # 网络或 DinD 启动慢时可适当加大
    wait_timeout = 60
    disable_cache = false

修改后执行 sudo gitlab-runner restart 使配置生效。

参考内容

• 极狐 GitLab Runner 文档
• Runner 执行器对比