GitLab 基础教程

下面是一份超完整、可实践、结构清晰的 GitLab 教程，涵盖从核心概念、安装部署、用户与权限、CI/CD、Runner、项目管理、Hook、运维、备份恢复、安全加固、最佳实践等内容。

GitLab 是什么？核心功能概述
GitLab 架构与核心组件
GitLab 安装部署（单机、Docker、K8s、HA）
基础使用教程（用户、项目、组、权限）
GitLab CI/CD 完整教程
GitLab Runner 使用教程
GitLab 常用功能（Issue、MR、Webhook、API）
GitLab 运维与管理（备份、恢复、升级）
GitLab 性能调优
GitLab 安全加固
GitLab 最佳实践（企业级）

1. GitLab 是什么？

GitLab = 代码托管 + CI/CD + DevOps 平台

主要模块：

Git 仓库管理
Merge Request（代码评审）
Issue / 任务管理 / 看板
CI/CD Pipeline
Runner 执行器
依赖仓库（Registry、Package、Container Registry）
权限管理（用户/组/项目）

GitLab = GitHub 的自建替代品，但比 GitHub 更偏 企业内部 DevOps 一体化平台。

2. GitLab 架构与核心组件

2.1 核心组成

GitLab Rails

主核心：Web、API、业务逻辑。

Gitaly

Git 操作服务（替代原来的 NFS 方案）。

PostgreSQL
Redis
Sidekiq
Nginx/Workhorse
GitLab Runner（独立组件）

2.2 运行流程（简图）

用户 -> Nginx -> Workhorse -> Rails -> Gitaly -> Git Repo
                    ↓
                  Sidekiq
                    ↓
              Redis / PostgreSQL

3. GitLab 安装部署

3.1 Linux 一键安装（推荐）

基于 Omnibus 包：

curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | bash
sudo EXTERNAL_URL="https://gitlab.example.com" apt install gitlab-ee

常用子命令：

gitlab-ctl reconfigure     # 重载配置
gitlab-ctl status          # 查看服务状态
gitlab-ctl restart         # 重启服务
gitlab-rake gitlab:check   # 检查健康

3.2 使用 Docker 部署（最简单）

docker run -d \
    --hostname gitlab.example.com \
    -p 443:443 -p 80:80 -p 22:22 \
    --name gitlab \
    -v /srv/gitlab/config:/etc/gitlab \
    -v /srv/gitlab/logs:/var/log/gitlab \
    -v /srv/gitlab/data:/var/opt/gitlab \
    gitlab/gitlab-ee:latest

3.3 Kubernetes 部署（生产级）

官方 Helm Chart: gitlab/gitlab
需准备：
NFS/S3 Object Storage（Artifacts、Registry）
PostgreSQL（外部或 Cloud）
Redis（Cluster 版）
Ingress

4. GitLab 基础使用教程

4.1 用户与权限

权限级别（从低到高）：

Guest
Reporter
Developer
Maintainer
Owner

核心区别：

角色	查看	推送	创建 MR	管理项目	管理组
Guest	✅	❌	❌	❌	❌
Reporter	✅	❌	❌	❌	❌
Developer	✅	✅	✅	❌	❌
Maintainer	✅	✅	✅	✅	❌
Owner	✅	✅	✅	✅	✅

4.2 组（Group）

一个组可以包含多个项目
可以设置默认权限
可以创建子组（子权限继承）

4.3 项目（Project）

核心功能：

Issues
Merge Requests
Wiki
Snippets
WebIDE
CI/CD Pipelines（.gitlab-ci.yml）

4.4 Merge Request（代码评审）

MR 推荐流程：

开新分支
提交代码
Push
创建 MR
Reviewer 代码Review
MR pipeline 通过
Squash merge

5. GitLab CI/CD（完全体）

核心文件：.gitlab-ci.yml

5.1 Pipeline 基本结构

stages:
  - build
  - test
  - deploy

build-job:
  stage: build
  script:
    - echo "Build..."

test-job:
  stage: test
  script:
    - echo "Run Test"

deploy-job:
  stage: deploy
  script:
    - echo "Deploy"
  only:
    - main

5.2 常用配置

缓存 cache

cache:
  paths:
    - node_modules/

工件 artifacts

artifacts:
  paths:
    - build/
  expire_in: 7 days

环境管理 environment

environment:
  name: production
  url: https://prod.example.com

变量 variables

variables:
  NODE_ENV: production

6. GitLab Runner 教程

6.1 安装 Runner

sudo apt install gitlab-runner
gitlab-runner --version

6.2 注册 Runner

gitlab-runner register

选择：

executor：docker / shell / virtualbox / kubernetes
默认推荐 Docker executor

6.3 Docker Runner 配置

[runners.docker]
  tls_verify = false
  image = "alpine:latest"
  privileged = true
  volumes = ["/cache"]

7. GitLab 常用功能

7.1 Issues

任务管理，可配置 label、milestone、assignee。

7.2 Milestone

用于管理阶段性任务（如迭代）。

7.3 Webhook

常用场景：

触发 Jenkins
推送到飞书/钉钉
自动部署

7.4 GitLab API（REST & GraphQL）

示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  https://gitlab.example.com/api/v4/projects

8. GitLab 运维管理

8.1 备份

gitlab-backup create
ls /var/opt/gitlab/backups

8.2 恢复

gitlab-backup restore BACKUP=xxx
gitlab-ctl reconfigure

8.3 升级原则

不要跨大版本升级
遵循版本跳跃规则（如 12 -> 13 -> 14）

9. GitLab 性能调优

9.1 推荐服务器配置

人数	CPU	内存	存储
<100	4C	8G	SSD
100 ~ 1000	8C	16G	SSD
企业级	16C+	32G+	SSD RAID

9.2 调优方向

Gitaly 分离部署
Redis Cluster
PostgreSQL 外部化（主从）
Sidekiq 多队列
Registry、Artifacts 使用 S3

10. GitLab 安全加固

强制 2FA
禁止 Guest 创建项目
限制 Runner 权限（不要 root/privileged）
关闭公开注册
配置防火墙：只暴露 22、80、443
启用 SSO（LDAP / SAML）

11. GitLab 最佳实践（企业级）

开发流程推荐：

main：保护分支
dev：普通开发
feature/*：特性
bugfix/*：修复
hotfix/*：线上修复

CI/CD 最佳实践

每个 MR 触发 pipeline
pipeline 分阶段：Lint -> Build -> Test -> Deploy
生产环境必须有手工确认（manual）

权限最佳实践

Developer 不允许直接 push main
Maintainer 才能合并 MR
每个组使用子组管理权限隔离
Runner 使用 token + scope 限制