1. GitLab Runner 概述与安装准备GitLab Runner 是 GitLab CI/CD 的核心组件负责执行持续集成和持续交付的作业。它作为一个轻量级的代理程序可以部署在各种操作系统上与 GitLab 实例协同工作。在 Rocky Linux 10 上安装 GitLab Runner 是一个相对直接的过程但需要注意一些关键细节以确保稳定运行。1.1 系统环境检查在开始安装前建议先检查系统环境# 检查系统版本 cat /etc/redhat-release # 检查CPU架构 uname -m # 确保curl已安装 sudo dnf install -y curl提示虽然Rocky Linux 10默认包含curl但某些最小化安装可能缺少这个工具。如果遇到command not found错误请先安装curl。1.2 用户与权限规划GitLab Runner 需要一个专用系统用户来运行作业。我们选择创建名为gitlab-runner的用户这符合Linux系统管理的最佳实践# 检查是否已存在gitlab-runner用户 id gitlab-runner || echo 用户不存在可以继续安装创建专用用户有几个重要优势隔离运行环境增强安全性便于权限管理方便日志追踪和问题排查2. 安装GitLab Runner2.1 下载二进制文件从官方源下载最新版的GitLab Runner二进制文件sudo curl -L --output /usr/local/bin/gitlab-runner \ https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64这里有几个关键点需要注意使用-L参数让curl跟随重定向输出路径选择/usr/local/bin这是存放本地安装程序的常规位置下载的是针对amd64架构的Linux版本注意如果您的系统是ARM架构需要将amd64替换为arm64。2.2 设置执行权限下载完成后需要赋予执行权限sudo chmod x /usr/local/bin/gitlab-runner权限设置非常重要它确保root用户可以安装服务gitlab-runner用户可以执行程序其他用户无法修改或执行2.3 创建系统用户创建一个专用的系统用户来运行GitLab Runnersudo useradd --comment GitLab Runner --create-home gitlab-runner --shell /bin/bash参数说明--comment添加用户描述--create-home创建用户主目录--shell /bin/bash指定bash作为默认shell2.4 安装系统服务将GitLab Runner安装为系统服务sudo /usr/local/bin/gitlab-runner install --usergitlab-runner \ --working-directory/home/gitlab-runner服务安装参数--user指定运行服务的用户--working-directory设置工作目录启动服务并设置开机自启sudo /usr/local/bin/gitlab-runner start2.5 创建符号链接可选但推荐为了方便使用可以创建一个符号链接sudo ln -sf /usr/local/bin/gitlab-runner /usr/bin/gitlab-runner这样就能直接使用gitlab-runner命令而不需要输入完整路径。3. GitLab网页端配置3.1 访问Runner设置页面登录GitLab网页界面进入项目设置 → CI/CD → Runners点击New project runner按钮3.2 填写Runner配置关键配置项说明配置项值重要性Tagskoji-build★★★★★Run untagged jobs勾选★★★★Descriptionyuhua-os-builder★★标签(koji-build)的作用用于将作业定向到特定Runner后续CI/CD流水线会根据这个标签选择Runner建议使用有意义的、项目相关的名称勾选Run untagged jobs可以防止忘记给作业打标签时任务被阻塞配置错误导致的作业停滞3.3 获取注册令牌点击Create runner后页面会显示一个以glrt-开头的注册令牌。这个令牌有以下几个特点每个Runner唯一一次性使用注册后失效有效期为30分钟重要立即复制这个令牌页面刷新后将无法再次查看。4. 终端注册Runner4.1 执行注册命令在服务器终端运行注册命令sudo gitlab-runner register4.2 输入配置信息按照提示依次输入以下信息GitLab实例URLhttp://172.16.104.218:8080/注意根据实际GitLab地址修改确保使用HTTP或HTTPS协议注册令牌粘贴从网页复制的glrt-xxxx令牌描述可以直接回车使用默认值或输入有意义的名称如yuhua-koji-builder标签可以回车跳过已在网页端设置执行器(Executor)输入shellshell是最简单的执行器适合大多数基础使用场景对于更高级的用例可以考虑docker或kubernetes4.3 验证注册结果注册完成后可以通过以下命令检查Runner状态sudo gitlab-runner verify输出应显示Runner已连接并准备就绪。5. 常见问题与解决方案5.1 连接问题排查如果Runner无法连接到GitLab实例可以尝试# 测试网络连通性 ping 172.16.104.218 # 测试端口访问 telnet 172.16.104.218 8080 # 检查防火墙规则 sudo firewall-cmd --list-all5.2 权限问题处理常见的权限错误及解决方法错误现象可能原因解决方案permission denied二进制文件权限不正确sudo chmod x /usr/local/bin/gitlab-runner无法创建文件工作目录权限问题sudo chown -R gitlab-runner:gitlab-runner /home/gitlab-runner命令找不到PATH环境变量问题使用完整路径或创建符号链接5.3 服务管理命令常用服务管理命令备忘命令用途sudo gitlab-runner start启动服务sudo gitlab-runner stop停止服务sudo gitlab-runner restart重启服务sudo gitlab-runner status查看状态sudo gitlab-runner run前台运行调试用6. 高级配置与优化6.1 并发设置编辑配置文件调整并发数sudo vim /etc/gitlab-runner/config.toml找到concurrent参数根据服务器性能调整concurrent 4建议初始值设置为CPU核心数的1-2倍根据实际负载调整。6.2 日志配置默认日志位置/var/log/gitlab-runner/调整日志级别在config.toml中log_level info # 可改为debug获取更详细日志6.3 安全加固建议定期更新Runner版本sudo gitlab-runner stop sudo curl -L --output /usr/local/bin/gitlab-runner \ https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64 sudo chmod x /usr/local/bin/gitlab-runner sudo gitlab-runner start限制Runner网络访问使用防火墙规则限制出站连接只允许访问必要的GitLab实例和依赖服务定期检查Runner日志sudo journalctl -u gitlab-runner -f7. 实际使用经验分享在实际生产环境中运行GitLab Runner几个月后我总结了一些有价值的经验标签策略不要过度使用标签。开始时我们为每个微服务创建了独立标签结果导致管理复杂。后来改为按环境(dev/stage/prod)和机器类型(highmem/gpu)分类效率大幅提升。资源监控安装后前两周要密切监控系统资源。我们曾遇到一个失控的构建作业吃光了16GB内存导致服务器崩溃。现在我们会在config.toml中设置output_limit使用cgroups限制资源使用对长时间运行的作业设置超时缓存配置合理配置缓存可以显著提升构建速度。我们为Maven/NPM等包管理器设置了共享缓存[[runners]] [runners.cache] Type s3 Shared true [runners.cache.s3] ServerAddress s3.example.com AccessKey access-key SecretKey secret-key BucketName gitlab-runner-cache BucketLocation us-east-1灾备方案永远要有备用Runner。我们配置了至少两台Runner服务器当主节点维护时CI/CD流程不会中断。使用相同的标签可以让作业自动故障转移。清理策略定期清理工作空间。我们设置了每周执行的cron作业0 3 * * 0 find /home/gitlab-runner/builds -mtime 7 -exec rm -rf {} \;这些经验都是通过实际运维积累的希望能帮助您避免我们踩过的坑。GitLab Runner是一个非常灵活的工具正确的配置和管理可以极大提升团队的开发效率。
