闭坑指南！GitLab Runner Docker模式完整部署（含共享runner注册及认证配置问题排查）

在CI/CD自动化流程中，GitLab Runner是连接GitLab仓库与构建任务的核心组件，负责执行.gitlab-ci.yml中定义的构建、测试、部署等流程。Docker模式的GitLab Runner凭借环境隔离、版本可控、部署便捷的优势，成为企业级CI/CD部署的首选方案。本文将详细讲解GitLab Runner的Docker部署全流程，包含环境准备、容器部署、Runner注册、配置优化，以及部署过程中常见的认证失败、地址不生效等问题的解决方案，所有涉及敏感信息的脚本均做脱敏处理，可直接参考落地。

一、部署前置准备

1.1 环境要求

部署前需确保服务器满足以下基础条件，避免因环境缺失导致部署失败：

服务器系统：CentOS 7/8、Ubuntu 20.04+（本文以CentOS 7为例）；
Docker环境：已安装Docker 19.03+，且Docker服务正常运行；
网络权限：服务器可访问GitLab仓库地址（HTTP/HTTPS），开放对应端口（如本文示例中的8080端口）；
权限要求：服务器拥有root权限，可执行Docker、GitLab Runner相关命令；
GitLab版本：GitLab CE/EE 15.0+（与Runner版本兼容，本文使用GitLab Runner 18.10.0）。

1.2 核心依赖说明

GitLab Runner与GitLab仓库的通信依赖两个关键信息（需从GitLab后台获取，示例如下）：

GitLab仓库地址：示例 gitlab.example.com/（替换为实际仓库地址，…
Runner注册令牌：示例 vZ-GnroNAZ6Eyxo1vGqK（项目级/组级/实例级令牌均可，根据权限需求选择）；
个人访问令牌（PAT）：示例 glpat-个人令牌（用于拉取私有仓库代码的认证，后续详细说明）。

注：注册令牌和个人访问令牌均属于敏感信息，请勿泄露，建议通过GitLab后台定期更新。

二、GitLab Runner Docker部署完整流程

2.1 拉取GitLab Runner镜像

优先使用官方镜像，确保版本兼容性，本文选择稳定版18.10.0（与前文报错日志中Runner版本一致），拉取命令如下：

拉取GitLab Runner官方镜像（指定版本，避免版本兼容问题）

docker pull gitlab/gitlab-runner:18.10.0

验证镜像拉取成功

docker images | grep gitlab-runner

若拉取缓慢，可配置Docker镜像加速器（如阿里云加速器），提高拉取效率。

2.2 启动GitLab Runner容器

使用Docker run命令启动容器，挂载必要目录（用于持久化配置文件），确保容器重启后配置不丢失，命令如下：

# 启动GitLab Runner容器，挂载配置目录

docker run -d \
 --name gitlab-runner \
 --restart always \
 --privileged=true \
 -v /srv/gitlab-runner/config:/etc/gitlab-runner \
 -v /var/run/docker.sock:/var/run/docker.sock \
 gitlab/gitlab-runner:18.10.0

命令参数说明：

-d：后台运行容器；
--name gitlab-runner：指定容器名称，便于后续管理；
--restart always：容器退出后自动重启，保证服务高可用；
--privileged=true：授予容器特权，解决Docker executor权限不足问题；
-v /srv/gitlab-runner/config:/etc/gitlab-runner：挂载Runner配置目录，持久化config.toml文件；
-v /var/run/docker.sock:/var/run/docker.sock：挂载Docker守护进程，让Runner可在容器内调用Docker命令（用于Docker executor）。

启动后，通过以下命令验证容器运行状态：

查看容器运行状态

docker ps | grep gitlab-runner

查看容器日志，确认无启动报错

docker logs gitlab-runner --tail 10

若日志显示“Configuration loaded”，说明容器启动成功。

2.3 注册GitLab Runner

容器启动后，需将Runner注册到GitLab仓库，建立通信连接。注册操作需在容器内执行，步骤如下：

步骤1：进入GitLab Runner容器

进入容器终端

docker exec -it gitlab-runner bash

步骤2：执行注册命令

注册Runner，使用Docker executor

gitlab-runner register \
 --non-interactive \
 --url "https://gitlab.example.com/" \ # 替换为实际GitLab仓库地址
--registration-token "vZ-GnroNAZ6Eyxo1vGqK" \ # 替换为实际注册令牌
--name "my-docker-runner" \ # Runner名称，可自定义
--executor "docker" \ # 指定执行器为Docker
--docker-image "node:20" \ # 默认构建镜像，可根据项目需求修改
--docker-privileged # 授予Docker容器特权

注册成功后，会提示“Runner registered successfully”，同时配置信息会自动写入/etc/gitlab-runner/config.toml文件。

注：GitLab Runner 15.6+版本已 deprecate注册令牌方式，推荐使用认证令牌，但现有注册令牌仍可正常使用，后续可逐步迁移至新方式。

2.4 配置config.toml（关键优化）

