• 操作系统: Linux (推荐 Ubuntu 20.04+ 或 CentOS 7/8)
• 内存: 至少 4GB RAM，对于 CE (Community Edition) 版本，4GB 是最低要求，8GB 或以上体验更佳，EE (Enterprise Edition) 需要更多资源。
• CPU: 2 核或以上
• 磁盘空间: 至少 20GB 可用空间，GitLab 的数据、日志和仓库会占用大量空间，请根据团队规模预留更多空间。
• 网络: 需要一个固定的 IP 地址或域名，以便其他用户可以访问。

2 安装方式选择

GitLab 主要提供两种安装方式：

1. Omnibus 包安装: 这是最简单、最推荐的方式，GitLab 官方将所有组件（Ruby on Rails, Nginx, PostgreSQL 等）打包成一个 .deb (Debian/Ubuntu) 或 .rpm (CentOS/RHEL) 包，你只需要执行几个命令即可完成安装，非常适合快速部署和生产环境。
2. Docker 安装: 通过官方提供的 Docker 镜像运行 GitLab，这种方式非常轻量，启动快，适合开发、测试、学习或 CI/CD 环境。
3. 源码安装: 从源码编译安装，这种方式非常复杂，不推荐普通用户使用，主要用于深度定制和 GitLab 核心开发。

本教程将重点讲解最常用的 Omnibus 包安装 和最快捷的 Docker 安装。

3 使用 Docker 快速安装 (推荐新手)

这是最简单快捷的方式,只需几条命令即可运行一个功能完整的 GitLab。

步骤 1: 安装 Docker 和 Docker Compose

如果你的系统还没有安装 Docker，请先安装，以 Ubuntu 为例：

# 更新软件包索引
sudo apt-get update
# 安装必要的包
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
# 添加 Docker 仓库
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
# 再次更新索引并安装 Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

步骤 2: 创建 docker-compose.yml 文件

创建一个目录来存放 GitLab 相关文件，并在其中创建 docker-compose.yml 文件。

mkdir gitlab && cd gitlab
vim docker-compose.yml

粘贴到 docker-compose.yml 文件中：

version: '3.6'
services:
  gitlab:
    image: 'gitlab/gitlab-ce:latest' # 使用最新的社区版镜像
    container_name: gitlab
    restart: always
    hostname: 'gitlab.example.com' # 替换成你的服务器域名或 IP
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://gitlab.example.com' # 替换成你的服务器域名或 IP
        # 如果使用 HTTPS，请取消下面两行的注释并修改域名
        # letsencrypt['enable'] = true
        # letsencrypt['contact_emails'] = ['admin@example.com']
    ports:
      - '80:80'
      - '443:443'
      - '22:22'
    volumes:
      - './config:/etc/gitlab'
      - './logs:/var/log/gitlab'
      - './data:/var/opt/gitlab'

重要配置说明:

• hostname: GitLab 实例的完整域名，如果只是本地测试，可以写你的服务器 IP。
• external_url: GitLab 的对外访问地址，必须和 hostname 保持一致。
• ports: 将宿主机的端口映射到容器内部。80 (HTTP), 443 (HTTPS), 22 (SSH) 是必须的。
• volumes: 将容器的配置、日志和数据持久化到宿主机上，这样即使容器重启，数据也不会丢失。

步骤 3: 启动 GitLab

在 docker-compose.yml 文件所在的目录下，执行以下命令：

sudo docker-compose up -d

GitLab 会开始下载镜像并启动，这个过程可能需要一些时间，因为镜像很大（几个 GB），你可以使用 sudo docker-compose logs -f 命令来查看启动日志。

步骤 4: 访问 GitLab

启动完成后,打开浏览器，访问你在 external_url 中配置的地址（http://你的服务器IP）。

首次访问时,GitLab 会自动进行初始化，等待几分钟，直到看到登录页面。

• 默认管理员用户名: root
• 默认管理员密码: 需要查看容器日志获取，执行命令：

  sudo docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password

  输出的密码就是初始密码。请在首次登录后立即修改密码！

4 在 Linux (Ubuntu/CentOS) 上源码安装

如果你想在服务器上直接安装 GitLab（而不是使用 Docker），可以按照以下步骤操作。

以 Ubuntu 20.04 为例:

步骤 1: 安装必要的依赖

sudo apt-get update
sudo apt-get install -y curl openssh-server ca-certificates tzdata

步骤 2: 安装 Postfix (用于发送邮件通知)

GitLab 需要一个邮件服务器来发送通知邮件，Postfix 是一个常见的选择。

