文章目录
[**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 工作者进程因内存不足而被杀死。
解决方案:
检查系统内存：free -h。如果可用内存很少，请增加 Swap 空间。
增加 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
检查 sudo gitlab-ctl status 是否有服务异常退出。
Q2: 如何备份和恢复 GitLab？
备份: 使用命令 sudo gitlab-backup create。备份文件默认存储在 /var/opt/gitlab/backups/ 目录下。注意：这个命令不备份配置文件！
恢复:
将备份文件拷贝到新服务器的备份目录。
停止相关服务：sudo gitlab-ctl stop puma && sudo gitlab-ctl stop sidekiq。
执行恢复（将 TIMESTAMP 替换为备份文件的时间戳）:
bash
复制代码
sudo gitlab-backup restore BACKUP=TIMESTAMP
重要： 确保将旧服务器上的 /etc/gitlab/gitlab.rb 和 /etc/gitlab/gitlab-secrets.json 也拷贝到新服务器的相同位置。
重新配置并启动：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 等参数。