config.toml是GitLab Runner的核心配置文件，决定Runner的运行方式、认证方式、构建环境等。注册成功后，需根据实际需求优化配置，重点解决私有仓库拉取认证、拉取地址覆盖等问题（脱敏后完整配置如下）：

concurrent = 1 # 全局并发构建数，根据服务器性能调整
check_interval = 0 # 检查新作业的间隔（秒），0使用默认值3秒
shutdown_timeout = 0 # 强制关机超时时间，0使用默认值30秒

[session_server]
session_timeout = 1800 # 会话超时时间（秒）

[[runners]]
name = "my-docker-runner" # Runner名称，与注册时一致
url = "https://gitlab.example.com/" # GitLab仓库地址，与注册时一致
id = 13 # Runner唯一ID，自动生成，无需修改
token = "UsLBeNzcwTR6PkNN79FV" # Runner认证令牌，自动生成，无需修改
executor = "docker" # 执行器类型，Docker模式
clone_url = "https://oauth2:glpat-个人令牌@gitlab.example.com" # 强制覆盖拉取地址，带PAT认证
[runners.cache]
MaxUploadedArchiveSize = 0 # 缓存最大上传大小，0无限制
[runners.cache.s3]
[runners.cache.gcs]
[runners.cache.azure]
[runners.docker]
tls_verify = false # 关闭Docker TLS验证（私有环境可关闭）
image = "node:20" # 默认构建镜像
privileged = true # 授予特权，解决构建时权限不足问题
disable_entrypoint_overwrite = false # 不覆盖容器入口点
oom_kill_disable = false # 启用OOM杀死机制
disable_cache = false # 启用缓存
volumes = ["/cache"] # 挂载缓存目录
volume_keep = false # 不保留 volumes
shm_size = 0 # 共享内存大小，0使用默认值
network_mtu = 0 # 网络MTU，0使用默认值

关键配置说明（解决前文遇到的认证和地址问题）：

clone_url：强制覆盖GitLab下发的代码拉取地址，格式为https://oauth2:【PAT令牌】@仓库地址:端口，用于解决私有仓库拉取认证失败问题，且需放在[[runners]]下一级（位置错误会导致配置不生效）；
token：Runner与GitLab通信的认证令牌，注册时自动生成，无需手动修改；
docker-privileged：授予Docker容器特权，避免构建时出现权限不足（如挂载目录、执行系统命令）；
concurrent：全局并发构建数，根据服务器CPU、内存配置调整，避免资源耗尽（前文日志中提示可调整为2-4，优化长轮询问题）。

配置修改完成后，需重启GitLab Runner使配置生效：

容器内重启Runner

gitlab-runner restart

退出容器

exit

补充说明：GitLab Runner每3秒会检查一次配置文件修改，大多数配置无需重启即可生效，但clone_url等核心配置建议重启确认生效。

2.5 验证部署成功

部署完成后，需从GitLab后台和服务器两个维度验证Runner是否正常可用：

GitLab后台验证：登录GitLab → 进入对应项目 → Settings → CI/CD → Runners，可看到注册的Runner，状态显示“活跃”；
服务器验证：执行以下命令，查看Runner状态，确认无报错：

查看Runner状态

docker exec gitlab-runner gitlab-runner status

查看Runner列表

docker exec gitlab-runner gitlab-runner list

若状态显示“running”，且GitLab后台Runner为“活跃”，说明部署成功，可正常接收构建任务。

三、常见问题排查（重点解决前文报错）

部署过程中，容易出现认证失败、拉取地址不生效、Runner注册成功但无法接收任务等问题，本文结合前文遇到的报错，给出针对性解决方案。

3.1 问题1：拉取代码报错“HTTP Basic: Access denied”

报错日志（脱敏）：

2026-04-03T03:37:55.759243Z 01E remote: HTTP Basic: Access denied
2026-04-03T03:37:55.759257Z 01E fatal: Authentication failed for 'http://gitlab.example.com/xxx.xxx.git/'

原因分析：

核心原因：Runner拉取私有仓库代码时，未携带有效的认证信息（账号密码或PAT令牌）；
次要原因：clone_url配置位置错误（如放在[runners.cache]后面），导致配置不生效，Runner仍使用GitLab下发的旧HTTP地址拉取代码。

解决方案：

确认个人访问令牌（PAT）有效，且拥有read_repository权限（生成方式：GitLab头像 → Edit Profile → Access Tokens → 勾选read_repository，生成后复制保存，仅显示一次）；
修改config.toml，将clone_url放在[[runners]]下一级（正确位置参考本文2.4节完整配置）；
重启GitLab Runner，确保配置生效；
备选方案：若无需强制覆盖地址，可在config.toml中添加环境变量，通过HTTP请求头携带PAT认证（适合不想修改clone_url的场景）：

[[runners]]
...
environment = [
"GIT_CONFIG_COUNT=1",
"GIT_CONFIG_KEY_0=http.extraheader",
"GIT_CONFIG_VALUE_0=Authorization: Bearer glpat-个人令牌"
]
...

