Debian用户如何使用GitLab CI/CD

Debian 上使用 GitLab CI/CD 的完整实践

一 环境准备与安装

• 更新系统并安装依赖：sudo apt update && sudo apt upgrade -y && sudo apt install -y curl openssh-server ca-certificates postfix tzdata perl
• 添加 GitLab 官方仓库并安装 GitLab CE：
  • curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
  • sudo apt install -y gitlab-ce
• 配置 external_url（在 /etc/gitlab/gitlab.rb 中）：external_url ‘https://your-domain-or-ip’
• 应用配置并启动：sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart
• 访问服务器地址完成管理员初始化设置。

二 安装与注册 GitLab Runner

• 安装 Runner（Debian 包）：
  • curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
  • sudo apt install -y gitlab-runner
• 注册 Runner（交互或命令行）：
  • 交互：sudo gitlab-runner register，依次输入 GitLab 实例 URL、项目注册令牌、Runner 描述、标签（如：debian, docker）、执行器（如：docker/shell）。
  • 非交互示例（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,debian”
      –run-untagged “true”
      –locked “false”
      –docker-volumes “/var/run/docker.sock:/var/run/docker.sock”
      –docker-privileged “true”
• 启动服务：sudo systemctl daemon-reload && sudo systemctl enable --now gitlab-runner
• 如需在 Docker 执行器里构建镜像，确保 gitlab-runner 用户加入 docker 组：sudo usermod -aG docker gitlab-runner，然后重启 Runner。

三 编写与触发流水线

• 在项目根目录创建 .gitlab-ci.yml（示例含缓存、产物与部署阶段）：
  • stages:
    • build
    • test
    • deploy
  • variables:
    • NODE_VERSION: “18”
  • cache:
    • key: ${CI_COMMIT_REF_SLUG} paths:
      • node_modules/
  • build_job:
    • stage: build
    • image: node:${NODE_VERSION}
    • script:
      • npm ci
      • npm run build --if-present
    • artifacts:
      • paths:
        • dist/
      • expire_in: 1 week
  • test_job:
    • stage: test
    • image: node:${NODE_VERSION}
    • script:
      • npm test – --ci
  • deploy_job:
    • stage: deploy
    • image: alpine:latest
    • script:
      • apk add --no-cache openssh-client rsync
      • rsync -avz --delete dist/ user@your-server:/var/www/app/
    • only:
      • main
• 提交并推送：git add .gitlab-ci.yml && git commit -m “Add CI/CD” && git push origin main
• 在 GitLab 项目页面进入 CI/CD → Pipelines 查看运行结果与日志。

四 安全与网络要点

• 防火墙放行端口：确保 22/80/443 可达（如使用 HTTPS，请优先开放 443）。
• 邮件与通知：如使用 Postfix，安装时选择 Internet Site 并完成发信配置；也可后续接入外部 SMTP。
• 证书与域名：生产环境建议使用 HTTPS/TLS，可通过 Let’s Encrypt 获取免费证书并在 /etc/gitlab/gitlab.rb 中配置 external_url 为 https:// 域名。

五 常见问题与排错

• Runner 无法连接 GitLab：核对 URL/Token、网络连通性与代理设置；必要时在 Runner 配置或容器内设置 HTTP/HTTPS 代理。
• Docker 构建权限问题：将 gitlab-runner 加入 docker 组并重启 Runner；仅在需要时启用 –docker-privileged，注意安全边界。
• Runner 标签不匹配导致排队：在 .gitlab-ci.yml 的 job 上设置 tags 与项目 Runner 的标签一致，或在 Runner 配置中允许运行未打标签任务（run_untagged）。
• 构建缓存与产物：合理使用 cache/artifacts 提升速度并传递编译结果；为产物设置合适的 expire_in 避免存储膨胀。