GitLab Runner 教程：CI/CD 自动化部署实战 – wiki基地

作者： /

GitLab Runner 教程：CI/CD 自动化部署实战

本教程将详细介绍 GitLab Runner 的安装、注册和配置，并通过一个实战案例，演示如何利用 GitLab CI/CD 实现自动化部署，帮助开发团队提升效率，加速软件交付。

1. 引言

在现代软件开发中，持续集成 (CI)、持续交付 (CD) 和持续部署 (CD) 已经成为不可或缺的实践。它们通过自动化代码的构建、测试和部署，显著减少了人工干预，降低了错误率，并加快了产品上市时间。

什么是 GitLab CI/CD？

GitLab CI/CD 是 GitLab 内置的一套强大工具集，旨在无缝集成到您的开发工作流中。它允许您在每次代码提交时自动执行一系列操作，如编译代码、运行测试、生成报告，直至最终将应用程序部署到服务器。

什么是 GitLab Runner？

GitLab Runner 是 GitLab CI/CD 的执行引擎。它是一个独立的、开源的应用程序，负责接收来自 GitLab 实例的 CI/CD 作业，并在其运行环境中执行这些作业。Runner 可以安装在各种操作系统上（如 Linux、Windows、macOS），并且支持多种执行器类型（如 Shell、Docker、Kubernetes），使其能够灵活适应不同的项目需求。为了安全和性能考虑，通常建议将 GitLab Runner 安装在与 GitLab 实例不同的机器上。

CI/CD 自动化部署的优势：

  • 提高开发效率： 自动化重复性任务，让开发人员可以专注于编写代码。
  • 减少人为错误： 机器执行比人工操作更精确，降低了因疏忽造成的错误。
  • 快速反馈机制： 每次代码提交后都能迅速得到测试结果，及时发现和修复问题。
  • 加速软件交付： 缩短从代码提交到生产环境部署的整个周期。

2. 准备工作

在开始安装和配置 GitLab Runner 之前，请确保您已具备以下条件：

  • GitLab 账户和项目： 您需要一个活跃的 GitLab 账户，并拥有一个用于托管代码和配置 CI/CD 的项目。
  • Linux 服务器： 一台用于安装 GitLab Runner 的 Linux 虚拟机或物理服务器。本教程将以 Debian/Ubuntu 系统为例进行操作。确保该服务器可以访问 GitLab 实例。

3. 安装 GitLab Runner

以下是在 Debian/Ubuntu 系统上安装 GitLab Runner 的详细步骤：

  1. 更新系统包列表并安装必要的依赖：
    打开您的服务器终端，执行以下命令更新软件包索引并安装 curl 和 ca-certificates，这些是后续添加仓库和下载文件所需的工具。

    bash
    sudo apt-get update
    sudo apt-get install -y curl ca-certificates

  2. 添加 GitLab 官方仓库：
    GitLab 官方提供了一个脚本，可以自动将 GitLab Runner 的 APT 仓库添加到您的系统源列表中。执行以下命令：

    bash
    curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

  3. 安装 GitLab Runner：
    仓库添加成功后，您现在可以通过 apt-get 命令安装 gitlab-runner。

    bash
    sudo apt-get install gitlab-runner
    安装完成后，gitlab-runner 服务将自动启动，并且您可以在系统中执行 gitlab-runner 命令。

4. 注册 GitLab Runner