说明：http.extraheader的作用是给Git拉代码的HTTP请求添加认证请求头，携带PAT令牌，实现无密码认证，且比URL带密码更安全（日志不会暴露令牌）。

3.2 问题2：修改config.toml的url后，拉取地址仍为旧地址

原因分析：

config.toml中的url仅用于Runner连接GitLab API、获取构建任务，不影响代码拉取地址，代码拉取地址由GitLab服务器下发，默认使用GitLab的全局配置或项目配置中的地址。这个问题是导致remote: HTTP Basic: Access denied的根本原因。config.toml配置的clone_url必须要带PAT令牌，否则会报认证错误。

解决方案：

方案1（推荐）：使用clone_url强制覆盖拉取地址（参考本文2.4节配置），无论GitLab下发什么地址，Runner都会使用clone_url指定的地址拉取；
方案2（管理员权限）：登录GitLab后台 → Admin Area → Settings → General → 找到“Custom Git clone URL for HTTP(S)”，填入目标地址（如gitlab.example.com ），保存后所有项目、所有Runner都会使用该地址拉取代码；
方案3（单项目生效）：在项目的.gitlab-ci.yml中添加变量，覆盖拉取地址：

variables: GIT_CLONE_URL: "https://oauth2:glpat-个人令牌@gitlab.example.com/xxx.xxx.git"

3.3 问题3：Runner注册成功，但GitLab后台显示“未活跃”

原因分析：

Runner与GitLab仓库网络不通（如端口未开放、防火墙拦截）；
config.toml中的url或token错误；
Runner容器未正常运行，或重启失败。

解决方案：

检查服务器与GitLab仓库的网络连通性：ping gitlab.example.com、telnet gitlab.example.com；
确认config.toml中的url和token与GitLab后台一致，无拼写错误；
重启GitLab Runner容器：docker restart gitlab-runner，查看日志排查报错。

3.4 问题4：日志提示“Long polling issues detected”

报错日志（脱敏）：

WARNING: CONFIGURATION: Long polling issues detected.
Issues found:

- Request bottleneck: 1 runners have request_concurrency=1, causing job delays during long polling

原因分析：

全局并发数（concurrent）设置为1，导致Runner处理任务时出现瓶颈，可能造成任务延迟。

解决方案：

修改config.toml中的concurrent值，根据服务器性能调整为2-4（如concurrent = 2），重启Runner后生效；也可启用FF_USE_ADAPTIVE_REQUEST_CONCURRENCY特性，让Runner自动调整并发数。

3.5 如何注册共享runner

首先你必须是GitLab管理员，才能注册共享runner。在项目中的设置CI/CD只能配置特定该项目运行的Runner。必须是管理员菜单-概览-Runner右上角的注册一个实例runner才可以。

四、部署优化与最佳实践

4.1 配置持久化

前文部署时已挂载/srv/gitlab-runner/config目录，用于持久化config.toml文件，避免容器删除后配置丢失。建议定期备份该目录，防止配置误删或损坏。

4.2 镜像优化

指定固定的Runner镜像版本（如18.10.0），避免使用latest版本，防止版本更新导致兼容问题；
根据项目需求，自定义构建镜像（如包含Node.js、Maven等依赖），减少构建时的依赖安装时间，提高构建效率。

4.3 安全优化
个人访问令牌（PAT）仅授予必要权限（如read_repository），避免授予admin权限，降低安全风险；
定期更新PAT令牌和Runner注册令牌，避免令牌泄露导致的安全隐患；
关闭Docker TLS验证仅适用于私有环境，公网环境建议启用TLS验证，提高安全性。

4.4 日志排查

当Runner出现异常时，可通过以下命令查看详细日志，快速定位问题：

查看Runner实时日志

docker logs -f gitlab-runner

查看最近100行日志

docker logs gitlab-runner --tail 100

查看Runner配置验证日志（排查config.toml格式错误）

docker exec gitlab-runner gitlab-runner verify

五、总结

总结下来，其实熟悉docker部署gitlab runner很容易，花个半个小时就可以完成。最难搞的是出现的remote: HTTP Basic: Access denied认证问题，完全没有资料参考。还有就是共享Runner的配置，一定要是管理员权限才可以。切记切记！

本文详细讲解了GitLab Runner Docker模式的部署全流程，从环境准备、容器部署、Runner注册，到config.toml配置优化，再到常见问题排查，覆盖了部署过程中的核心要点和易错点。重点解决了私有仓库拉取认证失败、拉取地址不生效等实际问题，所有脚本均做脱敏处理，可直接适配不同企业的私有GitLab环境。

Docker模式的GitLab Runner凭借环境隔离、部署便捷的优势，能够有效提升CI/CD流程的稳定性和效率。在实际部署中，需根据服务器性能、项目需求，合理调整并发数、构建镜像、认证方式等配置，同时做好配置备份和安全防护，确保Runner长期稳定运行。

后续可根据实际需求，扩展Runner的功能，如配置缓存、使用Docker Compose管理多Runner、实现Runner自动扩缩容等，进一步优化CI/CD自动化流程。