使用 1Panel 部署 GitLab Runner 完整指南

前言

本文记录了如何在独立服务器上使用 1Panel 面板部署 GitLab Runner,并将其注册到现有的 GitLab 实例。适用于需要在多台服务器上分布式部署 CI/CD Runner 的场景。

环境说明

GitLab 服务器

  • 服务器 IP:18.93.12.26
  • GitLab 版本:GitLab CE 18.6.1
  • 安装方式:通过 1Panel 应用商店安装
  • HTTP 端口:80
  • SSH 端口:2222(因 22 端口被占用)

GitLab Runner 服务器

  • 服务器 IP:19.76.9.9
  • 安装方式:Docker 容器(通过 1Panel 编排)
  • Runner 版本:gitlab/gitlab-runner:latest (18.6.3)
  • 执行器类型:Docker

一、GitLab 容器配置(参考)

在 1Panel 应用商店安装 GitLab 后,容器配置如下:

基本配置

  • 容器名称:gitlab
  • 镜像:gitlab/gitlab-ce:18.6.1-ce.0

端口映射

服务器端口 容器端口 协议 说明
2222 22 TCP SSH(Git 操作)
80 80 TCP HTTP(Web界面和API)

挂载目录

宿主机目录 容器目录 权限
/opt/1panel/apps/gitlab/gitlab/data/config /etc/gitlab 读写
/opt/1panel/apps/gitlab/gitlab/data/logs /var/log/gitlab 读写
/opt/1panel/apps/gitlab/gitlab/data/data /var/opt/gitlab 读写

Docker Compose 配置

networks:
  1panel-network:
    external: true

services:
  gitlab:
    cap_add:
      - NET_ADMIN
    container_name: ${CONTAINER_NAME}
    deploy:
      resources:
        limits:
          cpus: ${CPUS}
          memory: ${MEMORY_LIMIT}
    environment:
      TZ: ${TIME_ZONE}
    image: gitlab/gitlab-ce:18.6.1-ce.0
    labels:
      createdBy: Apps
    networks:
      - 1panel-network
    ports:
      - ${HOST_IP}:${PANEL_APP_PORT_HTTP}:80
      - ${HOST_IP}:${PANEL_APP_PORT_SSH}:22
    restart: always
    shm_size: ${SHM_SIZE}
    volumes:
      - ./data/config:/etc/gitlab
      - ./data/logs:/var/log/gitlab
      - ./data/data:/var/opt/gitlab

二、准备 GitLab Runner 环境

2.1 拉取 GitLab Runner 镜像

在 111.228.22.30 服务器的 1Panel 面板中:

  1. 进入 容器镜像 页签
  2. 点击 拉取镜像
  3. 输入镜像名称:gitlab/gitlab-runner:latest
  4. 点击确认,等待拉取完成
    拉取 GitLab Runner
    查看 GitLab Runner 镜像拉取日志
    拉取成功后,镜像列表中会显示:
  • 镜像:gitlab/gitlab-runner
  • 标签:latest
  • 镜像ID:dab8fe7a2c93(参考)
    查看 GitLab Runner 镜像拉取日志

2.2 创建 GitLab Runner 编排

在 1Panel 的 编排 页面,创建新的编排配置:

  1. 点击 创建编排
  2. 填写编排名称:gitlab-runner
  3. 使用以下配置:
version: '3'
services:
  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    restart: always
    volumes:
      - /opt/1panel/apps/gitlab-runner/config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - 1panel-network

networks:
  1panel-network:
    external: true
  1. 点击 保存并启动
    创建 GitLab Runner 编排
    GitLab Runner 启动成功

配置说明

挂载卷解释

  • /opt/1panel/apps/gitlab-runner/config:/etc/gitlab-runner

    • 持久化 Runner 配置文件
    • 避免容器重启后配置丢失
  • /var/run/docker.sock:/var/run/docker.sock

    • 允许 Runner 容器操作宿主机 Docker
    • CI/CD 任务会在新的 Docker 容器中执行

网络配置

  • 使用 1panel-network 外部网络
  • 确保与其他 1Panel 应用在同一网络中(如有需要)

2.3 初始状态验证

启动后查看容器日志,会看到类似以下错误(这是正常的):

Runtime platform                                    arch=amd64 os=linux pid=7 revision=dbac4904 version=18.6.3
Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0 max_builds=0
Running in system-mode.
ERROR: Failed to load config stat /etc/gitlab-runner/config.toml: no such file or directory

这是预期的行为,因为配置文件需要在注册 Runner 后才会生成。

三、GitLab Runner 注册(关键步骤)

3.1 理解 GitLab 注册令牌的变化