安装完成后，您需要将本地的 GitLab Runner 实例注册到您的 GitLab 项目中，使其能够接收并执行 CI/CD 作业。

  1. 获取 Runner 认证 Token：

    • 登录您的 GitLab 账户。
    • 导航到您要集成 CI/CD 的项目。
    • 在项目侧边栏中，点击 Settings (设置) > CI/CD。
    • 滚动到 Runners (运行器) 部分。
    • 在这里，您会看到一个用于注册新 Runner 的 URL 和一个 Runner 认证 Token。请务必复制此 Token，因为它在离开此页面后可能无法再次查看。
    • 注意： GitLab 16.0 及更高版本引入了新的 Runner 创建工作流，现在使用 Runner 认证 Token (通常以 glrt- 为前缀) 替代了旧的 注册 Token。

  2. 注册 Runner：
    在您的 Linux 服务器终端中，执行以下命令开始注册过程：

    bash
    sudo gitlab-runner register
    系统将提示您输入一系列信息：

    • Enter your GitLab instance URL: 输入您在 GitLab 项目中复制的 GitLab 实例 URL (例如：https://gitlab.com/ 或您的私有 GitLab 实例地址)。
    • Enter the runner authentication token: 粘贴您在 GitLab 项目中获取的 Runner 认证 Token。
    • Enter a description for the runner: 为您的 Runner 输入一个有意义的描述，例如 my-project-shell-runner，以便在 GitLab 界面中识别它。
    • Enter tags for the runner (comma-separated): 输入一个或多个标签，用逗号分隔。这些标签用于在 .gitlab-ci.yml 文件中指定哪些作业可以由该 Runner 执行。例如：shell, linux, deployment。虽然可以留空，但强烈建议添加标签以更好地管理和调度作业。
    • Enter optional maintenance note for the runner: (可选) 输入维护说明，可以直接按回车跳过。
    • Enter an executor: 选择 Runner 的执行器类型。常用的有：
      • shell: 直接在 Runner 所在的服务器上执行脚本。简单直接，适合轻量级任务或对环境有特定要求的项目。
      • docker: 在 Docker 容器中运行作业，提供了更好的隔离性和可移植性。
      • kubernetes: 在 Kubernetes 集群中运行作业，适合大规模和动态环境。
        本教程中，我们选择 shell 执行器。

    注册成功后，您将看到 “Runner registered successfully” 的消息。此时，您可以返回 GitLab 项目的 CI/CD > Runners 页面，刷新后应该能看到新注册的 Runner 已经在线。

5. 配置 .gitlab-ci.yml 文件

.gitlab-ci.yml 文件是 GitLab CI/CD 管道的蓝图。它是一个 YAML 格式的文件，必须放置在您项目仓库的根目录，用于定义项目的构建、测试和部署流程。

基本结构：

“`yaml
stages:
– build
– test
– deploy

variables: # (可选) 全局变量
MY_VARIABLE: “hello”

before_script: # (可选) 所有作业前执行的脚本
– echo “全局前置脚本”

job_name_1: # 作业名称
stage: build # 所属阶段
image: ubuntu:latest # (可选) 如果使用 Docker executor
script:
– echo “执行构建任务”
– # 其他构建命令
artifacts: # (可选) 作业完成后要保存的文件或目录
paths:
– build/
expire_in: 1 week # 工件有效期

job_name_2:
stage: test
needs: [“job_name_1”] # (可选) 依赖其他作业
script:
– echo “执行测试任务”
– # 其他测试命令
coverage: ‘/Code coverage: \d+.\d+/’ # (可选) 解析测试覆盖率

deploy_job:
stage: deploy
tags:
– shell
– deployment # 指定由哪些 Runner 执行此作业
script:
– echo “执行部署任务”
– # 部署命令
only: # (可选) 定义何时运行此作业
– main # 只在 main 分支触发
except: # (可选) 定义何时不运行此作业
– schedules # 不通过定时任务触发
“`

  • stages: 定义了 CI/CD 管道中的不同阶段。作业将按照这些阶段的顺序执行。同一阶段内的作业可以并行运行。
  • variables: 定义可以在所有作业中使用的全局变量。
  • before_script / after_script: 定义在所有作业之前/之后执行的脚本。
  • job_name: 每个独立的 CI/CD 任务都被称为一个 “作业” (Job)，每个作业必须有一个唯一的名称。
  • stage: 每个作业必须指定它所属的阶段。
  • image: 如果您的 Runner 使用 docker 执行器，您需要在此处指定用于运行作业的 Docker 镜像。
  • script: 定义了作业要执行的 shell 命令列表。这些命令将按顺序在 Runner 上执行。
  • artifacts: 用于指定作业成功后需要保存的文件或目录。这些 “工件” 可以在后续阶段被其他作业下载使用，或者被用户手动下载。
  • only / except: 这些关键字用于控制作业何时运行或何时不运行，可以基于分支名、标签、触发器等条件。
  • tags: 这是非常重要的一项，用于指定哪些注册的 Runner 可以执行此作业。Runner 必须具有至少一个与作业 tags 列表中匹配的标签，才能被 GitLab 调度来执行该作业。

6. 实战示例：静态网站自动化部署

我们将创建一个简单的静态网站，并配置 GitLab CI/CD 管道。每次当代码推送到 main 分支时，GitLab Runner 将自动把网站部署到服务器的指定目录。

项目结构：

假设您的项目结构如下：

your-static-website/
├── public/
│ └── index.html
└── .gitlab-ci.yml

public/index.html 示例：

在 public 目录下创建一个 index.html 文件，内容如下：

“`html






Hello GitLab CI/CD


🎉 Hello from GitLab CI/CD! 🎉

这是一个通过 GitLab CI/CD 自动部署的静态网站。

祝贺您成功实现了自动化部署！


“`

.gitlab-ci.yml 示例：

在项目根目录创建 .gitlab-ci.yml 文件。假设您在注册 Runner 时使用了 shell 和 deployment 标签，并且希望将网站部署到服务器的 /var/www/html/my-static-site 目录。

“`yaml

定义 CI/CD 管道的阶段

stages:
– deploy

定义部署静态网站的作业

deploy_static_website:
stage: deploy # 指定此作业属于 ‘deploy’ 阶段
tags:
– shell # 确保 Runner 具备 ‘shell’ 标签
– deployment # 确保 Runner 具备 ‘deployment’ 标签
script:
– echo “🚀 开始部署静态网站…”
# 打印当前 public 目录内容，用于调试
– echo “— Public 目录内容 —”
– ls -l public/
– echo “———————–“

# 清理目标部署目录中的旧文件。'rm -rf .../*' 清除目录下所有内容。
# '|| true' 确保即使目标目录或文件不存在，命令也不会失败导致管道中断。
- sudo rm -rf /var/www/html/my-static-site/* || true

# 确保目标部署目录存在。'-p' 选项会创建所有不存在的父目录。
- sudo mkdir -p /var/www/html/my-static-site

# 将 'public' 目录下的所有文件和子目录递归复制到目标部署目录
- sudo cp -r public/* /var/www/html/my-static-site/

- echo "✅ 静态网站部署完成至 /var/www/html/my-static-site！"

only:
– main # 只在代码推送到 ‘main’ 分支时触发此部署作业
“`

关键说明：

  • tags: - shell - deployment: 这是将作业与特定 Runner 关联的关键。只有在注册时带有 shell 和 deployment 标签的 Runner 才会执行此作业。请根据您实际注册 Runner 时设置的标签进行调整。
  • script: 包含了实际的部署逻辑。
    • sudo rm -rf /var/www/html/my-static-site/* || true: 在部署前清空目标目录，确保部署的是最新版本。|| true 是一个常见技巧，用于防止 rm 命令在目标目录不存在或为空时报错中断 CI/CD 流程。
    • sudo mkdir -p /var/www/html/my-static-site: 确保目标部署目录存在。
    • sudo cp -r public/* /var/www/html/my-static-site/: 将 public 目录下的所有内容复制到服务器的指定目录。
  • sudo 权限注意事项：脚本中使用 sudo 命令来执行需要管理员权限的操作（如写入 /var/www/html 目录）。这要求运行 GitLab Runner 的用户（通常是 gitlab-runner 用户）拥有 sudo 权限，并且可能需要在 /etc/sudoers 文件中配置该用户无需密码即可执行特定命令，例如：
    # 允许 gitlab-runner 用户无密码执行 cp, rm, mkdir 到指定路径
    gitlab-runner ALL=(ALL) NOPASSWD: /usr/bin/cp -r /path/to/project/public/* /var/www/html/my-static-site/, /usr/bin/rm -rf /var/www/html/my-static-site/*, /usr/bin/mkdir -p /var/www/html/my-static-site
    注意： 授予 sudo 权限需谨慎，确保仅授予必要的权限以避免安全风险。在生产环境中，通常会采用更安全的部署方式，如 SSH 密钥部署、使用部署令牌或将 Runner 配置为在隔离环境中运行。
  • only: - main: 该作业只会在推送到 main 分支时触发。您可以根据需要修改为其他分支（如 master）或添加其他条件。

触发 CI/CD 流程：

  1. 将 public/index.html 文件和 .gitlab-ci.yml 文件添加到您的 GitLab 项目仓库中。

  2. 通过 Git 客户端将这些文件提交并推送到 main 分支：

    bash
    git add .
    git commit -m "feat: Add static website and CI/CD pipeline for automated deployment"
    git push origin main

  3. 推送到 GitLab 后，导航到您的 GitLab 项目界面。点击左侧菜单栏的 CI/CD > Pipelines。您应该会看到一个新的管道正在运行。

  4. 点击正在运行的管道，您可以查看 deploy_static_website 作业的详细日志。如果一切配置正确，管道将成功完成，您的静态网站将被自动部署到服务器上的 /var/www/html/my-static-site 目录。
  5. 现在，通过浏览器访问您的服务器 IP 地址或域名，您应该能看到刚刚部署的静态网站页面。

7. 总结

通过本教程，您已经掌握了 GitLab Runner 的核心概念、安装、注册流程，并学会了如何编写 .gitlab-ci.yml 文件来实现一个简单的静态网站自动化部署。这仅仅是 GitLab CI/CD 强大功能的开始。在实际项目中，您可以进一步探索以下高级功能：

  • 多阶段部署： 定义更复杂的管道，包括开发、测试、预发布和生产等多个环境的部署。
  • 缓存机制： 利用缓存加速依赖安装和构建过程。
  • 服务 (Services)： 在 Docker 执行器中，为作业提供数据库或其他服务。
  • 变量管理： 利用 CI/CD 变量安全地存储和使用敏感信息（如 API 密钥）。
  • 并行化和矩阵作业： 同时运行多个作业或在不同配置下运行作业，缩短执行时间。
  • 制品管理： 更好地管理和存储构建产物。

持续探索和实践，将使您能够构建出更加健壮、高效和自动化的 CI/CD 流程，为您的软件开发保驾护航。

滚动至顶部