sudo apt-get install -y postfix

在安装过程中,会弹出配置界面，选择 "Internet Site"，然后按回车，在 "System mail name" 处输入你的域名，gitlab.example.com，然后继续。

步骤 3: 添加 GitLab 官方仓库

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

步骤 4: 安装 GitLab CE

在安装命令中,将 https://gitlab.example.com 替换成你自己的服务器域名或 IP。

sudo EXTERNAL_URL="http://你的服务器IP或域名" apt-get install gitlab-ce

步骤 5: 重新配置 GitLab

安装完成后,运行以下命令让 GitLab 应用所有配置：

sudo gitlab-ctl reconfigure

步骤 6: 启动 GitLab 服务

sudo gitlab-ctl start

步骤 7: 访问 GitLab

与 Docker 方式相同，在浏览器中访问你配置的 EXTERNAL_URL，初始用户名和密码的获取方式也与 Docker 方式一致。

5 首次访问与配置

1. 登录: 使用用户名 root 和获取到的初始密码登录。
2. 修改密码: 登录后，系统会强烈建议你修改密码，点击 "Edit profile" -> "Password" 进行修改。
3. 设置 Profile: 可以修改你的用户名、邮箱等信息，邮箱非常重要，用于接收通知。
4. 创建 SSH Key: 登录后，点击右上角你的头像 -> "Preferences" -> "SSH Keys"，将你本地的公钥（通常在 ~/.ssh/id_rsa.pub 文件中）粘贴到这里，这样以后就可以免密操作 GitLab 了。

第二部分：GitLab 基本使用

1 创建第一个项目

1. 登录 GitLab 后，点击页面左侧导航栏的 "+" 号，选择 "New project"。
2. 填写项目信息：
   • Project name: 给你的项目起个名字，my-first-project。
   • Project URL: GitLab 会根据项目名自动生成一个 URL。
   • Visibility Level: 选择项目的可见性。
     • Private: 私有，只有你授权的用户才能看到。
     • Internal: 内部，登录了你 GitLab 实例的所有用户都能看到。
     • Public: 公开，任何人都能访问（但需要克隆/下载权限才能看代码）。
3. 点击 "Create project" 按钮。

2 生成 SSH 密钥 (推荐方式)

使用 SSH 方式与 GitLab 交互，可以避免每次操作都输入用户名和密码。

1. 检查是否已有密钥:

   cd ~/.ssh
   ls

   如果看到 id_rsa 和 id_rsa.pub 文件，说明你已经有了密钥，可以跳到下一步。

2. 生成新的 SSH 密钥: 如果没有密钥，或者你想创建一个新的，执行以下命令，将 your_email@example.com 替换成你的邮箱。

   ssh-keygen -t ed25519 -C "your_email@example.com"

   一路按回车即可,这会在 ~/.ssh/ 目录下生成 id_ed25519 (私钥) 和 id_ed25519.pub (公钥) 文件。

3. 复制公钥内容:

   cat ~/.ssh/id_ed25519.pub

   将输出的全部内容（以 ssh-ed25519 开头）复制到剪贴板。

4. 将公钥添加到 GitLab:

   • 回到 GitLab 浏览器页面。
   • 点击右上角你的头像 -> "Preferences" -> "SSH Keys"。
   • 将刚才复制的公钥粘贴到 "Key" 输入框中，"Title" 可以随便填一个，"My Laptop"。
   • 点击 "Add key"。

3 克隆项目到本地

1. 在你的 GitLab 项目页面，点击 "Clone" 按钮。
2. 选择 "Clone with SSH" 选项。
3. 复制仓库的 URL，它看起来像这样：git@你的服务器IP或域名:root/my-first-project.git。
4. 在你的本地电脑上,打开终端，选择一个你想要存放代码的目录，然后执行克隆命令：

   git clone git@你的服务器IP或域名:root/my-first-project.git

   如果一切正常,GitLab 会使用你之前添加的 SSH 密钥进行验证，无需输入密码，项目就会被下载到本地。

4 提交代码到 GitLab

这是一个典型的 Git 工作流程。

1. 创建并切换到新分支: 在项目根目录下，创建一个新分支进行开发，这是一个好习惯。

   cd my-first-project
   git checkout -b feature-branch

2. 修改文件: 用编辑器打开项目中的任意文件，做一些修改，然后保存。

3. 提交到本地仓库:

   # 查看修改状态
   git status
   # 将修改的文件添加到暂存区
   git add .  # . 表示所有修改
   # 提交到本地仓库，并添加提交信息
   git commit -m "feat: 添加了第一个功能"