⚠️ 重要提示:从 GitLab 15.6 开始,传统的注册令牌(Registration Token)已被弃用,改为使用身份验证令牌(Authentication Token)。

新旧方式对比

方式 令牌类型 配置位置 命令参数
旧方式 Registration Token 命令行指定 --registration-token + --tag-list
新方式 Authentication Token (glrt-) GitLab UI 预配置 --token(仅基本配置)

新方式的优势

  • 更安全的令牌管理
  • 集中化配置管理
  • 令牌可以在 UI 中撤销
  • 支持细粒度权限控制

3.2 在 GitLab UI 中创建 Runner

步骤 1:进入 Runner 管理页面

访问 GitLab:http://18.93.12.26

根据需要选择 Runner 级别:

方式 A:实例级别 Runner(推荐,需要管理员权限)

  1. 登录后点击左上角菜单
  2. 选择 管理员(Admin Area)
  3. 左侧菜单:CI/CDRunners
  4. 点击右上角 新建实例 Runner(New instance runner)

方式 B:群组级别 Runner

  1. 进入目标群组
  2. 设置(Settings)→ CI/CD
  3. 展开 Runners 部分
  4. 点击 新建群组 Runner(New group runner)

方式 C:项目级别 Runner

  1. 进入目标项目
  2. 设置(Settings)→ CI/CD
  3. 展开 Runners 部分
  4. 点击 新建项目 Runner(New project runner)

步骤 2:配置 Runner 信息

在创建页面填写以下信息:

配置项 说明 示例值
标签(Tags) CI/CD 任务通过标签匹配 Runner docker, linux, deploy, test
描述(Description) Runner 的说明信息 runner-111.228.22.30
运行未标记的作业 是否运行没有标签的任务 根据需求勾选
保护(Protected) 只在受保护分支运行 根据需求勾选

填写完成后点击 创建 Runner(Create runner)。

步骤 3:获取身份验证令牌

创建成功后,页面会显示注册指引:

步骤 1: 在要使用 Runner 的系统上安装 GitLab Runner

步骤 2: 注册 Runner

gitlab-runner register
  --url http://18.93.12.26
  --token glrt-xxxxxxxxxxxxxxxxxxxx

重要

  • 复制 --token 后面的值(以 glrt- 开头)
  • 这个令牌只会显示一次,请妥善保存
  • 示例令牌:glrt-Nft3wE_AsFZftnGaMVw-ZG86MQp0OjEKdToxCw.01.120pf0jly

3.3 在 Runner 容器中执行注册

步骤 1:进入容器终端

在 19.76.9.9 服务器的 1Panel 面板中:

  1. 进入 容器 页面
  2. 找到 gitlab-runner 容器
  3. 点击右侧的 终端 图标
  4. 进入容器 Shell

步骤 2:执行注册命令

⚠️ 注意:使用新的身份验证令牌时,很多参数(如 --tag-list)不能在命令中指定,因为这些已经在 GitLab UI 中配置好了。

正确的注册命令

gitlab-runner register --non-interactive --url "http://18.93.12.26" --token "glrt-Nft3wE_AsFZftnGaMVw-ZG86MQp0OjEKdToxCw.01.120pf0jly" --executor "docker" --docker-image "alpine:latest" --description "runner-19.76.9.9" --docker-privileged=false --docker-volumes "/var/run/docker.sock:/var/run/docker.sock"

参数说明

参数 说明
--non-interactive 非交互式注册 无需手动输入
--url GitLab 实例地址 http://18.93.12.26
--token 身份验证令牌 从 UI 复制的 glrt- 令牌
--executor 执行器类型 docker
--docker-image 默认 Docker 镜像 alpine:latest
--description Runner 描述 runner-19.76.9.9
--docker-privileged 是否启用特权模式 false(更安全)
--docker-volumes 挂载的卷 Docker socket

步骤 3:验证注册结果

成功的输出示例

Runtime platform                                    arch=amd64 os=linux pid=68 revision=dbac4904 version=18.6.3
Running in system-mode.

Verifying runner... is valid                        correlation_id=01KBPVSN9AP8SVEKMC7Y4PCMAQ runner=Nft3wE_As
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"

关键信息:

  • Verifying runner... is valid - Runner 验证通过
  • Runner registered successfully - 注册成功
  • ✅ 配置已保存到 /etc/gitlab-runner/config.toml

四、验证和测试

4.1 在 Runner 容器中验证

在容器终端执行以下命令:

查看已注册的 Runner

gitlab-runner list

输出示例:

Listing configured runners          ConfigFile=/etc/gitlab-runner/config.toml
runner-111.228.22.30               Executor=docker Token=glrt-Nft*** URL=http://18.93.12.26

