在 Debian 上部署 GitLab CI/CD 的完整步骤

一 架构与准备

• 组件分工：
  • GitLab CE：托管代码与 CI/CD 流水线、Runner 注册与管理 的平台。
  • GitLab Runner：执行 .gitlab-ci.yml 中定义的作业（可用 Shell、Docker 等执行器）。
• 准备要点：
  • 一台 Debian 12/11 服务器（建议 2–4 核 CPU、4–8 GB 内存），可访问外网。
  • 域名或公网 IP，开放 80/443（HTTP/HTTPS），如需 SSH 拉取代码开放 22。
  • 准备 sudo 权限与基础工具（curl、openssh-server、ca-certificates、postfix 等）。

二 安装 GitLab CE

• 更新系统并安装依赖：
  • sudo apt update && sudo apt upgrade -y
  • sudo apt install -y curl openssh-server ca-certificates postfix tzdata
• 添加 GitLab 仓库并安装（将域名替换为你的实际地址）：
  • curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
  • sudo EXTERNAL_URL=“https://gitlab.example.com” apt install -y gitlab-ce
• 首次配置与启动：
  • sudo gitlab-ctl reconfigure
  • sudo gitlab-ctl restart
• 访问并完成管理员初始化：打开浏览器访问 https://gitlab.example.com。

三 安装与注册 GitLab Runner

• 安装 Runner（Debian 推荐方式，使用签名源）：
  • 导入 GPG 公钥：
    • curl -L https://packages.gitlab.com/runner/gitlab-runner/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/gitlab-runner.gpg >/dev/null
  • 添加 APT 源（以 Debian 12 bookworm 为例，其他版本替换为对应代号）：
    • echo “deb [signed-by=/usr/share/keyrings/gitlab-runner.gpg] https://packages.gitlab.com/runner/gitlab-runner/debian bookworm main” | sudo tee /etc/apt/sources.list.d/gitlab-runner.list
  • 安装并验证：
    • sudo apt update && sudo apt install -y gitlab-runner
    • gitlab-runner --version
• 注册 Runner（两种常见方式，择一）：
  • 交互式注册（推荐新手）：
    • sudo gitlab-runner register
    • 按提示输入 GitLab 实例 URL（如：https://gitlab.example.com）与 项目/实例注册令牌（在项目的 Settings → CI/CD → Runners 获取）。
    • 选择执行器（如 docker、shell），按需填写镜像或标签。
  • 非交互式注册（示例为项目级 Runner，使用 Docker 执行器）：
    • sudo gitlab-runner register
      –non-interactive
      –url https://gitlab.example.com
      –registration-token PROJECT_REGISTRATION_TOKEN
      –executor docker
      –docker-image “alpine:latest”
      –description “debian-runner”
      –tag-list “docker,debian”
      –run-untagged=“true”
      –locked=“false”
• 常用服务管理：
  • 查看状态：sudo gitlab-runner status
  • 启动/停止/重启：sudo gitlab-runner start|stop|restart
  • 查看日志：sudo gitlab-runner --debug run
• 使用 Docker 执行器的权限要点：
  • 将 Runner 用户加入 docker 组：sudo usermod -aG docker gitlab-runner
  • 重启 Runner：sudo systemctl restart gitlab-runner
  • 如需代理，可在 Runner 环境或容器内配置 HTTP/HTTPS 代理。

四 创建流水线 .gitlab-ci.yml 示例

• 示例一（多阶段 + Docker 执行器 + 缓存加速）：
  • stages:
    • build
    • test
    • deploy
  • variables: NODE_VERSION: “18”
  • cache: paths:
    • node_modules/
  • build_job: stage: build image: node:$NODE_VERSION script:
    • npm ci
    • npm run build --if-present artifacts: paths:
      • dist/
  • test_job: stage: test image: node:$NODE_VERSION script:
    • npm test – --ci
  • deploy_job: stage: deploy image: alpine:latest script:
    • echo “Deploying to $DEPLOY_SERVER”

    例如：rsync/scp/ssh 等实际部署命令

    only:
    • main
• 示例二（Shell 执行器，适合直接操作本机环境）：
  • stages:
    • build
    • deploy
  • build_job: stage: build script:
    • make build
  • deploy_job: stage: deploy script:
    • rsync -avz build/ user@prod-server:/var/www/app/ only:
    • main
• 提交并触发流水线：
  • 将 .gitlab-ci.yml 提交到仓库根目录，推送后进入 CI/CD → Pipelines 查看与运行。

五 网络、安全与优化建议

• 防火墙与端口：
  • 放行 80/443（GitLab Web/CI）、如需 SSH 拉取代码放行 22；云厂商安全组同步放通。
• HTTPS 与证书：
  • 在 /etc/gitlab/gitlab.rb 中设置 external_url 为 https://，并配置 Let’s Encrypt 或自有证书后执行 sudo gitlab-ctl reconfigure。
• Runner 隔离与并发：
  • 为不同项目/环境创建多个 Runner 或使用 tags 隔离；在注册时合理设置 concurrent 与资源限制。
• 缓存与镜像加速：
  • 合理使用 cache/artifacts 提升速度；在国内环境可使用 Docker 镜像加速 与 GitLab Runner 镜像源。
• 代理与私有依赖：
  • 如存在公司代理，为 Runner 与容器配置 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 环境变量。