GitLab教程(7): GitLab Runner安装与配置

GitLab 2 小时前 0 0

GitLab Runner是执行CI/CD作业的代理程序。本文将详细介绍Runner的安装、注册和配置方法。

什么是GitLab Runner

# Runner类型

1. Shared Runner (共享Runner)
   - 所有项目都可使用
   - 由GitLab管理员配置
   - gitlab.com提供免费共享Runner

2. Group Runner (组Runner)
   - 特定组内的项目可用
   - 组管理员配置

3. Project Runner (项目Runner)
   - 仅特定项目可用
   - 项目维护者配置

# Runner执行器 (Executor)
- shell: 直接在Runner所在机器执行
- docker: 在Docker容器中执行
- docker+machine: 自动扩缩容的Docker
- kubernetes: 在K8s集群中执行
- virtualbox: 在虚拟机中执行
- ssh: 通过SSH在远程机器执行

安装Runner

Linux安装

# Ubuntu/Debian
# 添加仓库
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# 安装
sudo apt-get install gitlab-runner

# CentOS/RHEL
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
sudo yum install gitlab-runner

# 验证安装
gitlab-runner --version

# 输出
Version:      16.8.0
Git revision: c72a09ce
Git branch:   16-8-stable
GO version:   go1.21.5
Built:        2024-01-18T20:45:24+0000
OS/Arch:      linux/amd64

Docker安装

# 拉取镜像
docker pull gitlab/gitlab-runner:latest

# 运行Runner容器
docker run -d \
  --name gitlab-runner \
  --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

# 验证
docker exec -it gitlab-runner gitlab-runner --version

Docker Compose安装

# docker-compose.yml
version: '3.8'

services:
  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    restart: always
    volumes:
      - ./config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock

# 启动
docker-compose up -d

注册Runner

获取注册Token

# 项目Runner Token
# Project > Settings > CI/CD > Runners > Expand
# 复制注册Token: glrt-xxxxxxxxxxxxxxxxxxxx

# 组Runner Token
# Group > Settings > CI/CD > Runners

# 共享Runner Token (管理员)
# Admin Area > CI/CD > Runners

交互式注册

# 使用新版Token注册
sudo gitlab-runner register

# 交互过程
Runtime platform                                    arch=amd64 os=linux pid=12345
Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com/

Enter the registration token:
glrt-xxxxxxxxxxxxxxxxxxxx

Enter a description for the runner:
[hostname]: my-docker-runner

Enter tags for the runner (comma-separated):
docker,linux,build

Enter optional maintenance note for the runner:
General purpose build runner

Enter an executor: docker, shell, ssh, virtualbox, docker+machine, kubernetes:
docker

Enter the default Docker image (for example, ruby:2.7):
node:18-alpine

Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

# 启动Runner
sudo gitlab-runner start

非交互式注册

# 一行命令注册 (Docker executor)
sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --token "glrt-xxxxxxxxxxxxxxxxxxxx" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "Docker Runner" \
  --tag-list "docker,linux" \
  --run-untagged="true" \
  --locked="false"

# Shell executor
sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --token "glrt-xxxxxxxxxxxxxxxxxxxx" \
  --executor "shell" \
  --description "Shell Runner" \
  --tag-list "shell,linux"

# Docker容器中注册
docker exec -it gitlab-runner gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --token "glrt-xxxxxxxxxxxxxxxxxxxx" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "Docker Runner"

配置文件详解

# 配置文件位置: /etc/gitlab-runner/config.toml

concurrent = 4                    # 最大并发Job数
check_interval = 0                # 检查新Job的间隔
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "Docker Runner"
  url = "https://gitlab.example.com/"
  id = 12345
  token = "runner-token-here"
  token_obtained_at = 2024-01-01T00:00:00Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  
  [runners.custom_build_dir]
  
  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  
  [runners.docker]
    tls_verify = false
    image = "node:18-alpine"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]
    shm_size = 0
    network_mtu = 0
    pull_policy = ["if-not-present"]

# 添加多个Runner
[[runners]]
  name = "Shell Runner"
  url = "https://gitlab.example.com/"
  token = "another-token"
  executor = "shell"

Docker Executor配置

# 完整的Docker配置示例

[[runners]]
  name = "Docker Runner"
  url = "https://gitlab.example.com/"
  token = "token"
  executor = "docker"
  
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    
    # Docker-in-Docker (用于构建镜像)
    privileged = true
    
    # 挂载卷
    volumes = [
      "/cache",
      "/var/run/docker.sock:/var/run/docker.sock",
      "/builds:/builds"
    ]
    
    # 拉取策略
    pull_policy = ["if-not-present", "always"]
    
    # 资源限制
    memory = "2g"
    cpus = "2"
    
    # 网络
    network_mode = "bridge"
    
    # 额外hosts
    extra_hosts = ["registry.local:192.168.1.100"]
    
    # DNS
    dns = ["8.8.8.8", "8.8.4.4"]
    
    # 允许的镜像
    allowed_images = ["node:*", "python:*", "golang:*"]
    
    # 禁用缓存
    disable_cache = false
    
    # 清理策略
    helper_image = ""
    wait_for_services_timeout = 30