验证 Runner 状态

gitlab-runner verify

输出示例:

Verifying runner... is alive                        runner=glrt-Nft***

查看配置文件

cat /etc/gitlab-runner/config.toml

配置文件示例:

concurrent = 1
check_interval = 0
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "runner-19.76.9.9"
  url = "http://18.93.12.26"
  id = 1
  token = "glrt-xxxxx"
  token_obtained_at = 2025-12-05T08:33:48Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
    shm_size = 0
    network_mtu = 0

4.2 在 GitLab UI 中确认

  1. 返回 GitLab:http://18.93.12.26
  2. 进入 管理中心CI/CDRunners
  3. 找到刚创建的 Runner
  4. 确认状态:
    • ✅ 状态指示灯为绿色
    • ✅ 最后联系时间显示为"刚刚"或几秒前
    • ✅ 显示 Runner 描述:runner-19.76.9.9

4.3 检查容器日志

在 1Panel 的容器页面,查看 gitlab-runner 的日志:

之前的错误应该消失,取而代之的是正常运行日志:

Configuration loaded                                builds=0 max_builds=1
Checking for jobs...                               

4.4 创建测试 Pipeline

步骤 1:创建测试项目

在 GitLab 中创建一个新项目或使用现有项目。

步骤 2:添加 CI 配置文件

在项目根目录创建 .gitlab-ci.yml 文件:

# 测试 GitLab Runner 的简单 Pipeline

stages:
  - test

test-runner-connection:
  stage: test
  tags:
    - docker  # 使用您在 UI 中配置的标签
  script:
    - echo "=============================="
    - echo "测试 GitLab Runner"
    - echo "=============================="
    - echo "Runner 主机: $(hostname)"
    - echo "当前时间: $(date)"
    - echo "工作目录: $(pwd)"
    - echo "用户: $(whoami)"
    - echo ""
    - echo "文件列表:"
    - ls -la
    - echo ""
    - echo "系统信息:"
    - cat /etc/os-release
    - echo ""
    - echo "Docker 版本:"
    - docker --version
    - echo ""
    - echo "=============================="
    - echo "Runner 测试成功!"
    - echo "=============================="

test-docker-commands:
  stage: test
  tags:
    - docker
  script:
    - echo "测试 Docker 命令执行"
    - docker ps
    - docker images
    - echo "Docker 命令执行成功!"

步骤 3:运行 Pipeline

  1. 提交并推送 .gitlab-ci.yml 文件
  2. 访问项目的 CI/CDPipelines 页面
  3. 观察 Pipeline 的执行情况

成功的标志

  • Pipeline 状态为 passed(绿色勾)
  • 任务日志中能看到测试输出
  • Runner 标签显示为 docker

五、常见问题和解决方案

5.1 注册时报错:--tag-list: not found

问题原因

  • 多行命令粘贴时换行符处理有问题
  • Shell 将命令拆分成了多行

解决方案
使用单行命令,将所有参数放在一行中执行。

5.2 注册时报错:configuration is reserved

完整错误信息

FATAL: Runner configuration other than name and executor configuration is reserved 
(specifically --locked, --access-level, --run-untagged, --maximum-timeout, --paused, 
--tag-list, and --maintenance-note) and cannot be specified when registering with a 
runner authentication token.

问题原因
使用新的身份验证令牌(glrt- 开头)时,以下参数不能在注册命令中指定:

  • --tag-list
  • --locked
  • --access-level
  • --run-untagged
  • --maximum-timeout
  • --paused
  • --maintenance-note

这些配置应该在 GitLab UI 创建 Runner 时指定。

解决方案
移除上述参数,只保留基本配置参数。

5.3 SSH 端口非标准(2222)的影响

问题说明
GitLab 的 SSH 端口映射为 2222 而不是标准的 22 端口。

影响范围

  • ✅ Runner 注册:不受影响(使用 HTTP API,走 80 端口)
  • ✅ HTTP(S) 方式克隆:不受影响(默认方式)
  • ⚠️ SSH 方式克隆:可能受影响(需要额外配置)

解决方案

如果 CI/CD 任务需要使用 SSH 克隆代码,需要配置 GitLab 的 SSH 端口:

  1. 编辑 GitLab 配置文件(在 18.93.12.26 服务器):
/opt/1panel/apps/gitlab/gitlab/data/config/gitlab.rb
  1. 添加或修改:
gitlab_rails['gitlab_shell_ssh_port'] = 2222
  1. 重新配置 GitLab:
