GitLab 完整学习笔记

第一部分：GitLab 基本配置与使用

我这里使用的是docker创建容器来实现服务

复制代码

docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/gitlab/gitlab-ce:17.0.0-ce.0
docker tag  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/gitlab/gitlab-ce:17.0.0-ce.0  docker.io/gitlab/gitlab-ce:17.0.0-ce.0



docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/gitlab/gitlab-runner:v17.0.0
docker tag  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/gitlab/gitlab-runner:v17.0.0  docker.io/gitlab/gitlab-runner:v17.0.0

一、GitLab 部署后必做的 6 件事

1. 获取 root 用户初始密码

GitLab 首次启动后，会生成一个临时密码，存放在容器/服务内的一个文件里。

普通安装方式（apt/yum/rpm 安装）：

复制代码

cat /etc/gitlab/initial_root_password | grep Password

Kubernetes 部署方式：

复制代码

kubectl exec -it -n gitlab gitlab-645b7cccf-xwg7s -- bash
root@gitlab-645b7cccf-xwg7s:/# cat /etc/gitlab/initial_root_password | grep Password

输出示例：

复制代码

Password: BwoXKC3qGABwhtLOFERuMzA4ZK+baSr9NRKhDIwI3Xo=

易错点：

这个密码文件在 24 小时后会被 GitLab 自动删除。
如果超过 24 小时再去看这个文件，会发现文件不存在。
如果密码文件过期，需要用命令行重置密码：

进入 GitLab 容器/服务

kubectl exec -it -n gitlab gitlab-645b7cccf-xwg7s -- bash

执行重置密码命令

gitlab-rake "gitlab:password:reset[root]"
复制密码时注意不要带空格或换行符，否则登录会失败。

2. 修改 root 密码

使用临时密码登录后，修改密码：

复制代码

Admin Area → Overview → Users → Edit → 修改密码

易错点：

root 用户本身就存在，不用创建。
修改后记住新密码，临时密码后续无法再使用。

3. 把 GitLab 界面切换为中文

复制代码

点击右上角头像 → Preferences → Localization → 将 Language 改为中文 → 保存 → 刷新页面

易错点：

改完语言后必须要刷新页面才能生效。
只有登录后才有 Preferences 入口。

4. 解决头像不显示问题

**原因：** GitLab 默认使用 Gravatar 头像服务，而 Gravatar 在国内无法访问，导致头像空白。

**解决方法：** 修改 GitLab 配置文件，把头像 URL 改成国内可访问的镜像地址。

普通安装方式：

复制代码

vim /etc/gitlab/gitlab.rb

Kubernetes 部署方式：

复制代码

kubectl exec -it -n gitlab gitlab-645b7cccf-xwg7s -- bash
root@gitlab-645b7cccf-xwg7s:/# vi /etc/gitlab/gitlab.rb

修改内容：

复制代码

# 注释掉原来的配置
# gitlab_rails['gravatar_plain_url'] = 'http://www.gravatar.com/avatar/%{hash}?s=%{size}&d=identicon'
# gitlab_rails['gravatar_ssl_url'] = 'https://secure.gravatar.com/avatar/%{hash}?s=%{size}&d=identicon'

# 改成国内镜像
gitlab_rails['gravatar_plain_url'] = 'http://gravatar.loli.net/avatar/%{hash}?s=%{size}&d=identicon'
gitlab_rails['gravatar_ssl_url'] = 'https://gravatar.loli.net/avatar/%{hash}?s=%{size}&d=identicon'

配置完成后重载配置并重启：

复制代码

gitlab-ctl reconfigure
gitlab-ctl restart

5. git clone 地址不正确问题

**原因：** GitLab 安装后，项目显示/使用的地址可能不是实际可访问的域名，需要手动指定。

修改 /etc/gitlab/gitlab.rb 中的 external_url：

复制代码

external_url 'http://gitlab.local.com'

然后：

复制代码

gitlab-ctl reconfigure
gitlab-ctl restart

易错点：

这个地址会影响项目 clone 地址、注册 Runner 的地址、CI 拉取代码的地址。
如果配置了域名，确保其他机器能通过 hosts/DNS 解析到这个域名。

6. GitLab 配置参考文档

