Linux GitLab的持续集成与部署

Linux 上搭建 GitLab CI/CD 的完整实践

一 架构与前置准备

• 核心组件与职责
  • GitLab：托管代码与流水线编排（内置 GitLab CI）。
  • GitLab Runner：实际执行作业的代理，支持 Shell、Docker、Docker-in-Docker（DinD）、Kubernetes 等执行器，可分布式部署。
• 运行环境建议
  • 自托管 GitLab 或 GitLab.com 均可；目标服务器需具备 SSH 访问、对应运行时（如 Node.js/Python/Java）与 Web 服务器（Nginx/Apache）。
• Runner 部署方式（二选一或混合）
  • 直接在 Linux 主机安装并注册 Runner（便于访问内网资源）。
  • 以 Docker 运行 Runner，便于隔离与扩缩容（挂载 /var/run/docker.sock 可使用宿主机 Docker 引擎）。

二 安装与注册 Runner

• 方式 A：直接在 Linux 主机安装
  • 安装 Runner（Debian/Ubuntu 示例）：
    • 添加仓库与 GPG、安装包：
      • curl -L --output /etc/apt/trusted.gpg.d/gitlab.asc https://packages.gitlab.com/install/repositories/gitlab/gitlab-runner/gpgkey
      • echo “deb https://packages.gitlab.com/gitlab/gitlab-runner/ubuntu $(lsb_release -cs) main” | sudo tee /etc/apt/sources.list.d/gitlab-runner.list
      • sudo apt-get update & & sudo apt-get install -y gitlab-runner
  • 注册 Runner：
    • 获取项目的 Registration token（项目：Settings > CI/CD > Runners > New project runner），执行注册并选择执行器（如 shell/docker）。
• 方式 B：以 Docker 运行 Runner
  • 启动容器（挂载配置与 Docker 套接字）：
    • docker run -d --name gitlab-runner --restart always
      -v /var/run/docker.sock:/var/run/docker.sock
      -v /data/gitlab_runner/config:/etc/gitlab-runner
      gitlab/gitlab-runner:latest
  • 进入容器注册：
    • docker exec -it gitlab-runner gitlab-runner register
• 常用检查
  • 查看 Runner 状态：gitlab-runner status；查看日志：journalctl -u gitlab-runner -f。

三 编写 .gitlab-ci.yml 与变量

• 基本结构与示例
  • stages 定义阶段顺序；每个 job 通过 script 执行命令；可用 artifacts 在阶段间传递产物；通过 rules 精确控制触发分支与事件。
  • 示例（Node.js + SSH 部署到测试环境）：
    • stages:
      • build
      • test
      • deploy
    • variables:
      • NODE_VERSION: “18”
    • build:
      • stage: build
      • image: node:$NODE_VERSION
      • script:
        • npm ci
        • npm run build
      • artifacts:
        • paths:
          • dist/
    • test:
      • stage: test
      • image: node:$NODE_VERSION
      • script:
        • npm test – --ci
    • deploy_staging:
      • stage: deploy
      • image: alpine:latest
      • before_script:
        • apk add --no-cache openssh-client
        • mkdir -p ~/.ssh
        • chmod 700 ~/.ssh
        • echo “$SSH_KNOWN_HOSTS” > > ~/.ssh/known_hosts
        • echo “$SSH_PRIVATE_KEY” | tr -d ‘\r’ | ssh-add -
      • script:
        • ssh -i “$SSH_PRIVATE_KEY” -o StrictHostKeyChecking=no $SERVER_USER@$SERVER_IP
          “cd $PROJECT_PATH & & git pull origin $CI_COMMIT_REF_NAME & & npm install & & npm run build”
      • environment:
        • name: staging
        • url: https://staging.example.com
      • only:
        • develop
• 变量与安全
  • 在 GitLab 项目设置中添加变量：Settings > CI/CD > Variables（如 SSH_PRIVATE_KEY、SERVER_IP、SERVER_USER、PROJECT_PATH、SSH_KNOWN_HOSTS），勾选 Masked 与（必要时）Protected，避免明文写入配置。
  • 生产部署建议 when: manual 并绑定到 main 分支，降低风险。

四 部署策略与进阶实践

• 多环境部署
  • 通过 environment 与分支策略区分 staging/production，例如 develop 自动部署到预发，main 手动部署到生产，并在 GitLab 环境页面查看与回滚。
• SSH 免密与 known_hosts
  • 方式一：在 Runner 容器中预置 known_hosts（通过变量注入）。
  • 方式二：在 Runner 配置 /etc/gitlab-runner/config.toml 的 [[runners]] 下启用：
    • [runners.ssh]
      • disable_strict_host_key_checking = true
    • 注意：会降低主机密钥校验安全性，仅在受控网络中使用。
• Docker 与镜像流水线
  • 使用 Docker-in-Docker（DinD） 或宿主机 Docker 构建并推送镜像到 GitLab Container Registry 或私有仓库，然后在目标主机拉取并运行；适合标准化交付与多环境一致性。
• 健康检查与回滚
  • 部署后执行 HTTP 健康检查，失败则告警或阻断；提供 手动回滚 作业（如基于 Git 回退或切换上一镜像标签），确保可观测与可恢复。
• 蓝绿部署与流量切换
  • 通过维护 blue/green 两套目录或实例，部署完成后切换 Nginx 配置并重载，实现零停机或低停机发布。

五 常见问题与排查

• Runner 无法连接或权限不足
  • 检查 Runner 标签（tags） 与作业匹配；确认执行器（shell/docker）具备所需权限与工具链；必要时使用 privileged 或挂载所需目录/套接字。
• SSH 主机密钥校验失败
  • 在 Runner 容器中写入 known_hosts 或在 config.toml 中临时关闭严格校验（仅测试环境）。
• 作业卡在 “pending”
  • 没有可用 Runner、标签不匹配或 Runner 被暂停；在 Admin > Runners 查看并修复。
• 变量未生效或被遮蔽
  • 确认变量作用域（项目/组/实例）、Protected 与 Masked 设置；在作业中打印调试信息（注意遮蔽敏感值）。
• 构建缓存与产物
  • 合理使用 cache/artifacts 加速构建与跨阶段传递产物；避免缓存 node_modules 等易变目录引发不一致。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！