# 在 GitLab 容器中执行
gitlab-ctl reconfigure
  1. 或者,在 Runner 机器上配置 SSH:
mkdir -p ~/.ssh
cat >> ~/.ssh/config << EOF
Host 18.93.12.26
    Port 2222
EOF

推荐做法
使用 HTTP(S) 方式克隆(GitLab Runner 默认行为),无需额外配置。

5.4 Runner 显示离线

可能原因

  1. 网络连接问题
  2. GitLab URL 配置错误
  3. Runner 服务未启动
  4. 防火墙阻止连接

排查步骤

# 1. 测试网络连通性
curl http://18.93.12.26

# 2. 在 Runner 容器中验证配置
gitlab-runner verify

# 3. 查看 Runner 日志
docker logs gitlab-runner

# 4. 重启 Runner
docker restart gitlab-runner

5.5 CI 任务中 Docker 命令失败

错误示例

Cannot connect to the Docker daemon at unix:///var/run/docker.sock

问题原因
Docker socket 未正确挂载或权限不足。

解决方案

  1. 确认编排配置中包含 Docker socket 挂载:
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  1. 确认注册命令中包含 Docker volumes:
--docker-volumes "/var/run/docker.sock:/var/run/docker.sock"
  1. 如果仍有问题,尝试启用特权模式(不推荐,但可以解决权限问题):
--docker-privileged=true

5.6 Pipeline 一直处于 pending 状态

可能原因

  1. 没有可用的 Runner
  2. 任务标签与 Runner 标签不匹配
  3. Runner 被暂停

解决方案

  1. 检查任务标签和 Runner 标签是否匹配
  2. 在 GitLab UI 中确认 Runner 状态为在线
  3. 检查 Runner 是否勾选了"运行未标记的作业"
  4. 查看 Runner 日志是否有错误信息

六、配置优化建议

6.1 Runner 并发设置

编辑配置文件 /etc/gitlab-runner/config.toml(在宿主机路径:/opt/1panel/apps/gitlab-runner/config/config.toml):

concurrent = 4  # 同时运行的最大任务数
check_interval = 3  # 检查新任务的间隔(秒)

修改后重启容器:

docker restart gitlab-runner

6.2 Docker 镜像缓存

config.toml 中配置镜像缓存:

[[runners]]
  # ... 其他配置
  [runners.docker]
    # ... 其他配置
    pull_policy = "if-not-present"  # 如果本地存在则不拉取

6.3 资源限制

限制 Runner 容器资源使用,修改编排配置:

services:
  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    restart: always
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G
    volumes:
      - /opt/1panel/apps/gitlab-runner/config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - 1panel-network

6.4 日志管理

配置日志轮转,避免日志文件过大:

在编排配置中添加:

services:
  gitlab-runner:
    # ... 其他配置
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

6.5 使用私有 Docker 仓库

如果需要使用私有镜像仓库:

[[runners]]
  [runners.docker]
    # ... 其他配置
    pull_policy = "if-not-present"
    allowed_images = ["docker.io/*", "your-registry.com/*"]
    [runners.docker.services_pull_policy]
      policy = "if-not-present"

然后在 GitLab 项目中配置 Docker 认证信息(Settings → CI/CD → Variables)。

七、安全加固

7.1 限制 Runner 访问范围

在 GitLab UI 中:

  1. 进入 Runner 详情页
  2. 勾选 锁定到当前项目
  3. 勾选 保护(仅在受保护分支运行)

7.2 禁用特权模式

除非必要,否则不要启用 --docker-privileged

--docker-privileged=false

7.3 限制 Docker 镜像

config.toml 中限制可使用的镜像:

[[runners]]
  [runners.docker]
    allowed_images = ["alpine:*", "node:*", "python:*"]
    allowed_services = ["docker:*-dind"]

7.4 配置 HTTPS

