使用 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 面板中:
- 进入 容器 → 镜像 页签
- 点击 拉取镜像
- 输入镜像名称:
gitlab/gitlab-runner:latest - 点击确认,等待拉取完成
![拉取 GitLab Runner]()
![查看 GitLab Runner 镜像拉取日志]()
拉取成功后,镜像列表中会显示:
- 镜像:gitlab/gitlab-runner
- 标签:latest
- 镜像ID:dab8fe7a2c93(参考)
![查看 GitLab Runner 镜像拉取日志]()
2.2 创建 GitLab Runner 编排
在 1Panel 的 编排 页面,创建新的编排配置:
- 点击 创建编排
- 填写编排名称:
gitlab-runner - 使用以下配置:
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
- 点击 保存并启动
![创建 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(推荐,需要管理员权限)
- 登录后点击左上角菜单
- 选择 管理员(Admin Area)
- 左侧菜单:CI/CD → Runners
- 点击右上角 新建实例 Runner(New instance runner)
方式 B:群组级别 Runner
- 进入目标群组
- 设置(Settings)→ CI/CD
- 展开 Runners 部分
- 点击 新建群组 Runner(New group runner)
方式 C:项目级别 Runner
- 进入目标项目
- 设置(Settings)→ CI/CD
- 展开 Runners 部分
- 点击 新建项目 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 面板中:
- 进入 容器 页面
- 找到
gitlab-runner容器 - 点击右侧的 终端 图标
- 进入容器 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 中确认
- 返回 GitLab:
http://18.93.12.26 - 进入 管理中心 → CI/CD → Runners
- 找到刚创建的 Runner
- 确认状态:
- ✅ 状态指示灯为绿色
- ✅ 最后联系时间显示为"刚刚"或几秒前
- ✅ 显示 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
- 提交并推送
.gitlab-ci.yml文件 - 访问项目的 CI/CD → Pipelines 页面
- 观察 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 端口:
- 编辑 GitLab 配置文件(在 18.93.12.26 服务器):
/opt/1panel/apps/gitlab/gitlab/data/config/gitlab.rb
- 添加或修改:
gitlab_rails['gitlab_shell_ssh_port'] = 2222
- 重新配置 GitLab:
# 在 GitLab 容器中执行
gitlab-ctl reconfigure
- 或者,在 Runner 机器上配置 SSH:
mkdir -p ~/.ssh
cat >> ~/.ssh/config << EOF
Host 18.93.12.26
Port 2222
EOF
推荐做法:
使用 HTTP(S) 方式克隆(GitLab Runner 默认行为),无需额外配置。
5.4 Runner 显示离线
可能原因:
- 网络连接问题
- GitLab URL 配置错误
- Runner 服务未启动
- 防火墙阻止连接
排查步骤:
# 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 未正确挂载或权限不足。
解决方案:
- 确认编排配置中包含 Docker socket 挂载:
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- 确认注册命令中包含 Docker volumes:
--docker-volumes "/var/run/docker.sock:/var/run/docker.sock"
- 如果仍有问题,尝试启用特权模式(不推荐,但可以解决权限问题):
--docker-privileged=true
5.6 Pipeline 一直处于 pending 状态
可能原因:
- 没有可用的 Runner
- 任务标签与 Runner 标签不匹配
- Runner 被暂停
解决方案:
- 检查任务标签和 Runner 标签是否匹配
- 在 GitLab UI 中确认 Runner 状态为在线
- 检查 Runner 是否勾选了"运行未标记的作业"
- 查看 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 中:
- 进入 Runner 详情页
- 勾选 锁定到当前项目
- 勾选 保护(仅在受保护分支运行)
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:
- 获取 SSL 证书(Let's Encrypt 或购买)
- 修改 GitLab 配置使用 HTTPS
- 更新 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 定期检查
建议定期检查以下内容:
- Runner 在线状态(每天)
- 磁盘空间(每周)
df -h du -sh /opt/1panel/apps/gitlab-runner/ - Docker 镜像清理(每月)
docker image prune -a - 容器日志大小(每月)
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"
十、总结
关键要点
-
GitLab Runner 版本兼容性
- 确保 Runner 版本与 GitLab 版本兼容
- 推荐使用与 GitLab 相同或更新的版本
-
新的注册方式
- GitLab 15.6+ 使用身份验证令牌(
glrt-) - 配置在 UI 中管理,更安全
- 注册命令更简洁
- GitLab 15.6+ 使用身份验证令牌(
-
Docker 执行器
- 最常用的执行器类型
- 隔离性好,环境一致
- 需要挂载 Docker socket
-
网络配置
- Runner 只需要访问 GitLab 的 HTTP/HTTPS 端口
- SSH 端口主要用于代码克隆(可选)
-
安全考虑
- 避免使用特权模式
- 限制 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 挂载
下一步建议
-
配置更多 Runner
- 根据负载增加 Runner 数量
- 不同 Runner 使用不同标签
-
优化 CI/CD Pipeline
- 使用缓存加速构建
- 合理划分 stages
- 使用 artifacts 传递文件
-
监控和告警
- 配置 Prometheus 监控
- 设置 Runner 离线告警
- 监控资源使用情况
-
安全加固
- 启用 HTTPS
- 配置 Runner 访问控制
- 定期审计 CI/CD 配置
参考资料
本文更新时间:2025年12月5日
适用版本:GitLab CE 18.6.1, GitLab Runner 18.6.3, 1Panel v2.0.14
作者备注:本文所有步骤均在实际环境中测试通过,如有问题欢迎交流讨论。






浙公网安备 33010602011771号