Debian上GitLab的CI/CD如何配置与使用

在 Debian 上配置与使用 GitLab CI/CD

一 环境准备与安装

• 更新系统并安装依赖：sudo apt update && sudo apt upgrade -y；sudo apt install -y curl openssh-server ca-certificates tzdata perl。安装 Postfix 时选择 Internet Site 完成邮件配置。
• 添加 GitLab 官方仓库并安装：curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash；sudo apt install gitlab-ce。
• 配置访问地址：编辑 /etc/gitlab/gitlab.rb，设置 external_url（如 https://gitlab.example.com 或服务器 IP），执行 sudo gitlab-ctl reconfigure 使配置生效。
• 访问 GitLab Web 界面完成管理员初始化设置。

二 安装与注册 GitLab Runner

• 安装 Runner（Debian 包）：curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash；sudo apt install gitlab-runner。
• 注册 Runner：在项目的 Settings → CI/CD → Runners 获取 URL 与 Registration token，执行注册命令（交互或非交互均可）。常见示例（使用 Docker 执行器）：
  sudo gitlab-runner register --non-interactive
  –executor “docker”
  –docker-image alpine:latest
  –url “http://your-gitlab-url”
  –registration-token “your-registration-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”
  如需使用 Shell 执行器，可直接在注册时选择 Shell，便于在本机执行脚本。
• 启动服务：sudo systemctl daemon-reload && sudo systemctl start gitlab-runner && sudo systemctl enable gitlab-runner。
• 验证：在项目 Runners 页面应看到已注册并 绿色 状态的 Runner。

三 编写与触发流水线

• 在项目根目录创建 .gitlab-ci.yml，定义 stages 与 jobs。示例（Node.js + 简单测试）：
  stages:

  • build
  • test
  • deploy

  variables: NODE_VERSION: “18”

  build: stage: build image: node:$NODE_VERSION script: - npm ci - npm run build --if-present artifacts: paths: - dist/ expire_in: 1 week

  test: stage: test image: node:$NODE_VERSION script: - npm test – --ci

  deploy_prod: stage: deploy image: alpine:latest script: - echo “Deploying to production…” # 例如：rsync/scp/ssh 到目标服务器 only: - main environment: production

• 提交并推送：git add .gitlab-ci.yml && git commit -m “Add CI/CD” && git push origin main。

• 在 CI/CD → Pipelines 查看流水线状态与日志，必要时点击 Run Pipeline 手动触发。

四 安全与网络要点

• 防火墙放行：确保 22/80/443 端口开放（入站），以便 SSH、HTTP/HTTPS 访问。
• HTTPS 与证书：为域名配置 Let’s Encrypt 免费证书，编辑 /etc/gitlab/gitlab.rb 的 external_url 为 https:// 并配置证书路径，执行 sudo gitlab-ctl reconfigure 生效。
• Runner 与 Docker：若使用 Docker 执行器并需要拉取私有镜像，配置 Runner 主机的 Docker 登录凭证；如 Runner 以 Docker 方式运行，注意卷挂载与权限。
• Runner 用户组：当 Runner 使用 Docker 执行器且需要访问本机 Docker 守护进程时，可将 gitlab-runner 加入 docker 组：sudo usermod -aG docker gitlab-runner（变更后重启 Runner 服务）。

五 常见问题与排错

• Runner 未触发：检查项目 Runners 页面是否可见、Runner 是否 未锁定、标签是否匹配（job 的 tags）、分支是否被 only/except 限制。
• Docker 权限或拉取失败：确认 Runner 主机已安装并运行 Docker；如使用私有镜像，提前执行 docker login；必要时在 Runner 配置中添加 --docker-volumes 挂载凭据或配置私有镜像仓库。
• SSH 部署失败：在 Runner 主机生成密钥对，将公钥部署到目标服务器 ~/.ssh/authorized_keys；在 CI 中使用 SSH_PRIVATE_KEY 等 CI/CD 变量注入私钥，并在 before_script 中启动 ssh-agent、添加 known_hosts。
• Runner 服务异常：查看状态与日志（sudo systemctl status gitlab-runner；journalctl -u gitlab-runner -f），必要时重新注册或重启服务。