GitLab CI/CD流水线搭建实战：Runner注册到多阶段部署全流程

CI/CD流水线从GitLab Runner开始

GitLab自带的CI/CD能力把代码提交、构建、测试、部署全部编排进一条流水线，配置放在仓库里的.gitlab-ci.yml，随代码走、天然可评审可追溯。落地CI/CD第一步是准备好执行构建任务的Runner。Runner是独立于GitLab的进程，可以共享的服务器上，注册到项目或分组后，流水线的每个Job都会派给Runner执行。

安装并注册GitLab Runner

使用Docker方式安装Runner最简单：

docker run -d --name gitlab-runner --restart always   -v /srv/gitlab-runner/config:/etc/gitlab-runner   -v /var/run/docker.sock:/var/run/docker.sock   gitlab/gitlab-runner:latest

注册Runner需要GitLab项目地址和注册令牌，项目设置->CI/CD->Runner里获取：

docker exec -it gitlab-runner gitlab-runner register   --url https://gitlab.example.com   --token glrt-xxxxxxx   --executor docker   --docker-image node:20-alpine

Runner支持shell、docker、kubernetes等执行器，docker执行器每次Job拉取独立镜像，环境隔离干净，推荐。

编写.gitlab-ci.yml：多阶段流水线编排

流水线由stages和jobs组成，同一stage的job并行执行，不同stage按顺序执行。一套典型的前后端部署流水线：

stages:
  - build
  - test
  - deploy

variables:
  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

build-job:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $IMAGE_TAG .
    - docker push $IMAGE_TAG
  only:
    - main

test-job:
  stage: test
  image: node:20-alpine
  script:
    - npm ci
    - npm run test
  needs: ["build-job"]
  only:
    - main

deploy-job:
  stage: deploy
  image: alpine
  script:
    - apk add --no-cache openssh-client
    - ssh -o StrictHostKeyChecking=no deploy@$SERVER_IP         "docker pull $IMAGE_TAG && docker-compose up -d"
  environment: production
  only:
    - main
  when: manual

三个关键点：制品版本号用CI_COMMIT_SHORT_SHA，保证每个提交对应唯一镜像，避免部署错版本；部署步骤用when: manual做成手动触发，防止不确认直接上线；敏感信息通过项目的CI/CD变量配置，写进yml等于泄露。

流水线优化：缓存、制品与失败重试

每次Job都重新拉依赖会非常慢，用cache缓存公共依赖目录：

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - node_modules/

构建产物要传给后面的Job用artifacts字段打包，比如测试报告、dist目录，否则下一个Job环境是全新的拿不到。

生产环境出错不要慌，Job失败后点Rerun即可重试；日志里看到Runner not found大概率是Runner注册令牌过期或执行器镜像下载失败。常见报错还有docker命令没权限，确认Runner用了docker executor且挂载了docker.sock。

用CI/CD把变更风险降低

一条完整的流水线意味着每次变更都经过构建、测试、部署三个门禁，人在哪里通过合并请求介入，机器在哪执行重复劳动。从一个小项目开始跑通，再逐步加测试、静态扫描、生产环境手动确认，是多数团队落地DevOps实践比较稳的路径。