Runner管理命令

# 服务管理
sudo gitlab-runner status
sudo gitlab-runner start
sudo gitlab-runner stop
sudo gitlab-runner restart

# 状态输出
Runtime platform                                    arch=amd64 os=linux pid=12345
gitlab-runner: Service is running

# 列出注册的Runner
sudo gitlab-runner list

# 输出
Listing configured runners                          ConfigFile=/etc/gitlab-runner/config.toml
Docker Runner                                       Executor=docker Token=glrt-xxx URL=https://gitlab.example.com/
Shell Runner                                        Executor=shell Token=glrt-yyy URL=https://gitlab.example.com/

# 验证Runner
sudo gitlab-runner verify

# 输出
Verifying runner... is valid                        runner=xxxx
Verifying runner... is valid                        runner=yyyy

# 删除Runner
sudo gitlab-runner unregister --name "Docker Runner"
# 或
sudo gitlab-runner unregister --all-runners

# 手动运行单个Job (调试用)
sudo gitlab-runner run-single \
  --url "https://gitlab.example.com/" \
  --token "runner-token" \
  --executor "shell"

Runner标签和限制

# 使用标签指定Runner
# .gitlab-ci.yml

build-docker:
  tags:
    - docker
    - linux
  script:
    - docker build -t myapp .

build-windows:
  tags:
    - windows
    - shell
  script:
    - build.bat

build-gpu:
  tags:
    - gpu
    - cuda
  script:
    - python train.py

# Web界面配置Runner标签
# Project > Settings > CI/CD > Runners
# 点击Runner旁边的编辑图标

# 配置选项:
# - Run untagged jobs: 是否运行无标签Job
# - Lock to current projects: 锁定到当前项目
# - Maximum job timeout: 最大超时时间

缓存配置

# 本地缓存
[[runners]]
  [runners.cache]
    Type = "local"
    Path = "/cache"

# S3缓存
[[runners]]
  [runners.cache]
    Type = "s3"
    Shared = true
    [runners.cache.s3]
      ServerAddress = "s3.amazonaws.com"
      AccessKey = "your-access-key"
      SecretKey = "your-secret-key"
      BucketName = "gitlab-runner-cache"
      BucketLocation = "us-east-1"

# GCS缓存
[[runners]]
  [runners.cache]
    Type = "gcs"
    [runners.cache.gcs]
      BucketName = "gitlab-runner-cache"
      CredentialsFile = "/path/to/credentials.json"

# MinIO缓存 (自托管S3兼容)
[[runners]]
  [runners.cache]
    Type = "s3"
    [runners.cache.s3]
      ServerAddress = "minio.example.com:9000"
      AccessKey = "minio-access-key"
      SecretKey = "minio-secret-key"
      BucketName = "runner-cache"
      Insecure = true

监控Runner

# 查看Runner日志
sudo journalctl -u gitlab-runner -f

# Docker Runner日志
docker logs -f gitlab-runner

# Prometheus指标
# 配置 /etc/gitlab-runner/config.toml
listen_address = ":9252"

# 访问指标
curl http://localhost:9252/metrics

# 输出示例
# HELP gitlab_runner_jobs Number of jobs
# TYPE gitlab_runner_jobs counter
gitlab_runner_jobs{state="success"} 150
gitlab_runner_jobs{state="failed"} 10

# HELP gitlab_runner_concurrent Number of concurrent jobs
gitlab_runner_concurrent 4

# 在GitLab查看Runner状态
# Project > Settings > CI/CD > Runners
# 绿色 = 在线
# 灰色 = 离线

常见问题

# 问题1: Runner离线
# 检查服务状态
sudo gitlab-runner status
sudo systemctl status gitlab-runner

# 重启服务
sudo gitlab-runner restart

# 问题2: Docker权限问题
# 将用户添加到docker组
sudo usermod -aG docker gitlab-runner
sudo gitlab-runner restart

# 问题3: 证书问题
# 添加CA证书
sudo gitlab-runner register \
  --tls-ca-file=/path/to/ca.crt ...

# 或跳过验证 (不推荐)
[runners.docker]
  tls_verify = false

# 问题4: Job卡住
# 检查并发数
concurrent = 4  # 增加并发

# 检查Job超时
# Project > Settings > CI/CD > General pipelines > Timeout

总结

本文介绍了GitLab Runner的安装、注册和配置方法，包括不同执行器的使用场景和配置选项。正确配置Runner是保证CI/CD顺利运行的关键。

下一篇我们将学习GitLab CI/CD的高级特性。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。