在 Debian 上搭建 GitLab CI/CD 的完整流程

一 架构与准备

• 组件分工：
  • GitLab CE：托管代码与 CI/CD 流水线 的 Web 服务。
  • GitLab Runner：执行流水线中的作业（Job），支持 Shell、Docker 等执行器。
• 运行方式选择：
  • 全部部署在单台 Debian 服务器（Runner 与 GitLab 同机）。
  • 分离部署（GitLab 与 Runner 在不同主机，Runner 通过 URL 与 Token 注册到 GitLab）。
• 基础准备：
  • 一台可外网访问的 Debian 主机（建议 Debian 11/12），已安装 sudo 与 Docker（如使用 Docker 执行器）。
  • 开放防火墙端口：22（SSH）、80/443（HTTP/HTTPS）。
  • 域名与证书（可选）：为 external_url 配置 HTTPS/Let’s Encrypt。

二 安装 GitLab CE

• 更新系统并安装依赖：
  • sudo apt update && sudo apt upgrade -y
  • sudo apt install -y curl openssh-server ca-certificates tzdata perl
• 添加 GitLab 官方仓库并安装：
  • curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
  • sudo apt install -y gitlab-ce
• 配置外部访问地址（将域名或服务器 IP 替换为你的实际地址）：
  • sudo vim /etc/gitlab/gitlab.rb
  • external_url ‘https://your-domain-or-ip’
• 应用配置并启动服务：
  • sudo gitlab-ctl reconfigure
  • sudo systemctl enable --now gitlab
• 访问并完成管理员初始化：浏览器打开 external_url，设置管理员账号与密码。

三 安装并注册 GitLab Runner

• 安装 Runner（Debian 包方式）：
  • curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh | sudo bash
  • sudo apt install -y gitlab-ci-multi-runner
• 注册 Runner（交互或命令行）：
  • 获取注册信息：进入项目 Settings → CI/CD → Runners，复制 URL 与 Registration token。
  • 交互注册：sudo gitlab-runner register
  • 非交互注册示例（Docker 执行器）：
    • sudo gitlab-runner register --non-interactive
      –executor “docker”
      –docker-image “alpine:latest”
      –url “https://your-gitlab-url”
      –registration-token “YOUR_TOKEN”
      –description “docker-runner”
      –tag-list “docker,ci”
      –run-untagged “true”
      –locked “false”
      –docker-volumes “/var/run/docker.sock:/var/run/docker.sock”
      –docker-privileged “true”
      –access-level “not_protected”
• 常用管理命令：
  • 查看状态：sudo gitlab-runner status
  • 启动/停止/重启：sudo gitlab-runner start|stop|restart
  • 注册为系统服务（如未自动注册）：sudo systemctl enable --now gitlab-runner
• 使用 Docker 执行器的权限要点：
  • 将 Runner 用户加入 docker 组：sudo usermod -aG docker gitlab-runner
  • 重启 Runner：sudo systemctl restart gitlab-runner。

四 编写 .gitlab-ci.yml 与触发流水线

• 最小可用示例（Node.js 项目，使用 Docker 执行器）：
  • stages:
    • build
    • test
    • deploy
  • variables: NODE_IMAGE: node:18
  • build_job: stage: build image: $NODE_IMAGE script:
    • npm ci
    • npm run build --if-present artifacts: paths:
      • dist/ expire_in: 1 week
  • test_job: stage: test image: $NODE_IMAGE script:
    • npm test – --ci dependencies:
    • build_job
  • deploy_job: stage: deploy image: alpine:latest script:
    • echo “Deploying to $CI_ENVIRONMENT_NAME…”

    例如：rsync/scp/ssh 到目标服务器

    environment: name: staging url: https://staging.example.com only:
    • main
• 提交并触发：
  • git add .gitlab-ci.yml
  • git commit -m “Add CI/CD pipeline”
  • git push origin main
• 在 GitLab 查看：进入项目 CI/CD → Pipelines，可查看 作业日志、流水线图、失败定位 等信息。

五 安全与网络要点

• 防火墙放行：确保 22/80/443 端口对 GitLab 与 Runner 可达（云主机需配置安全组）。
• 邮件与通知：如使用 Postfix 发送邮件，请正确配置发信域名与中继；也可接入 Slack/Webhook 等通知。
• 证书与域名：为 external_url 配置 HTTPS/Let’s Encrypt，避免明文传输与浏览器告警。
• Runner 与 Docker：
  • 使用 Docker 执行器 时，优先采用 /var/run/docker.sock 挂载方式；如启用 –docker-privileged，务必在受控网络与可信项目中启用，降低安全风险。
  • 需要代理时，为 Runner 配置 HTTP/HTTPS 代理（如 ~/.docker/config.json 或 systemd 环境变量）。
• 变量与凭据：将 SSH 私钥、API Key、生产密码 等存入 CI/CD Variables（Masked/Protected），避免硬编码。