官方配置模板参考：

复制代码

https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-gitlab-config-template/gitlab.rb.template

二、GitLab 常用命令

命令	作用
`gitlab-ctl tail`	查看详细日志信息
`gitlab-ctl status`	检查各组件运行状态
`vim /etc/gitlab/gitlab.rb`	修改默认配置文件
`gitlab-ctl reconfigure`	重载配置
`gitlab-ctl start`	启动所有 GitLab 组件
`gitlab-ctl stop`	停止所有 GitLab 组件
`gitlab-ctl restart`	重启所有 GitLab 组件
`gitlab-rake gitlab:check SANITIZE=true --trace`	检查 GitLab 是否正常

三、GitLab 权限体系

1. 组、用户、项目的关系

GitLab 的权限管理核心是通过 **组（Group）** 来组织：

复制代码

一个组下面可以有多个项目
一个组下面可以有多个用户
组里的用户对组内所有项目有相同权限

流程：

复制代码

创建组 → 创建项目并归到组 → 创建用户 → 把用户加入组并分配角色

2. 三种可见性级别（组和项目都适用）

类型	谁能看到/访问
Private（私有）	只有组/项目成员才能看到
Internal（内部）	只要登录 GitLab 的用户都能看到
Public（公开）	所有人（包括未登录）都能看到，可以 clone

权限验证结论（通过实验总结）：

用户类型	能看到哪些项目
普通用户（张三，属于私有组）	自己组项目 + 内部项目 + 公开项目
普通用户（李四，属于内部组）	自己组项目 + 内部项目（看不到其他私有组）
管理员用户（王五）	所有项目（私有/内部/公开都能看到）
未登录用户	只能看到/访问公开项目

3. 用户类型

类型	作用
Regular（普通用户）	只能访问属于他的组和项目
Admin（管理员）	可以访问所有组和项目，可管理全站

4. 组内 5 种角色权限

角色	权限
Guest（访客）	可以创建 issue、发表评论，不能读写代码仓库
Reporter（报告者）	可以克隆代码，不能提交，适合 QA、PM
Developer（开发者）	可以克隆、开发、提交、push，普通开发人员
Maintainer（维护者）	可以创建项目、添加 tag、保护分支、添加成员、编辑项目，核心开发人员
Owner（所有者）	可以设置项目可见性、删除/迁移项目、管理组成员，管理人员

5. 实战操作步骤总结

创建组

复制代码

管理员登录 → 群组 → 新建群组 → 填写组名 → 选择可见性 → 创建

创建项目并归到组

复制代码

进入组 → 新建项目 → 填写项目名 → 选择可见性 → 创建

创建用户

复制代码

Admin Area → Overview → Users → 新建用户 → 填写信息 → 创建 → 设置初始密码

把用户添加进组

复制代码

进入组 → Manage → Members → 输入用户名/邮箱 → 选择角色 → 邀请

四、GitLab 监控（Metrics）

1. 启用监控

修改 gitlab.rb：

复制代码

gitlab_exporter['enable'] = true
gitlab_exporter['listen_address'] = '0.0.0.0'
gitlab_exporter['listen_port'] = '9168'

然后：

复制代码

gitlab-ctl reconfigure
gitlab-ctl restart

2. 暴露端口（K8s 环境）

K8s Service 需要增加一个端口：

复制代码

ports:
  - port: 9168
    targetPort: 9168
    name: gitlab-exporter

3. 访问验证

复制代码

curl gitlab.cicd.svc:9168/metrics

返回一堆指标数据即成功。

第二部分：GitLab Runner 全面解析（第13章）

一、Runner 是什么？

GitLab Runner 是一个开源项目 ，用来运行 GitLab CI/CD 的作业任务，并把结果返回给 GitLab。

可以把它理解成 Jenkins 的 agent/slave。

关键特点：

特点	说明
语言	Go 编写
跨平台	Linux / Windows / macOS
版本要求	应该和 GitLab 版本保持一致
数量	可以配置任意数量 Runner
运行作业	同时执行多个作业

二、Runner 类型

类型	作用范围
Shared（实例共享）	运行整个 GitLab 平台上所有项目的作业
Group（群组）	运行某一个群组下所有项目的作业
Specific（项目）	只运行指定项目的作业

