从零到CI/CD：给你的GitLab服务器装上GitLab Runner（含避坑指南）

从零到CI/CD给你的GitLab服务器装上GitLab Runner含避坑指南在当今快节奏的软件开发环境中持续集成和持续部署CI/CD已成为提升团队效率的必备实践。想象一下每次代码提交后都能自动运行测试、构建镜像并部署到测试环境这不仅能减少人为错误还能让开发者更专注于创造价值而非重复性工作。本文将带你从零开始在已搭建好的GitLab服务器上配置GitLab Runner实现完整的CI/CD流水线。1. GitLab Runner核心概念解析GitLab Runner是GitLab CI/CD的执行引擎负责运行你在.gitlab-ci.yml中定义的任务。理解它的工作原理是避免后续踩坑的关键。Runner的三种关键属性Executor类型决定任务在哪里运行常见的有shell直接在Runner所在机器执行docker在Docker容器中执行推荐kubernetes在K8s集群中执行Tags用于匹配特定Runner与任务Lock状态决定Runner是否可以运行无标签的任务提示生产环境推荐使用Docker executor它能提供更好的隔离性和可重复性。下面是一个典型的Runner注册流程中需要准备的信息表格配置项示例值获取方式GitLab URLhttp://your.gitlab.urlGitLab实例地址Registration Tokenglrt-xxxxxx项目设置→CI/CD→RunnersExecutor类型docker根据环境选择默认镜像alpine:latest无特殊需求时的基础镜像2. 实战安装与注册Runner假设你的GitLab服务器已正常运行在CentOS 7.6上以下是具体操作步骤2.1 安装GitLab Runner# 添加官方仓库 curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash # 安装最新版本 sudo yum install -y gitlab-runner # 验证安装 gitlab-runner --version2.2 注册Runner到项目注册前先在GitLab项目中获取以下信息进入项目 → Settings → CI/CD → Runners记录Set up a specific Runner manually部分的URL和Token执行注册命令sudo gitlab-runner register按提示输入GitLab实例URL如http://gitlab.example.com注册Token描述如my-project-runner标签可选如docker,aws执行器推荐docker默认镜像如docker:latest2.3 验证Runner状态# 查看Runner列表 gitlab-runner list # 检查运行状态 systemctl status gitlab-runner常见问题排查Runner显示为灰色检查网络连通性和Token是否正确任务卡在Pending确认Runner标签与任务匹配且Runner未设置为locked3. 编写你的第一个CI/CD流水线在项目根目录创建.gitlab-ci.yml文件这是定义CI/CD流程的核心。以下是一个包含测试、构建、部署三阶段的示例stages: - test - build - deploy variables: DOCKER_IMAGE: my-app:$CI_COMMIT_SHORT_SHA unit-test: stage: test image: node:14 script: - npm install - npm test only: - merge_requests docker-build: stage: build image: docker:latest services: - docker:dind script: - docker build -t $DOCKER_IMAGE . - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker push $DOCKER_IMAGE rules: - if: $CI_COMMIT_BRANCH main production-deploy: stage: deploy image: alpine:latest script: - apk add --no-cache openssh-client - ssh deployserver docker pull $DOCKER_IMAGE docker-compose up -d when: manual only: - main关键元素解析stages定义流水线的阶段顺序variables设置全局变量image指定任务运行环境services启用额外服务如Docker-in-Dockerrules/when控制任务触发条件4. 高级配置与性能优化4.1 Runner并发配置编辑/etc/gitlab-runner/config.toml调整性能参数concurrent 4 check_interval 3 [[runners]] executor docker [runners.docker] tls_verify false image alpine:latest privileged true disable_cache false volumes [/cache, /var/run/docker.sock:/var/run/docker.sock]重要参数说明concurrent同时运行的最大任务数volumes挂载宿主机目录如Docker socketprivileged允许容器运行特权操作4.2 缓存与制品管理加速流水线的两个关键机制缓存适合node_modules等依赖目录cache: key: $CI_COMMIT_REF_SLUG paths: - node_modules/制品用于阶段间传递构建结果build-job: artifacts: paths: - build/ expire_in: 1 week4.3 安全最佳实践敏感数据保护使用项目Variables存储密码/密钥避免在日志中输出敏感信息script: - echo $API_KEY | docker login -u $USER --password-stdin镜像安全docker-build: image: name: docker:latest entrypoint: [] # 禁用默认entrypoint5. 常见问题解决方案问题1Runner注册成功但不执行任务检查Runner是否显示绿色且未锁定确认项目设置中允许未标记的任务查看Runner日志journalctl -u gitlab-runner -f问题2Docker executor报权限错误# 将gitlab-runner用户加入docker组 sudo usermod -aG docker gitlab-runner sudo systemctl restart gitlab-runner问题3流水线执行超慢优化.gitlab-ci.yml# 避免每次安装依赖 cache: key: $CI_COMMIT_REF_SLUG paths: - vendor/配置Runner使用SSD存储增加concurrent值问题4部署时SSH连接失败使用SSH密钥代替密码before_script: - mkdir -p ~/.ssh - echo $SSH_PRIVATE_KEY ~/.ssh/id_rsa - chmod 600 ~/.ssh/id_rsa在实际项目中我发现最影响效率的往往是网络问题。为Docker executor配置国内镜像源能显著提升速度[runners.docker] pull_policy if-not-present [[runners.docker.volumes]] name daemon-config mount_path /etc/docker/daemon.json read_only true创建一个daemon.json文件{ registry-mirrors: [https://registry.cn-hangzhou.aliyuncs.com] }