GitLab 完整落地

前言

绝大多数公司开发都会使用 GitLab，它是私有化部署的代码仓库、CI/CD 一体化平台，替代公有 GitHub/Gitee，兼顾代码私有、权限管控、自动构建、自动测试、自动部署、代码评审全流程。 本文完整覆盖：为什么企业必须用 GitLab、GitLab 核心组件、三种部署方案（Docker 一键部署推荐）、基础操作、分支规范、权限管理、CI/CD 流水线、日常协作流程、备份迁移、运维排错，完整可落地。

一、为什么需要 GitLab？解决什么痛点

1. 公有代码仓库的缺陷（GitHub/Gitee）

1. 代码安全不可控 公司业务源码、数据库脚本、中间件配置、核心算法上传公网存在泄露风险；
2. 网络访问限制 GitHub 国内访问不稳定，企业内网环境无法访问外网；
3. CI/CD 功能受限 公有平台流水线有时长、并发限制，无法对接内网测试 / 生产服务器；
4. 精细化权限缺失 无法按部门、项目、环境区分读写、合并、部署权限；
5. 数据无法自主备份 代码、提交记录、流水线日志、制品全部托管第三方，企业无完整数据所有权。

2. GitLab 核心价值

（1）私有化代码仓库，代码完全自主可控

基于 Git 底层，托管所有项目源码，部署在企业内网 / 私有云，外部网络无法访问，保障商业代码安全。

（2）完整权限体系，分级管控

支持超级管理员、部门管理员、项目所有者、开发、测试、访客多层角色；可限制分支推送、禁止直接 push 主分支、仅允许合并 MR。

（3）内置 CI/CD 自动化流水线

无需额外搭建 Jenkins，内置流水线： 提交代码自动构建、单元测试、代码扫描、打包镜像、自动部署测试 / 生产环境。

（4）标准化代码评审 MR

开发不能直接推送代码到主分支，必须提交合并请求，指定负责人审核代码，通过后才能合并，规范代码质量。

（5）配套配套研发工具一体化

• 在线代码编辑器；
• 制品仓库：存储 Docker 镜像、Maven Jar 包；
• 项目看板、任务管理、缺陷关联；
• Wiki 文档、接口文档、项目知识库；
• 内置监控、日志、审计日志（谁拉取、推送、合并代码）。

（6）高可用、备份、迁移能力

支持集群部署、定时全量备份、跨服务器迁移，满足企业生产稳定要求。

3. GitLab 版本区分

1. GitLab Community Edition（CE 社区免费版） 个人、中小企业首选，免费开源，包含代码仓库、MR、CI/CD 基础功能，无商业付费。
2. GitLab Enterprise Edition（EE 企业付费版） 高级权限、安全扫描、集群高可用、官方技术支持、LDAP 统一登录、多租户管理，大型集团使用。

二、GitLab 整体架构核心组件（理解部署原理）

整套 GitLab 由多个独立服务组成，Docker 镜像已内置全部组件，无需单独安装：

1. Nginx：反向代理、静态资源、SSL、端口转发，前端访问入口
2. GitLab Rails：核心 Web 后台，页面、权限、MR、项目管理
3. Gitaly：Git 底层存储服务，管理仓库文件、提交记录
4. PostgreSQL：数据库，存储用户、项目、权限、流水线记录
5. Redis：缓存、任务队列、会话存储
6. Sidekiq：异步任务执行器（流水线、邮件、备份、镜像打包）
7. GitLab Runner：CI/CD 执行器，单独部署，执行流水线脚本
8. MinIO / 内置容器仓库：存储构建 Docker 镜像、Jar 包制品

三、三种部署方案详解（推荐 Docker）

方案 1：Docker Compose 一键部署

前置条件

云服务器 CentOS7/8 / Ubuntu，配置：

• 最低配置：2 核 4G（低于 4G 内存会频繁卡顿、流水线卡死）
• 磁盘：至少 50G，代码、镜像、日志持续占用空间
• 安全组放行端口：80（网页）、443（HTTPS）、22（ssh 拉代码）

步骤 1：安装 Docker + Docker Compose

bash运行

# CentOS
yum install docker-ce docker-compose -y
systemctl start docker
systemctl enable docker

步骤 2：编写 docker-compose.yml

新建文件夹 /usr/local/gitlab，创建配置文件

yaml

version: '3.6'
services:
  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    restart: always
    privileged: true
    ports:
      - "80:80"
      - "443:443"
      - "22:22"
    volumes:
      # 持久化目录，数据不会随容器删除丢失
      - ./config:/etc/gitlab
      - ./logs:/var/log/gitlab
      - ./data:/var/opt/gitlab
    environment:
      # 填写你的服务器公网IP/域名
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://120.xx.xx.xx'
        # ssh克隆地址端口
        gitlab_rails['gitlab_shell_ssh_port'] = 22
        # 邮箱配置（可选，MR审核、通知邮件）
        gitlab_rails['smtp_enable'] = true

步骤 3：启动容器

bash运行

docker-compose up -d