选择建议：

公司统一 CI 基础设施，用 Shared。
某个团队独享，用 Group。
某个项目特殊需求，用 Specific。

三、Runner 状态

状态	含义
locked（锁定）	不能运行项目作业
paused（已暂停）	暂时不接受新作业

四、Runner 工作流程

复制代码

开发 push 代码
       ↓
GitLab 触发 Pipeline
       ↓
GitLab 检查可用 Runner
       ↓
Runner 接收 Job
       ↓
Runner 按执行器创建执行环境（shell / docker / k8s pod）
       ↓
Runner 拉取代码
       ↓
执行 CI 配置中的 script 命令
       ↓
把结果（日志/状态/制品）返回 GitLab
       ↓
GitLab 更新 Pipeline/Job 状态

五、Runner 安装方式

方式一：rpm/dnf 安装

复制代码

# 下载对应版本
curl -L -o gitlab-runner-17.0.0-1.x86_64.rpm \
  https://mirrors.tuna.tsinghua.edu.cn/gitlab-runner/yum/el9-x86_64/gitlab-runner-17.0.0-1.x86_64.rpm

# 安装
dnf install -y gitlab-runner-17.0.0-1.x86_64.rpm

# 开机自启
systemctl enable --now gitlab-runner

# 把 gitlab-runner 用户加入 docker 组（如果要用 docker 执行器）
usermod -aG docker gitlab-runner

易错点：

版本要和 GitLab 主版本一致，例如 GitLab 16.10 → Runner 16.10.x。
安装完要确认服务状态：

gitlab-runner status

方式二：Docker 安装

复制代码

docker run --name gitlab-runner -itd \
  -v /opt/docker/gitlab-runner:/etc/gitlab-runner \
  --restart always \
  gitlab/gitlab-runner:v16.10.0

易错点：

容器挂了以后配置会自动重启。
配置文件挂在宿主机，删除容器再启动配置还在。

六、Runner 注册

1. 获取注册 Token

不同类型 Runner 获取位置不同：

类型	路径
Shared	管理中心 → CI/CD → Runner → 新建实例 Runner
Group	群组 → 设置 → CI/CD → Runner → 新建群组 Runner
Specific	项目 → 设置 → CI/CD → Runner → 新建项目 Runner

2. 交互式注册（shell 执行器）

复制代码

gitlab-runner register \
  --url http://192.168.10.72 \
  --token glrt-sx_xdrgZF7sHn1-5u5rz

然后根据提示输入：

复制代码

Enter the GitLab instance URL: 回车（默认已带）
Enter a name for the runner: 自定义名称
Enter an executor: shell

成功提示：

复制代码

Runner registered successfully.

3. 非交互式注册（Docker 容器方式）

复制代码

docker exec -it gitlab-runner gitlab-runner register \
  --non-interactive \
  --executor "shell" \
  --url "http://192.168.10.72" \
  --token "glrt-sewzG59GqdxshPisQkFo"

4. 注册 Docker 类型执行器

复制代码

docker exec -it gitlab-runner gitlab-runner register \
  --non-interactive \
  --executor "docker" \
  --url "http://192.168.10.72" \
  --token "glrt-JHbwfcKH4PZye2z6d6NT" \
  --docker-image alpine:latest \
  --docker-privileged

5. Runner 常见注册报错与解决

报错	原因	解决
`Could not resolve host: gitlab.test.com`	Runner 机器/容器无法解析 GitLab 域名	在 Runner 机器或容器加 hosts：`echo "192.168.10.72 gitlab.test.com" >> /etc/hosts`
`verifying runner... is valid` 但作业不跑	标签不匹配	在 CI 文件里加 `tags:` 匹配 Runner 标签
Job 一直 pending	Runner 不在线 / 被 paused / 没有可用 Runner	检查 Runner 状态和标签
`chosen stage does not exist`	作业的 `stage` 不在 `stages` 列表中	检查 `stage` 拼写和 `stages` 定义

七、Runner 配置文件 `config.toml` 详解

默认路径：

复制代码

/etc/gitlab-runner/config.toml

concurrent = 10          # 并行执行作业数
check_interval = 0

