Ubuntu 上 GitLab CI/CD 集成实操指南
一 架构与前置条件
- 组件分工：代码托管与流水线编排由 GitLab 提供，实际作业在 GitLab Runner 上执行；Runner 需注册到你的 GitLab 实例（项目级或实例级），并在 Ubuntu 18.04/20.04/22.04 等环境安装。Runner 支持多种 Executor（如 Docker、Shell），Docker 更利于可移植与隔离。
- 基本准备：一个可访问的 GitLab 项目（自托管或 gitlab.com）、一台 Ubuntu 服务器（建议 ≥2 CPU、≥4 GB 内存）、具备 sudo 权限的用户、若使用容器化需安装 Docker Engine。
二 安装并注册 GitLab Runner
- 安装 Runner（Ubuntu 推荐方式）
- 更新索引并安装依赖：sudo apt-get update && sudo apt-get install -y curl ca-certificates
- 添加 Runner 官方仓库并安装：
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt-get install -y gitlab-runner
- 注册 Runner：
- 在项目的 Settings > CI/CD > Runners 获取 URL 与 Registration token。
- 执行注册：sudo gitlab-runner register，按提示依次输入 URL、token、Runner 描述、tags（可选）、选择 Executor（如 docker 或 shell）。
- 若选择 Docker Executor，请确保本机已安装并运行 Docker Engine。
- 常用运维：
- 查看状态：sudo gitlab-runner status
- 重启：sudo gitlab-runner restart
- 注册为系统服务后会随系统启动（安装过程通常会自动注册）。
三 编写 .gitlab-ci.yml 与变量管理
-
基本结构与示例
-
在项目根目录创建 .gitlab-ci.yml，定义 stages 与 jobs，提交后自动触发流水线。
-
示例（Node.js + Docker 构建与部署，使用 GitLab 容器注册表）：
stages:
variables:
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
build_job:
stage: build
image: node:18
script:
- npm ci
- npm run build --if-present
artifacts:
paths:
- dist/
test_job:
stage: test
image: node:18
script:
- npm test – --ci
deploy_job:
stage: deploy
image: docker:24.0
services:
- docker:24.0-dind
variables:
DOCKER_HOST: tcp://docker:2375
DOCKER_TLS_CERTDIR: “”
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
# 如需 SSH 部署到目标服务器，可在本机准备 SSH 私钥为 CI 变量，再用 ssh 执行远程命令
only:
- main
-
要点说明：
- 使用 artifacts 在作业间传递产物（如上例的 dist/）。
- 使用 only/except 或 rules 控制分支触发策略（如仅 main 分支执行部署）。
- 使用 services: docker:dind 可在 CI 内运行 Docker（注意网络与性能配置）。
-
变量与密钥
- 在 Settings > CI/CD > Variables 添加变量（如 CI_REGISTRY_USER、CI_REGISTRY_PASSWORD、SSH_PRIVATE_KEY），勾选 Masked（必要时勾选 Protected）。
- 在作业中使用 $VAR 或 ${VAR} 引用；不建议在 YAML 中明文存放密钥。
四 触发流水线并查看结果
- 推送代码（git push）或创建 Merge Request 时，GitLab 会自动检测 .gitlab-ci.yml 并触发流水线。
- 在项目的 CI/CD > Pipelines 查看运行状态、作业日志与耗时；失败可在具体作业日志中定位问题并迭代修复。
五 常见问题与最佳实践
- Runner 与权限
- 选择合适的 Executor：Docker 更通用、环境一致；Shell 适合本机直连场景但可移植性差。
- Runner 运行用户与目录权限需正确配置，避免因权限不足导致拉取代码或执行脚本失败。
- 构建与缓存
- 合理使用 cache/artifacts 减少重复下载与构建时间（如 node_modules、maven 本地仓库、Docker 层缓存）。
- Docker 构建建议固定基础镜像版本，减少“漂移”。
- 部署安全
- 生产部署建议限定分支（如 only: main）、使用 Protected 变量与 Masked 密钥。
- 通过 SSH 部署 时，使用临时密钥或跳板机，避免长期密钥泄露；必要时在目标机限制该密钥的权限（仅允许特定目录与命令）。
- 可观测与优化
- 在 Pipelines 与 Jobs 页面持续观察日志与耗时，按需拆分或并行化作业；定期更新 Runner 与依赖以获得性能与安全性修复。
