如何在Linux中使用GitLab CI/CD

在 Linux 中使用 GitLab CI/CD 的实操指南

一 架构与准备

• 核心组件与流程：开发者提交代码 → GitLab 解析仓库根目录的 .gitlab-ci.yml → 根据 Runner 标签将任务调度到 Runner → 执行构建、测试、部署 → 在界面查看 Pipeline/Job 日志与产物。Runner 是实际执行作业的代理，需与项目或群组关联后使用。
• 安装 GitLab Runner（Ubuntu/Debian 示例）：
  • 安装：sudo apt-get update && sudo apt-get install -y gitlab-runner
  • 注册：sudo gitlab-runner register（按提示输入 GitLab 实例 URL、注册令牌、描述、标签和执行器，如 docker/shell）
  • 查看状态：sudo gitlab-runner list
• 安装 GitLab Runner（RHEL/CentOS 示例）：
  • 安装：sudo yum install -y gitlab-runner
  • 启动：sudo systemctl start gitlab-runner && sudo systemctl enable gitlab-runner
• Runner 标签与执行器要点：在 Settings → CI/CD → Runners 获取注册令牌；标签用于匹配作业（如 linux/shell），执行器决定运行环境（shell 简单通用，docker 更隔离可复用）。

二 编写第一个 .gitlab-ci.yml

• 最小可用示例（多阶段与产物、缓存）：
  • stages: 定义阶段顺序（如 build → test → deploy）
  • cache：缓存依赖目录（如 node_modules/）加速后续作业
  • artifacts：保存构建输出（如 dist/），供下游作业或下载
  • tags：指定具备相应标签的 Runner 执行
  • 示例：

    stages:
      - build
      - test
      - deploy
    
    variables:
      NODE_ENV: production
    
    build_job:
      stage: build
      image: node:20
      script:
        - npm ci
        - npm run build
      cache:
        paths:
          - node_modules/
      artifacts:
        paths:
          - dist/
        expire_in: 1 week
    
    test_job:
      stage: test
      image: node:20
      script:
        - npm test -- --ci
      cache:
        paths:
          - node_modules/
    
    deploy_job:
      stage: deploy
      image: alpine:latest
      before_script:
        - apk add --no-cache openssh-client
        - eval $(ssh-agent -s)
        - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
        - mkdir -p ~/.ssh
        - chmod 700 ~/.ssh
        - ssh-keyscan $SERVER_IP >> ~/.ssh/known_hosts
      script:
        - ssh -o StrictHostKeyChecking=no -i $SSH_PRIVATE_KEY $SERVER_USER@$SERVER_IP \
          "cd $PROJECT_PATH && git pull origin main && npm install && npm run build"
      environment:
        name: production
        url: https://your-domain.com
      when: manual
      tags:
        - linux
    

• 常用关键字速览：
  • image/services：指定作业镜像与依赖服务容器
  • before_script/after_script：全局或作业级前后置脚本
  • variables/cache/artifacts：变量、缓存、产物
  • dependencies：显式声明依赖的上游产物
  • tags/only/except/rules：Runner 选择、分支条件与更灵活的规则控制
  • when/allow_failure/retry/timeout：手动触发、允许失败、失败重试、超时设置。

三 变量与密钥及安全实践

• 在 GitLab 项目设置中添加变量：Settings → CI/CD → Variables（建议 Masked 且 Protected），常见变量：
  • SSH_PRIVATE_KEY：部署私钥（权限建议 600）
  • SERVER_IP / SERVER_USER / PROJECT_PATH：目标主机与部署路径
  • STAGING_*：预发布环境相关变量
• SSH 部署要点（在 before_script 中完成密钥注入与主机校验）：
  • 启动 ssh-agent，添加私钥，写入 known_hosts，避免交互确认
  • 生产部署建议使用 when: manual 或 rules 做门禁控制
• Runner 安全与隔离：
  • 生产环境优先使用 docker 执行器隔离依赖
  • 为 Runner 设置合适的 tags 与并发，避免越权执行
  • 变量与密钥不要硬编码在 .gitlab-ci.yml 中。

四 触发与排错

• 触发与查看：推送代码到指定分支或创建 Merge Request 会自动触发流水线；在 Project → CI/CD → Pipelines 查看状态与日志，进入 Job 可查看完整输出与产物下载。
• 常见排错清单：
  • 作业未运行：检查 Runner 是否在线、tags 是否匹配、项目/群组 Runner 是否启用
  • 权限失败：确认 SSH_PRIVATE_KEY 正确、目标目录权限与用户匹配
  • 脚本换行符问题：Windows 换行（CRLF）导致脚本执行异常，使用 dos2unix 或在 CI 中执行 sed 去除 \r
  • 缓存/依赖问题：清理缓存或调整 cache:key 避免交叉污染
  • 部署回滚：利用 artifacts 或镜像标签（如 $CI_COMMIT_SHA）实现快速回滚。

五 进阶场景与优化

• Docker 镜像构建与推送（使用 GitLab 容器镜像仓库或私有仓库）：
  • 示例要点：使用 docker:dind 服务；登录 CI_REGISTRY；构建并打上 $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA 标签后推送，便于追踪与回滚。
• 并行与矩阵构建：使用 parallel 或 parallel: matrix 提升测试覆盖与速度（如多版本 Node/Python 并行）。
• 测试报告与质量门禁：生成 JUnit 报告并上传，结合 rules 在 Merge Request 阶段做质量检查与阻断。
• 性能优化：合理使用 cache 与 artifacts、拆分耗时任务、减少不必要下载与重建，必要时增加 retry 与 timeout 提升稳定性。