[[runners]]
name = "client2"
url = "http://192.168.10.72"
token = "glrt-xxx"
executor = "docker"

[runners.docker]
image = "alpine:latest"          # 默认镜像
pull_policy = "if-not-present"   # 镜像拉取策略
privileged = true                # 特权模式
volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]

八、Runner 执行器对比

最常用三种：

执行器	特点
Shell	直接在本机执行命令，简单但环境可能被污染
Docker	每个作业在独立容器里执行，环境隔离最常用
Kubernetes	每个作业动态创建 K8s Pod，适合云原生环境

九、Runner 的 K8s 部署（重点）

1. 执行过程

复制代码

Runner 通过 RBAC 权限访问 K8s API
       ↓
GitLab 有 job 时，Runner 获取任务
       ↓
Runner 调用 K8s API 创建 Pod
       ↓
Pod 中运行该 job 的 script
       ↓
完成后自动删除临时 Pod

2. 核心资源清单

创建 Secret（保存 kubeconfig）

复制代码

kubectl create secret generic -n cicd kube-config \
  --from-file=/root/.kube/config

kubectl create secret generic -n cicd kube-ca \
  --from-file=/etc/kubernetes/pki/ca.crt

创建 RBAC

复制代码

apiVersion: v1
kind: ServiceAccount
metadata:
  name: gitlab-runner-admin
  namespace: cicd
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: cicd
  name: gitlab-admin