4. 推送到远程 GitLab 仓库:

   git push origin feature-branch

   这条命令会将你的 feature-branch 分支推送到 GitLab 服务器上。

5 创建合并请求

当你完成了开发,希望将你的代码合并到主分支（如 main 或 master）时，就需要创建一个 Merge Request (MR)。

1. 回到 GitLab 浏览器中的项目页面。
2. 点击左侧导航栏的 "Merge requests" -> "New merge request"。
3. 在 "Source branch" 中选择你刚刚推送的分支（feature-branch）。
4. 在 "Target branch" 中选择你希望合并到的分支（通常是 main）。
5. GitLab 会自动显示两个分支的差异，填写 Title 和 Description，描述你这次修改了什么。
6. 点击 "Create merge request"。
7. 在下一个页面,你可以点击 "Merge" 按钮直接合并，或者让团队成员进行 "Review" (代码审查) 后再合并，点击 "Merge" 后，你的代码就正式进入了主分支。

第三部分：常用配置与管理

1 修改管理员密码

如果你忘记了 root 用户的密码，可以通过以下方式重置（以 Omnibus 安装为例）：

# 进入 GitLab 的 Rails 控制台
sudo gitlab-rails console -e production
# 在控制台执行以下 Ruby 代码
user = User.where(id: 1).first
user.password = '你的新密码'
user.password_confirmation = '你的新密码'
user.save!
# 退出控制台
exit

2 备份与恢复

备份: GitLab 提供了方便的备份工具。

# 创建备份，备份文件会存放在 /var/opt/gitlab/backups/ 目录下
sudo gitlab-backup create

恢复: 恢复过程比较严格，请务必停止写入数据。

# 1. 停止所有 GitLab 服务
sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# 2. 恢复备份 (假设备份文件是 170241XXXX_gitlab_backup.tar)
sudo gitlab-backup restore BACKUP=170241XXXX
# 3. 重新配置 GitLab
sudo gitlab-ctl reconfigure
# 4. 重启所有服务
sudo gitlab-ctl start

3 邮件配置

GitLab 需要配置邮件服务器才能发送注册、密码重置、合并请求等通知。

以使用外部 SMTP 服务器（如 QQ 邮箱、163 邮箱）为例，编辑配置文件：

sudo vim /etc/gitlab/gitlab.rb

找到或添加以下配置,并修改你的信息：

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.qq.com"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "your_email@qq.com"
gitlab_rails['smtp_password'] = "your_authorization_code" # 注意：不是邮箱密码，是授权码
gitlab_rails['smtp_domain'] = "qq.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = true
gitlab_rails['gitlab_email_from'] = 'your_email@qq.com'
gitlab_rails['gitlab_email_display_name'] = 'GitLab'

配置完成后,保存文件并重新配置 GitLab 使其生效：

sudo gitlab-ctl reconfigure

第四部分：常见问题与总结

1 常见问题

• 问题: 访问 GitLab 页面很慢或出现 502 错误。 原因: 通常是服务器资源不足（内存/CPU）。 解决: 检查系统资源使用情况，增加服务器配置。

• 问题: Docker 启动后，页面无法访问。 原因: 防火墙或安全组规则阻止了 80, 443, 22 端口。 解决: 确保服务器的防火墙和安全组已经开放了这些端口。

• 问题: GitLab 占用磁盘空间过大。 原因: 仓库、LFS 对象、包、CI/CD 缓存、日志等都会占用空间。 解决: 定期清理日志和 CI/CD 缓存，或增加磁盘空间。

• 问题: SSH 连接失败。 原因: 最常见的原因是 GitLab 服务器上的 SSH 服务未启动，或者防火墙阻止了 22 端口。 解决: 确保服务器 SSH 服务正在运行 (sudo systemctl status ssh)，并且端口 22 已开放。

恭喜你！现在你已经掌握了 GitLab 从安装到基本使用的完整流程。

• 安装: 根据你的需求选择 Docker（快速、隔离）或 Omnibus（稳定、适合生产）。
• 使用: 核心是 创建项目 -> 生成 SSH Key -> 克隆 -> 本地开发 -> 提交/推送 -> 创建 Merge Request。
• 管理: 记住如何修改密码、备份恢复和配置邮件，这对于长期维护至关重要。

GitLab 是一个非常强大的 DevOps 平台，除了代码托管，它还集成了 CI/CD (持续集成/持续部署)、Wiki、Issue Tracking、Container Registry 等众多功能，随着你对它的深入使用，你会发现更多能提升团队效率的强大特性。