首次启动需要 5~10 分钟初始化数据库、生成配置，访问页面超时属于正常现象。

步骤 4：获取初始管理员密码

默认管理员账号 root

bash运行

# 进入容器查看初始密码
docker exec -it gitlab cat /etc/gitlab/initial_root_password

复制密码，浏览器访问服务器 IP 登录，登录后立刻修改 root 密码。

方案 2：Linux 原生 rpm/deb 包部署

适合物理机、需要深度调优的场景，缺点环境依赖多，容易出现版本冲突。

bash运行

# CentOS 安装源
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash
yum install gitlab-ce -y
# 初始化配置
gitlab-ctl reconfigure
# 启停命令
gitlab-ctl start/stop/restart/status

方案 3：K8s 集群部署

大型企业多节点高可用，使用 GitLab 官方 helm 包，适合集群扩容，个人项目不推荐，部署复杂。

补充：GitLab Runner 部署（CI 流水线必备）

GitLab 容器仅提供流水线调度，真正执行打包、部署脚本需要单独部署 Runner Docker 快速部署 Runner：

bash运行

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

部署完成后进入 GitLab 页面获取注册 token，执行注册命令绑定项目。

四、GitLab 基础使用完整流程（从创建项目到代码提交）

1. 基础账号与分组管理

1）用户管理

管理员登录后进入「Admin 区域」：

• 创建开发、测试、产品账号；
• 设置密码、邮箱、登录权限；
• 禁用离职员工账号，回收代码权限。

2）Group 分组（按业务划分）

Group = 业务部门 / 产品线，例如 order-group 订单业务组

• Group 内可以创建多个项目仓库；
• 统一设置组权限，新仓库自动继承权限；
• 统一查看组下所有项目 MR、流水线。

2. 创建项目仓库

1. 点击新建项目，三种创建方式：
   • 空白项目（全新开发）
   • 导入已有仓库（Gitee/GitHub 迁移）
   • 模板项目（SpringBoot/Vue 模板）
2. 可见级别：
   • Private 私有：仅项目成员可访问（公司项目必选）
   • Internal 内网所有登录用户可见
   • Public 任何人可读，禁止业务代码使用

3. 本地 Git 关联仓库、提交代码

方式 1：HTTPS 拉取推送（简单，输入账号密码）

bash运行

# 克隆项目到本地
git clone http://服务器ip/order-group/order-service.git
cd order-service
# 修改代码后提交
git add .
git commit -m "新增订单创建接口"
# 推送到远程main分支
git push origin main

方式 2：SSH 免密推送（开发推荐）

1. 本地生成 ssh 密钥

bash

ssh-keygen -t rsa
cat ~/.ssh/id_rsa.pub

1. 复制公钥，GitLab 个人设置 → SSH 密钥，粘贴保存；
2. 使用 ssh 地址克隆，无需重复输入账号密码：

bash

git clone git@服务器IP:order-group/order-service.git

4. 分支规范（企业标准 GitFlow）

固定分支定义

1. main / master：生产环境稳定分支，禁止直接 push，只能 MR 合并
2. dev：开发测试环境主分支，日常开发合并到此
3. feature/xxx：功能开发分支，每个人新建自己的功能分支
4. hotfix/xxx：线上紧急 bug 修复分支
5. release/v1.0：版本发布分支

开发流程

1. 从 dev 拉出 feature 分支开发；
2. 开发完成提交本地，推送远程 feature 分支；
3. 创建 Merge Request 合并到 dev；
4. 代码审核通过后合并，删除 feature 分支；
5. 测试稳定后，MR 合并 dev 到 main 发布上线。

五、核心功能 1：Merge Request 代码评审

1. MR 作用

1. 禁止开发直接推送代码到 dev/main，防止脏代码、bug 直接进入主干；
2. 指定评审人，多人查看代码逻辑、规范、安全漏洞；
3. 支持在线批注、提出修改意见，修改后重新提交；
4. 自动触发 CI 流水线，编译、单元测试不通过禁止合并。

2. MR 操作步骤

1. 本地 feature 分支开发完成 push 远程；
2. GitLab 页面点击「Create merge request」；
3. 源分支：feature 分支，目标分支：dev；
4. 选择评审人、填写开发说明、关联需求 / 缺陷；
5. 提交 MR，等待评审；
6. 评审通过 + CI 流水线成功，点击合并，可勾选删除源分支。

3. 管理员保护主干分支

项目 → 设置 → 仓库 → 分支保护

1. 锁定 main、dev 分支；
2. 禁止任何人直接 push；
3. 仅允许拥有 Maintainer 权限用户审核合并；
4. 要求流水线成功才能合并。

六、核心功能 2：CI/CD 自动化流水线（GitLab 核心优势）

1. 实现原理

项目根目录新建 .gitlab-ci.yml 文件，定义流水线阶段、执行脚本，代码提交后自动触发 Runner 执行。

2. 流水线标准三阶段