rules:
  - apiGroups: [""]
    resources: ["*"]
    verbs: ["*"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gitlab-admin
  namespace: cicd
subjects:
  - kind: ServiceAccount
    name: gitlab-runner-admin
    namespace: cicd
roleRef:
  kind: Role
  name: gitlab-admin
  apiGroup: rbac.authorization.k8s.io

创建 ConfigMap（Runner 配置模板）

复制代码

apiVersion: v1
kind: ConfigMap
metadata:
  name: gitlab-runner-config
  namespace: cicd
data:
  group_runner_executor: "kubernetes"
  group_runner_url: "http://gitlab.cicd.svc"
  group_runner_token: "glrt-xxx"
  config-template.toml: |-
    [[runners]]
    [runners.kubernetes]
    image = "alpine:latest"
    pull_policy = "if-not-present"
    namespace = "cicd"
    privileged = true
    [[runners.kubernetes.host_aliases]]
    ip = "192.168.10.150"
    hostnames = ["gitlab.local.com"]

创建 Deployment

复制代码

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitlab-runner
  namespace: cicd
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gitlab-runner
  template:
    metadata:
      labels:
        app: gitlab-runner
    spec:
      serviceAccountName: gitlab-runner-admin
      containers:
        - name: gitlab-runner
          image: harbor.local.com/cicd/gitlab-runner:v17.2.0
          env:
            - name: GROUP_RUNNER_TOKEN
              valueFrom:
                configMapKeyRef:
                  name: gitlab-runner-config
                  key: group_runner_token
            - name: GROUP_RUNNER_URL
              valueFrom:
                configMapKeyRef:
                  name: gitlab-runner-config
                  key: group_runner_url
            - name: GROUP_RUNNER_EXECUTOR
              valueFrom:
                configMapKeyRef:
                  name: gitlab-runner-config
                  key: group_runner_executor
          lifecycle:
            postStart:
              exec:
                command: ["/bin/sh", "-c", "sh /tmp/register.sh"]

十、Runner 缓存优化

问题场景

Kubernetes 执行器每次 job 结束后 Pod 销毁，导致：

Maven 依赖每次重新下载
target 目录丢失
制品无法跨 job 使用

解决方案

方案一：使用 MinIO/S3 对象存储做分布式缓存

复制代码

[runners.cache]
Type = "s3"
Shared = false

[runners.cache.s3]
ServerAddress = "minio-service.minio.svc:9000"
AccessKey = "xxx"
SecretKey = "xxx"
BucketName = "gitlab-runner-cache"
Insecure = true

方案二：使用 PVC 持久化缓存

创建 PVC：

复制代码

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gitlab-runner-cache
  namespace: cicd
spec:
  storageClassName: nfs-client
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi

挂载到 Runner Deployment：

复制代码

volumeMounts:
  - name: cache
    mountPath: /home/gitlab-runner/cache
volumes:
  - name: cache
    persistentVolumeClaim:
      claimName: gitlab-runner-cache

在 CI 中指定缓存目录：

复制代码

mvn clean package -Dmaven.repo.local=/home/gitlab-runner/cache/maven

十一、Runner 监控

启用 metrics

在 config.toml 顶部添加：

复制代码

listen_address = ":9252"

创建 Service

复制代码

apiVersion: v1
kind: Service
metadata:
  name: gitlab-runner
  namespace: cicd
spec:
  selector:
    app: gitlab-runner
  ports:
    - port: 9252
      targetPort: 9252
      name: gitlab-runner-exporter

验证

复制代码

curl gitlab-runner.cicd.svc:9252/metrics

第三部分：GitLab 流水线完整语法（第14章）

一、Pipeline 流程

复制代码

提交 .gitlab-ci.yml
         ↓
GitLab 触发 Pipeline
         ↓
按 stages 顺序执行
         ↓
每个 stage 里可以并行多个 job
         ↓
全部成功 → Pipeline 通过
任何一个失败 → Pipeline 失败

二、核心关键字详解

1. `stages`

定义阶段顺序：

复制代码

stages:
  - build
  - test
  - deploy

执行顺序：

复制代码

build → test → deploy

未定义 stages 时： 默认阶段是 build、test、deploy。

一个 job 未指定 stage 时： 默认是 test。

2. `.pre` 和 `.post`

复制代码

.pre   → 永远第一个执行
.post  → 永远最后一个执行

特点：

不需要在 stages 里声明。
不管 stages 怎么排序，.pre 最先，.post 最后。
如果 Pipeline 里只有 .pre 或 .post 的 job，Pipeline 不会创建。

3. `script`

每个 job 必须有的命令列表：

复制代码

job:
  script:
    - echo "hello"
    - ls -la

易错点：

命令里有冒号 : 时必须用引号包起来：

script:
- echo "http://example.com"
特殊字符（; { } [ ] , & * # ? | < > = ! % @）建议都加引号。

4. `before_script` 和 `after_script`

复制代码

default:
  before_script:
    - echo "before"
  after_script:
    - echo "after"

build:
  stage: build
  script:
    - echo "build"

执行顺序：

复制代码

before_script → script → after_script

易错点：

before_script 失败 → 整个 job 失败。
after_script 失败 → 不影响 job 结果。
job 里可以覆盖全局定义。

5. `variables`

复制代码

variables:
  NAME: zhangsan
  AGE: 18

build:
  script:
    - echo "hello $NAME"

变量优先级：

复制代码

job 变量 > pipeline 变量 > Runner 变量 > 全局变量

6. `tags`

指定使用哪个 Runner：

复制代码

job:
  tags:
    - docker
    - shared

易错点：

如果 Runner 有标签，CI 必须匹配标签，否则作业一直 pending。
如果 Runner 设置了"运行未打标签的作业"，则不带 tags 也能跑。

7. `allow_failure`

允许作业失败但不阻塞流水线：

复制代码

test:
  script:
    - execute_script_that_will_fail
  allow_failure: true

效果：

作业失败显示橙色警告。
不影响整个 Pipeline 的成功/失败状态。

8. `when`

值	含义
`on_success`	前面阶段全部成功后执行（默认）
`on_failure`	前面阶段有失败时执行
`always`	不管前面成功失败都执行
`manual`	手动点击执行
`delayed`	延迟指定时间后执行
`never`	不创建这个作业

复制代码

deploy:
  stage: deploy
  when: manual

9. `retry`

失败后自动重试：

复制代码

deploy:
  script:
    - echo "deploy"
  retry:
    max: 2
    when: script_failure

10. `timeout`

作业超时时间：

复制代码

build:
  script: build.sh
  timeout: 3 hours 30 minutes

优先级：

复制代码

Runner 超时 < 项目超时 < job 超时

11. `parallel`

同一个 job 并行跑 N 个实例：

复制代码

codescan:
  script: echo "scan"
  parallel: 5

生成：

复制代码

codescan 1/5
codescan 2/5
...
codescan 5/5

三、条件分支

1. `rules`

按顺序匹配，匹配到就停止：

复制代码

codescan:
  stage: codescan
  script:
    - echo "codescan"
  rules:
    - if: '$DOMAIN == "example.com"'
      when: manual
    - when: on_success

2. `rules:changes`

根据文件是否变化：

复制代码

job:
  script: echo "changed"
  rules:
    - changes:
        - Dockerfile
      when: manual
    - when: on_success

3. `rules:exists`

根据仓库中是否存在某文件：

复制代码

job:
  script: echo "exists"
  rules:
    - exists:
        - Dockerfile
      when: manual

4. `workflow:rules`

控制整个 Pipeline 是否创建：

复制代码

workflow:
  rules:
    - if: '$DOMAIN == "example.com"'
      when: always
    - when: never

5. `only` / `except`

简单版条件控制，但不能和 rules 混用：

复制代码

job1:
  script: echo "test"
  only:
    - /^feature-.*$/

job2:
  script: echo "master"
  only:
    - master

四、缓存 `cache`

作用

跨 job 共享文件，例如 Maven 依赖、npm 缓存等。

基本用法

复制代码

cache:
  key: build
  paths:
    - target/

按分支做不同缓存：

复制代码

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - target/

按文件变化自动换缓存：

复制代码

cache:
  key:
    files:
      - pom.xml
  paths:
    - target/

缓存策略

策略	行为
`pull-push`（默认）	开始下载缓存，结束上传缓存
`pull`	只下载，不上传
`push`	只上传，不下载

复制代码

build:
  cache:
    policy: pull

五、制品 `artifacts`

作用

跨 job 传递文件，例如编译好的 jar 包。

复制代码

build:
  stage: build
  script:
    - mvn clean package
  artifacts:
    paths:
      - target/*.jar
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    when: on_success
    expire_in: 1 week

六、阶段并行 `needs`

默认必须等前面阶段的 job 全部完成才能继续。

使用 needs 可以提前触发：

复制代码

stages:
  - build
  - test

build1:
  stage: build
  script: echo "build1"

build2:
  stage: build
  script: echo "build2"

test1:
  stage: test
  needs: ["build1"]
  script: echo "test1"

test2:
  stage: test
  needs: ["build2"]
  script: echo "test2"

七、引用其他 CI 文件

1. `include:local`

引入同仓库文件：

复制代码

include:
  - local: 'ci/localci.yml'

2. `include:file`

引入其他项目文件：

复制代码

include:
  - project: 'develop/vue3_vite_element-plus'
    ref: master
    file: '.gitlab-ci.yml'

3. `include:remote`

引入远程 URL：

复制代码

include:
  - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'

八、管道触发 `trigger`

多项目管道

复制代码

staging:
  stage: deploy
  trigger:
    project: develop/vue3_vite_element-plus
    branch: master

父子管道（传递变量）

复制代码

staging2:
  stage: deploy
  trigger:
    include: 'ci/part1.yml'
    strategy: depend

九、容器相关

指定 job 使用的 Docker 镜像：

复制代码

build:
  stage: build
  image: maven:3.9.3
  script:
    - mvn clean package

给 job 提供额外服务容器：

复制代码

test:
  stage: test
  image: alpine:latest
  services:
    - redis:latest
  script:
    - echo "test redis"

十、环境 `environment`

复制代码

deploy to production:
  stage: deploy
  script:
    - echo "deploy"
  environment:
    name: production
    url: https://www.baidu.com

作用：

在 GitLab 页面记录部署历史
支持环境部署保护等

总结：三种环境部署 Runner 对比

部署方式	适合场景	优点	缺点
rpm/systemd	单机简单测试	简单直接	环境不隔离
Docker	中小型项目	隔离好，部署快	需要管理容器
Kubernetes	云原生/规模化	弹性伸缩、资源好管	复杂度高

四、易错点汇总表

易错点	原因	正确做法
Root 密码文件 24h 后消失	GitLab 自动删除	登录后立即改密码
头像不显示	Gravatar 被墙	改国内镜像地址
Runner 版本和 GitLab 不一致	版本不匹配	安装相同大版本
Job 一直 pending	标签不匹配 / Runner 离线	检查 tags 和 Runner 状态
`Could not resolve host: gitlab.test.com`	Runner 无法解析 GitLab 域名	在 Runner 上配置 hosts
`chosen stage does not exist`	stage 拼写错误/未定义	检查 `stage` 和 `stages`
`before_script` 失败	环境准备失败	修复前置命令
`after_script` 失败	不影响 job	不用紧张，但最好修复
缓存被覆盖	多个 job 使用同一 cache key	每个 job 设置不同 `cache:key`
制品跨 job 丢失	没有配置 artifacts	用 `artifacts.paths` 传递
K8s Runner 无法访问集群	没有 RBAC 权限	创建 ServiceAccount + Role + RoleBinding
K8s job 之间缓存丢失	Pod 销毁	配置 PVC / MinIO 分布式缓存

五、整体 CI/CD 工作流程图

复制代码

开发者 push 代码
       ↓
GitLab 触发 Pipeline
       ↓
Runner 获取 Job
       ↓
Shell/Docker/K8s 创建执行环境
       ↓
拉取代码
       ↓
before_script（可选）
       ↓
script（多个命令按顺序执行）
       ↓
after_script（可选，失败不影响）
       ↓
收集 artifacts / 更新 cache
       ↓
返回状态给 GitLab
       ↓
进入下一个 stage / 完成 Pipeline

GitLab 完整学习笔记

第一部分：GitLab 基本配置与使用

一、GitLab 部署后必做的 6 件事

1. 获取 root 用户初始密码

进入 GitLab 容器/服务

执行重置密码命令

2. 修改 root 密码

3. 把 GitLab 界面切换为中文

4. 解决头像不显示问题

5. git clone 地址不正确问题

6. GitLab 配置参考文档

二、GitLab 常用命令

三、GitLab 权限体系

1. 组、用户、项目的关系

2. 三种可见性级别（组和项目都适用）

3. 用户类型

4. 组内 5 种角色权限

5. 实战操作步骤总结

创建组

创建项目并归到组

创建用户

把用户添加进组

四、GitLab 监控（Metrics）

1. 启用监控

2. 暴露端口（K8s 环境）

3. 访问验证

第二部分：GitLab Runner 全面解析（第13章）

一、Runner 是什么？

二、Runner 类型

三、Runner 状态

四、Runner 工作流程

五、Runner 安装方式

方式一：rpm/dnf 安装

方式二：Docker 安装

六、Runner 注册

1. 获取注册 Token

2. 交互式注册（shell 执行器）

3. 非交互式注册（Docker 容器方式）

4. 注册 Docker 类型执行器

5. Runner 常见注册报错与解决

七、Runner 配置文件 config.toml 详解

八、Runner 执行器对比

九、Runner 的 K8s 部署（重点）

1. 执行过程

2. 核心资源清单

创建 Secret（保存 kubeconfig）

创建 RBAC

创建 ConfigMap（Runner 配置模板）

创建 Deployment

十、Runner 缓存优化

问题场景

解决方案

方案一：使用 MinIO/S3 对象存储做分布式缓存

方案二：使用 PVC 持久化缓存

十一、Runner 监控

启用 metrics

创建 Service

验证

第三部分：GitLab 流水线完整语法（第14章）

一、Pipeline 流程

二、核心关键字详解

1. stages

2. .pre 和 .post

3. script

4. before_script 和 after_script

5. variables

6. tags

7. allow_failure

8. when

9. retry

10. timeout

11. parallel

三、条件分支

1. rules

2. rules:changes

3. rules:exists

4. workflow:rules

5. only / except

四、缓存 cache

作用

七、Runner 配置文件 `config.toml` 详解

1. `stages`

2. `.pre` 和 `.post`

3. `script`

4. `before_script` 和 `after_script`

5. `variables`

6. `tags`

7. `allow_failure`

8. `when`

9. `retry`

10. `timeout`

11. `parallel`

1. `rules`

2. `rules:changes`

3. `rules:exists`

4. `workflow:rules`

5. `only` / `except`

四、缓存 `cache`

五、制品 `artifacts`

六、阶段并行 `needs`

1. `include:local`

2. `include:file`

3. `include:remote`

八、管道触发 `trigger`

十、环境 `environment`