@GitLab 介绍&部署&使用详细指南

文章目录

- - [**GitLab 介绍&部署&使用详细指南**](#GitLab 介绍&部署&使用详细指南)
  - [**1. GitLab 介绍与核心概念**](#1. GitLab 介绍与核心概念)
  - - [**1.1 什么是 GitLab？**](#1.1 什么是 GitLab？)
    - [**1.2 核心特性**](#1.2 核心特性)
    - [**1.3 版本区别**](#1.3 版本区别)
  - [**2. 部署指南 (以 Ubuntu 22.04 LTS 为例)**](#2. 部署指南 (以 Ubuntu 22.04 LTS 为例))
  - - [**2.1 环境准备**](#2.1 环境准备)
    - [**2.2 安装步骤**](#2.2 安装步骤)
    - [**2.3 重要配置文件**](#2.3 重要配置文件)
  - [**3. 基本使用入门**](#3. 基本使用入门)
  - - [**3.1 初始设置**](#3.1 初始设置)
    - [**3.2 创建项目与代码推送**](#3.2 创建项目与代码推送)
    - [**3.3 核心工作流：Merge Request (MR)**](#3.3 核心工作流：Merge Request (MR))
    - [**3.4 CI/CD 快速入门 (`.gitlab-ci.yml`)**](#3.4 CI/CD 快速入门 (.gitlab-ci.yml))
  - [**4. 常见问题 (FAQ) 与故障排除**](#4. 常见问题 (FAQ) 与故障排除)
  - - [**Q1: 502 Whoops, GitLab is taking too much time to respond.**](#Q1: 502 Whoops, GitLab is taking too much time to respond.)
    - [**Q2: 如何备份和恢复 GitLab？**](#Q2: 如何备份和恢复 GitLab？)
    - [**Q3: 如何修改 GitLab 的访问域名/URL？**](#Q3: 如何修改 GitLab 的访问域名/URL？)
    - [**Q4: 忘记 root 密码怎么办？**](#Q4: 忘记 root 密码怎么办？)
    - [**Q5: 如何配置外部邮件服务（如 SMTP）？**](#Q5: 如何配置外部邮件服务（如 SMTP）？)
  - [**5. 附录与进一步学习**](#5. 附录与进一步学习)

GitLab 介绍&部署&使用详细指南

1. GitLab 介绍与核心概念

1.1 什么是 GitLab？

GitLab 是一个基于 Git 的完整的DevOps 平台。它不仅仅是一个源代码版本控制系统（如 GitHub），更是一套集成了项目管理、代码仓库、CI/CD、监控、安全扫描等功能的综合性工具链。它支持从项目规划、源代码管理到构建、测试、部署和监控的整个开发生命周期。

1.2 核心特性

版本控制 (Git Repository): 提供强大的分布式版本控制功能。
项目管理 (Issue Tracking, Wiki): 提供问题跟踪、看板、Wiki 文档等功能，便于团队协作。
代码审查 (Merge Request): 支持代码合并请求、同行评审、评论和差异对比。
CI/CD (Continuous Integration/Delivery/Deployment): 内置强大的 CI/CD 流水线工具，无需集成其他工具（如 Jenkins）。
容器镜像仓库 (Container Registry): 内置 Docker 镜像仓库，方便管理项目镜像。
安全扫描 (Security Scanning): 提供依赖项扫描、SAST（静态应用安全测试）、DAST（动态应用安全测试）等安全功能。
多种安装方式: 支持从源代码、Omnibus 包、Docker 容器、云原生（Helm Chart）等多种方式部署。

1.3 版本区别

GitLab Community Edition (CE): 社区版，免费，包含大部分核心功能。
GitLab Enterprise Edition (EE): 企业版，付费，包含更多高级功能，如史诗管理、高级 CI/CD、合规性管理等。

本 SOP 将以 社区版 (CE) 为例进行说明。

2. 部署指南 (以 Ubuntu 22.04 LTS 为例)

官方推荐使用 Omnibus 包安装，这是最快捷、最易于维护的方式。

2.1 环境准备

操作系统: Ubuntu 22.04 LTS
硬件需求:
- 内存: 至少 4GB，推荐 8GB 或以上。4GB 内存下，Sidekiq 和 Puma 会在执行大型任务时使用 Swap，导致性能下降。
- CPU: 至少 2 核，推荐 4 核。
- 存储: 根据代码和仓库大小决定，至少 10GB 可用空间。
软件依赖:
- 确保系统已安装 curl, openssh-server, ca-certificates 等基本工具。

2.2 安装步骤

安装并配置必要的依赖:
bash 复制代码
```
sudo apt-get update
sudo apt-get install -y curl openssh-server ca-certificates postfix
```
在安装 Postfix（邮件服务器）时，如果计划使用外部邮件服务，可以选择"Internet Site"或直接跳过，后续再配置。

添加 GitLab 包仓库并安装:

bash 复制代码

curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

或者使用清华大学的镜像源（国内服务器推荐）:

bash 复制代码

# 信任 GitLab 的 GPG 公钥
curl https://packages.gitlab.com/gpg.key 2> /dev/null | sudo apt-key add - &>/dev/null

# 添加清华镜像源
vi /etc/apt/sources.list.d/gitlab-ce.list
# 写入以下内容
deb https://mirrors.tuna.tsinghua.edu.cn/gitlab-ce/ubuntu jammy main

# 更新缓存
sudo apt-get update

安装 GitLab CE:

bash 复制代码

# 将 `http://your-domain-or-ip` 替换为您服务器的实际访问地址
# 这将自动配置 GitLab 使用该 URL 并申请 Let's Encrypt 证书
sudo EXTERNAL_URL="http://your-domain-or-ip" apt-get install gitlab-ce

如果您暂时没有域名，可以先使用 http 协议和 IP 地址，例如：EXTERNAL_URL="http://192.168.1.100"。

首次启动与配置:

安装脚本会自动执行 gitlab-ctl reconfigure，初始化所有服务。此过程可能需要几分钟。
获取初始 root 密码:

安装完成后，初始管理员 root 的密码存储在 /etc/gitlab/initial_root_password 中。请立即登录并修改密码。
bash 复制代码
```
sudo cat /etc/gitlab/initial_root_password
```

常用管理命令:

bash 复制代码

# 启动所有 GitLab 服务
sudo gitlab-ctl start

# 停止所有 GitLab 服务
sudo gitlab-ctl stop

# 重启所有 GitLab 服务
sudo gitlab-ctl restart

# 重新加载配置（修改 /etc/gitlab/gitlab.rb 后必须执行）
sudo gitlab-ctl reconfigure

# 查看服务状态
sudo gitlab-ctl status

# 查看日志（如检查问题）
sudo gitlab-ctl tail nginx     # 查看 Nginx 日志
sudo gitlab-ctl tail postgresql # 查看 PostgreSQL 日志

2.3 重要配置文件

/etc/gitlab/gitlab.rb: GitLab 的主配置文件。所有自定义配置（如邮箱、备份、域名变更等）都在此文件中修改。修改后务必执行 sudo gitlab-ctl reconfigure 使其生效。

3. 基本使用入门

3.1 初始设置

通过浏览器访问您在安装时设置的 EXTERNAL_URL。
使用用户名 root 和之前获取的密码登录。
立即在 User Settings -> Password 中修改 root 用户的密码。

3.2 创建项目与代码推送

创建新项目:
- 点击导航栏中的 "Create new project"。
- 输入项目名称（如 my-awesome-project），选择可见级别（Private, Internal, Public）。
- 点击 "Create project"。

推送现有代码到新仓库:

bash 复制代码

# 进入你的本地代码目录
cd your-local-project

# 初始化 git（如果尚未初始化）
git init --initial-branch=main
git add .
git commit -m "Initial commit"

# 添加 GitLab 远程仓库地址
git remote add origin http://your-gitlab-url/username-or-group/project-name.git

# 推送代码
git push -u origin main

系统会提示您输入用户名和密码。

3.3 核心工作流：Merge Request (MR)

这是 GitLab 协作的核心。

创建分支: 从 main 分支创建一个新功能分支（如 feature/login-page）。
开发与提交: 在新分支上进行代码开发并提交。
推送分支: 将分支推送到 GitLab 远程仓库：git push origin feature/login-page。
创建 Merge Request: 在 GitLab 项目页面上，会提示你为刚推送的分支创建 MR。填写标题、描述，并指定目标分支 （通常是 main）和审核人。
代码审查: 审核人可以在 MR 中评论代码、提出修改意见。
修改与推送: 根据反馈在本地修改代码，再次提交并推送到同一个分支，MR 会自动更新。
合并: 审核通过后，点击 "Merge" 按钮将更改合并到目标分支。

3.4 CI/CD 快速入门 (`.gitlab-ci.yml`)

GitLab CI/CD 通过项目根目录下的 .gitlab-ci.yml 文件定义流水线。

示例：一个简单的 Node.js 项目流水线

yaml 复制代码

# .gitlab-ci.yml
stages:
  - test
  - build

test-job:
  stage: test
  image: node:18
  script:
    - npm install
    - npm run test

build-job:
  stage: build
  image: node:18
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

将此文件放入项目根目录并推送到 GitLab，CI/CD 流水线会自动触发。你可以在项目的 "CI/CD" -> "Pipelines" 中查看运行状态和日志。

4. 常见问题 (FAQ) 与故障排除

Q1: 502 Whoops, GitLab is taking too much time to respond.

原因: 最常见的原因是内存不足。Unicorn/Puma 工作者进程因内存不足而被杀死。
解决方案:
1. 检查系统内存：free -h。如果可用内存很少，请增加 Swap 空间。
2. 增加 Swap (以添加 4GB Swap 为例):
  bash 复制代码
```
sudo dd if=/dev/zero of=/swapfile bs=1M count=4096
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# 永久生效，写入 /etc/fstab: /swapfile swap swap defaults 0 0
```
3. 检查 sudo gitlab-ctl status 是否有服务异常退出。

Q2: 如何备份和恢复 GitLab？

备份: 使用命令 sudo gitlab-backup create。备份文件默认存储在 /var/opt/gitlab/backups/ 目录下。注意：这个命令不备份配置文件！
恢复:
1. 将备份文件拷贝到新服务器的备份目录。
2. 停止相关服务：sudo gitlab-ctl stop puma && sudo gitlab-ctl stop sidekiq。
3. 执行恢复（将 TIMESTAMP 替换为备份文件的时间戳）:
  bash 复制代码
```
sudo gitlab-backup restore BACKUP=TIMESTAMP
```
4. 重要： 确保将旧服务器上的 /etc/gitlab/gitlab.rb 和 /etc/gitlab/gitlab-secrets.json 也拷贝到新服务器的相同位置。
5. 重新配置并启动：sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart。

Q3: 如何修改 GitLab 的访问域名/URL？

编辑主配置文件：sudo vi /etc/gitlab/gitlab.rb。
找到并修改 external_url 'http://old-url' 为新的地址。
重新配置：sudo gitlab-ctl reconfigure。此命令会自动重启所有服务。

Q4: 忘记 root 密码怎么办？

进入服务器命令行。
执行 sudo gitlab-rake "gitlab:password:reset[root]"。
按提示输入新密码。

Q5: 如何配置外部邮件服务（如 SMTP）？

修改 /etc/gitlab/gitlab.rb，添加如下配置（以 Gmail 为例）:

ruby 复制代码

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "your-email@gmail.com"
gitlab_rails['smtp_password'] = "your-app-password" # 注意：使用应用专用密码，非邮箱登录密码
gitlab_rails['smtp_domain'] = "gmail.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false

修改后执行 sudo gitlab-ctl reconfigure。

5. 附录与进一步学习

官方文档: https://docs.gitlab.com/ - 最全面、最权威的参考资料。
安装选项: 除了 Omnibus，你还可以探索：
- Docker: docker run --detach --hostname gitlab.example.com --publish 443:443 --publish 80:80 --name gitlab --restart always --volume $GITLAB_HOME/config:/etc/gitlab --volume $GITLAB_HOME/logs:/var/log/gitlab --volume $GITLAB_HOME/data:/var/opt/gitlab gitlab/gitlab-ce:latest
- Kubernetes (Helm): 适用于大规模、高可用的生产环境。
性能调优: 对于生产环境，务必阅读官方《性能调优》文档，调整 /etc/gitlab/gitlab.rb 中的 puma, sidekiq, postgresql 等参数。

@GitLab 介绍&部署&使用详细指南

文章目录

GitLab 介绍&部署&使用详细指南

1. GitLab 介绍与核心概念

1.1 什么是 GitLab？

1.2 核心特性

1.3 版本区别

2. 部署指南 (以 Ubuntu 22.04 LTS 为例)

2.1 环境准备

2.2 安装步骤

2.3 重要配置文件

3. 基本使用入门

3.1 初始设置

3.2 创建项目与代码推送

3.3 核心工作流：Merge Request (MR)

3.4 CI/CD 快速入门 (.gitlab-ci.yml)

4. 常见问题 (FAQ) 与故障排除

Q1: 502 Whoops, GitLab is taking too much time to respond.

Q2: 如何备份和恢复 GitLab？

Q3: 如何修改 GitLab 的访问域名/URL？

Q4: 忘记 root 密码怎么办？

Q5: 如何配置外部邮件服务（如 SMTP）？

5. 附录与进一步学习

3.4 CI/CD 快速入门 (`.gitlab-ci.yml`)