1. build 构建：Maven/Gradle 打包、Vue 前端打包
2. test 测试：单元测试、代码覆盖率、静态代码扫描
3. deploy 部署：自动推送 Jar 到服务器、部署容器

3. SpringBoot 极简 .gitlab-ci.yml 示例

yaml

# 流水线执行镜像
image: maven:3.8-openjdk-17
# 阶段顺序
stages:
  - build
  - test
  - deploy

# 打包阶段
build:
  stage: build
  script:
    - mvn clean package -Dmaven.test.skip=true
  artifacts:
    paths:
      - target/*.jar

# 单元测试
test:
  stage: test
  script:
    - mvn test

# 部署到测试服务器
deploy-test:
  stage: deploy
  script:
    - scp target/*.jar root@测试服务器IP:/data/project/
    - ssh root@测试服务器IP "cd /data/project && sh restart.sh"
  only:
    - dev # 仅dev分支触发测试部署

# 生产部署（仅main分支允许）
deploy-prod:
  stage: deploy
  script:
    - scp target/*.jar root@生产IP:/data/prod/
  only:
    - main
  when: manual # 手动点击执行，防止自动发布线上

4. 流水线能力

1. 提交代码自动触发；
2. 分支区分环境，dev 自动部署测试，main 手动部署生产；
3. 保存构建产物 Jar、镜像；
4. 流水线失败发送邮件告警；
5. 记录每一次构建日志，可回滚历史版本。

七、权限体系详解（五级角色）

进入项目 → 设置 → 成员，分配 5 种权限，权限从上到下递减：

1. Owner 所有者 拥有项目全部权限：删除项目、修改配置、管理成员、修改分支保护、管理 CI/CD。
2. Maintainer 维护者 管理成员、合并 MR、配置流水线、保护分支，无删除项目权限。
3. Developer 开发人员（日常开发标配） 拉取代码、创建分支、提交代码、创建 MR，无法合并主干、修改项目配置。
4. Reporter 测试 / 产品 仅可读代码、查看 MR、流水线、Wiki，不能推送代码。
5. Guest 访客 仅查看公开文档，无法访问代码。

八、配套实用功能

1. Wiki 项目文档

每个项目内置知识库，存储接口文档、部署文档、需求文档，和代码仓库绑定，版本同步。

2. 制品仓库 Package Registry

存储 Maven Jar、Docker 镜像，流水线打包后自动上传，项目统一拉取依赖。

3. WebIDE 在线编辑器

浏览器直接修改代码、提交分支，临时改 bug 无需本地 Git 环境。

4. 审计日志

记录所有操作：账号登录、代码推送、MR 合并、流水线执行、账号权限变更，安全溯源。

九、日常运维：备份、迁移、扩容

1. 定时备份（重要，防止代码丢失）

Docker 部署执行备份命令：

bash

docker exec -t gitlab gitlab-backup create
# 备份文件存储在 ./data/backups
# 同时备份配置文件
docker exec gitlab tar -cvf /var/opt/gitlab/backups/config.tar /etc/gitlab

配合 Linux 定时任务 crontab 每日凌晨自动备份。

2. 迁移到新服务器

1. 新服务器部署同版本 GitLab；
2. 将备份文件、配置文件拷贝到新容器；
3. 执行恢复命令：gitlab-backup restore BACKUP=备份编号；
4. 重新配置域名、端口、Runner。

3. 内存优化

GitLab 默认占用大量内存，4G 机器修改配置限制 Redis、PostgreSQL 内存，避免 OOM 宕机。

十、常见问题与排错

1. 页面访问超时，502 错误 内存不足，至少扩容至 4G；等待初始化完成；执行gitlab-ctl restart重启服务。
2. CI 流水线卡住，任务不执行 GitLab Runner 未启动、未注册、镜像拉取失败，查看 Runner 日志。
3. 无法推送代码，403 权限不足 分支开启保护，禁止直接 push，必须走 MR；账号权限不足。
4. SSH 克隆连接失败 服务器 22 端口未放行，修改 gitlab ssh 端口配置。
5. 磁盘占满 清理流水线旧产物、过期镜像、日志，定时备份后删除老旧备份。

十一、完整学习使用路线

1. 部署 Docker 版 GitLab，修改管理员密码；
2. 创建业务 Group、新建项目；
3. 本地 Git 配置 SSH 密钥，拉取提交代码；
4. 遵守 GitFlow 分支规范，练习 MR 代码评审；
5. 部署 GitLab Runner，编写.gitlab-ci.yml 实现自动打包部署；
6. 配置分支保护、分级成员权限；
7. 开启定时备份，掌握基础运维；
8. 进阶：LDAP 统一登录、HTTPS 域名、容器镜像仓库。

结语

GitLab 是企业研发一体化核心平台，不只是单纯代码仓库。对于后端开发，必须掌握：私有化部署、Git 分支协作、MR 代码评审、CI 自动构建部署三大核心能力。 对比 Jenkins+Gitee 组合，GitLab 一体化减少中间件维护成本，权限管控更贴合企业内部安全规范，是绝大多数中小企业标准研发工具。