GitLab CI/CD流水线搭建实战：Runner注册与自动化构建部署配置

GitLab CI/CD是目前团队落地DevOps实践的常见入口，.gitlab-ci.yml一个文件就能定义从代码提交到测试、构建、部署的完整流水线。本文从Runner注册、流水线语法、构建缓存与部署环境四个环节，给出可直接照抄的GitLab CI/CD配置方法。

GitLab Runner安装与注册

Runner是执行流水线任务的Agent，先安装再注册到GitLab实例。以Ubuntu为例：

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | bash
apt install gitlab-runner

注册时到项目的Settings → CI/CD → Runners获取注册token：

gitlab-runner register   --url https://gitlab.example.com   --token glrt-xxx   --executor docker   --docker-image python:3.11-slim   --docker-volumes /var/run/docker.sock:/var/run/docker.sock

executor选择docker会让每个job跑在干净的容器里，tag建议打上docker，后续流水线按tag指定runner。

流水线文件结构与阶段定义

.gitlab-ci.yml的核心是stages与job。一个典型的构建、测试、部署三段式：

stages:
  - build
  - test
  - deploy

variables:
  IMAGE_TAG: "$CI_COMMIT_SHORT_SHA"

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t registry.example.com/app:$IMAGE_TAG .
    - docker push registry.example.com/app:$IMAGE_TAG
  only:
    - main

test:
  stage: test
  image: python:3.11-slim
  script:
    - pip install -r requirements.txt
    - pytest -q
  artifacts:
    reports:
      junit: junit.xml

deploy:
  stage: deploy
  image: alpine/k8s
  script:
    - kubectl set image deployment/app app=registry.example.com/app:$IMAGE_TAG
  environment:
    name: production
  only:
    - main

job默认并行执行，用needs关键字可跳过无关job提前启动下游依赖，用rules替代老旧的only/except能更精细控制触发条件。

构建缓存与依赖加速

流水线每次执行都要重新拉依赖，缓存能显著缩短构建时间：

cache:
  key: "$CI_COMMIT_REF_NAME"
  paths:
    - .cache/pip
    - node_modules/

install:
  stage: .pre
  script:
    - pip install -r requirements.txt

key用分支名区分缓存，避免不同分支互相覆盖。CI/CD缓存默认挂载在runner机器本地，使用多runner时要注意命中率，或用对象存储做分布式缓存。

多环境部署与环境变量管理

同一份代码要部署到preview、staging、production时，用environment关键字声明环境：

deploy-prod:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'

按tag触发生产发布、合并到main自动发布预发环境。密钥统一存到Settings → CI/CD → Variables，流水线里通过$VAR_NAME引用，禁止把密码直接写进yaml。变量要按environment:production隔离，避免预发环境拿到生产密钥。

流水线失败排查与效率优化

流水线失败集中在三处：runner镜像拉取超时、docker-in-docker的daemon未就绪、权限不足。日志里job失败前几行是关键。效率优化方面，docker pull慢时配置镜像加速器，测试job过长时用parallel: 8把测试用例分片并行跑，构建产物过大的用artifacts只保留必要文件。

整体思路是先让流水线跑通一个简单的hello-world job，确认runner连通性，再逐步叠加测试、构建、部署阶段，每加一个环节单独验证，能大幅减少排查成本。