GitLab CI/CD流水线实战：从代码提交到自动部署的完整配置

GitLab CI/CD是仓库与流水线一体化的DevOps实践方案，开发者提交代码后自动触发构建、测试、部署，把发布频率从每周一次提升到每天几十次。整套体系的核心是一个.gitlab-ci.yml文件，掌握它的语法与最佳实践就能搭建完整的自动发布链路。

GitLab CI/CD基本概念：Runner、Pipeline、Job与Stage

GitLab CI/CD由几个基础概念组成。Runner是执行任务的独立机器或容器，注册到项目或组后负责运行流水线；Pipeline是一次提交触发的完整流水线执行；Pipeline内部按Stage（阶段）划分，每个Stage包含若干Job（任务），同一Stage全部成功才会进入下一Stage。默认的.gitlab-ci.yml写在项目根目录，语法为YAML。

2. 一个完整的GitLab CI/CD流水线配置示例

下面是一条典型的“编译-测试-构建镜像-部署”流水线，覆盖Java后端场景：

stages:
  - build
  - test
  - package
  - deploy

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2"
  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .m2/

compile:
  stage: build
  image: maven:3.9-eclipse-temurin-17
  script:
    - mvn compile -q

unit-test:
  stage: test
  image: maven:3.9-eclipse-temurin-17
  script:
    - mvn test -q
  artifacts:
    paths:
      - target/surefire-reports/
    when: always

build-image:
  stage: package
  image: docker:26
  services:
    - docker:26-dind
  variables:
    DOCKER_HOST: tcp://docker:2375
  before_script:
    - echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY
  script:
    - docker build -t $IMAGE_TAG .
    - docker push $IMAGE_TAG

deploy-prod:
  stage: deploy
  image: alpine:3.20
  only:
    - main
  environment:
    name: production
    url: https://www.yunthe.com
  before_script:
    - apk add --no-cache openssh-client
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | ssh-add -
  script:
    - ssh -o StrictHostKeyChecking=no deploy@10.0.0.5 "docker pull $IMAGE_TAG && docker-compose up -d"

把上面内容提交到仓库后，GitLab会在每次push时自动运行流水线。构建镜像的Job依赖Docker-in-Docker服务，注册Runner时需注意配置。

3. 分支策略与流水线触发规则

开发分支与主分支应当走不同的流水线。用rules规则替代旧only/except，粒度更细：

deploy-staging:
  stage: deploy
  script: ./deploy-staging.sh
  rules:
    - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'
    - if: '$CI_COMMIT_BRANCH == \"develop\"'

deploy-production:
  stage: deploy
  script: ./deploy-prod.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == \"main\"'
      when: manual   # 需要人工确认
  environment:
    name: production

生产部署建议加when: manual人工确认，避免误推主干直接把未验证代码带到线上。合并请求流水线（Merge Request Pipeline）可以在代码合并前跑完测试，比在主干上跑更早发现问题。

4. 缓存与产物：加速CI流水线的两个手段

缓存（cache）把依赖目录保留在Runner本地或分布式存储中，避免每次从中央仓库重新拉包，适合包管理器目录。产物（artifacts）把Job生成的测试报告、JAR包传递给后续Job或供下载，只保留需要的文件并设置过期时间，避免垃圾堆积。测试报告与覆盖率报告都通过artifacts上传，GitLab在MR页面直接展示覆盖率与失败用例。

5. 流水线常见问题：Runner离线与Job超时

Runner离线是最常见的问题：先看Runner注册token是否失效，再用gitlab-runner verify确认连接；如果Runner挂载了旧镜像，gitlab-runner restart清掉残留容器。Job超时主要来自Docker build拉取大镜像或测试用例运行过久，可在顶层配置timeout限制，也可以在build脚本里对慢步骤加超时。Runner标签（tag）只让特定Runner执行敏感任务（如生产部署），没加标签的Runner会漏掉带tag的Job，注意检查。

GitLab CI/CD的核心价值是把“提交-构建-测试-发布”全流程编码化。先把流水线跑通再逐步加上分支策略、人工确认、失败通知，配合监控告警体系与日志分析，整套自动化发布链路就完整了。