对于生产环境,强烈建议为 GitLab 配置 HTTPS:

  1. 获取 SSL 证书(Let's Encrypt 或购买)
  2. 修改 GitLab 配置使用 HTTPS
  3. 更新 Runner 注册 URL 为 HTTPS

7.5 定期更新

定期更新 GitLab 和 GitLab Runner 版本:

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

# 重新创建容器
docker-compose down
docker-compose up -d

八、监控和维护

8.1 查看 Runner 状态

在 1Panel 中

  • 容器页面 → gitlab-runner → 查看状态和资源使用

在 GitLab UI 中

  • Admin Area → Runners → 查看在线状态和任务历史

命令行

# 查看 Runner 状态
docker ps | grep gitlab-runner

# 查看资源使用
docker stats gitlab-runner

# 查看日志
docker logs -f gitlab-runner

8.2 定期检查

建议定期检查以下内容:

  1. Runner 在线状态(每天)
  2. 磁盘空间(每周)
    df -h
    du -sh /opt/1panel/apps/gitlab-runner/
    
  3. Docker 镜像清理(每月)
    docker image prune -a
    
  4. 容器日志大小(每月)
    docker logs gitlab-runner 2>&1 | wc -l
    

8.3 备份配置

定期备份 Runner 配置:

# 备份配置文件
cp /opt/1panel/apps/gitlab-runner/config/config.toml \
   /opt/1panel/apps/gitlab-runner/config/config.toml.backup.$(date +%Y%m%d)

# 备份编排文件
cp /path/to/docker-compose.yml \
   /path/to/docker-compose.yml.backup.$(date +%Y%m%d)

8.4 故障恢复

如果 Runner 出现问题:

# 重启容器
docker restart gitlab-runner

# 如果重启无效,重新注册
docker exec -it gitlab-runner gitlab-runner unregister --all-runners
# 然后重新执行注册命令

# 完全重建
docker-compose down
docker-compose up -d

九、高级配置示例

9.1 多 Runner 配置

如果需要在同一服务器上运行多个 Runner:

version: '3'
services:
  gitlab-runner-1:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner-1
    restart: always
    volumes:
      - /opt/1panel/apps/gitlab-runner-1/config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - 1panel-network

  gitlab-runner-2:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner-2
    restart: always
    volumes:
      - /opt/1panel/apps/gitlab-runner-2/config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - 1panel-network

networks:
  1panel-network:
    external: true

9.2 使用 Docker-in-Docker (DinD)

如果需要在 CI 中构建 Docker 镜像:

.gitlab-ci.yml:

build-docker:
  image: docker:latest
  services:
    - docker:dind
  tags:
    - docker
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - docker build -t myimage:latest .
    - docker push myimage:latest

Runner 配置config.toml):

[[runners]]
  [runners.docker]
    privileged = true
    volumes = ["/certs/client", "/cache"]

9.3 使用 Kubernetes 执行器

如果有 Kubernetes 集群,可以使用 Kubernetes 执行器:

gitlab-runner register \
  --non-interactive \
  --url "http://18.93.12.26" \
  --token "glrt-xxx" \
  --executor "kubernetes" \
  --kubernetes-host "https://k8s-api-server:6443" \
  --kubernetes-namespace "gitlab-runner"

十、总结

关键要点

  1. GitLab Runner 版本兼容性

    • 确保 Runner 版本与 GitLab 版本兼容
    • 推荐使用与 GitLab 相同或更新的版本
  2. 新的注册方式

    • GitLab 15.6+ 使用身份验证令牌(glrt-
    • 配置在 UI 中管理,更安全
    • 注册命令更简洁
  3. Docker 执行器

    • 最常用的执行器类型
    • 隔离性好,环境一致
    • 需要挂载 Docker socket
  4. 网络配置

    • Runner 只需要访问 GitLab 的 HTTP/HTTPS 端口
    • SSH 端口主要用于代码克隆(可选)
  5. 安全考虑

    • 避免使用特权模式
    • 限制 Runner 访问范围
    • 定期更新和维护

完整配置清单

GitLab 服务器:18.93.12.26

  • GitLab CE 18.6.1
  • HTTP: 80, SSH: 2222
  • 使用 1Panel 应用商店安装

GitLab Runner 服务器:19.76.9.9

  • Runner 版本 18.6.3
  • 执行器:Docker
  • 容器管理:1Panel 编排

网络配置

  • HTTP 通信(80 端口)
  • Docker 网络:1panel-network

存储配置

  • 配置持久化:/opt/1panel/apps/gitlab-runner/config
  • Docker socket 挂载

下一步建议

  1. 配置更多 Runner

    • 根据负载增加 Runner 数量
    • 不同 Runner 使用不同标签
  2. 优化 CI/CD Pipeline

    • 使用缓存加速构建
    • 合理划分 stages
    • 使用 artifacts 传递文件
  3. 监控和告警

    • 配置 Prometheus 监控
    • 设置 Runner 离线告警
    • 监控资源使用情况
  4. 安全加固

    • 启用 HTTPS
    • 配置 Runner 访问控制
    • 定期审计 CI/CD 配置

参考资料


本文更新时间:2025年12月5日
适用版本:GitLab CE 18.6.1, GitLab Runner 18.6.3, 1Panel v2.0.14

作者备注:本文所有步骤均在实际环境中测试通过,如有问题欢迎交流讨论。

posted @ 2025-12-08 14:37  omniloom  阅读(158)  评论(0)    收藏  举报