---

GitLab CE 指南：轻松自托管你的代码仓库

在现代软件开发流程中，版本控制系统（VCS）是不可或缺的基石。Git 作为目前最流行、最强大的分布式版本控制系统，被全球数百万开发者广泛使用。而 GitLab，则是在 Git 的基础上构建的一个完整的 DevOps 平台，它不仅提供了强大的代码仓库管理功能，还集成了项目管理、CI/CD（持续集成/持续部署）、安全扫描、监控等一系列开发运维所需的功能。

GitLab 提供了两种主要的版本：企业版（Enterprise Edition, EE）和社区版（Community Edition, CE）。GitLab EE 包含所有 CE 的功能，并额外提供了一些面向大型企业的高级特性和官方支持，是付费产品。而 GitLab CE 则是完全免费且开源的，它包含了绝大多数开发团队日常所需的核心功能，并且允许用户 自托管（Self-Hosted）。

为什么要选择自托管 GitLab CE？

虽然 GitLab.com 提供了便捷的 SaaS 服务，但自托管 GitLab CE 具有其独特的优势：

1. 数据完全掌控： 你的代码、项目数据、用户信息等所有资产都存储在你自己的服务器上，不受第三方服务提供商的政策限制，拥有最高级别的数据主权和隐私保护。这对于有严格数据合规性要求的组织尤其重要。
2. 高度定制化： 你可以根据自身需求自由配置服务器资源、网络环境、存储方案，甚至可以修改 GitLab CE 的源代码（遵循其开源协议）以满足特殊需求。
3. 成本效益（潜在）： 对于已经拥有服务器资源或用户量较大的团队，相比于付费的 SaaS 服务或 GitLab EE，自托管 CE 在长期来看可能更具成本效益，因为它免除了许可证费用。当然，需要考虑硬件和运维人力成本。
4. 网络隔离与安全： 可以将 GitLab CE 部署在内部网络中，与公网隔离，进一步增强代码和项目的安全性，降低外部攻击风险。
5. 不受平台限制： 无需担心 SaaS 平台可能出现的服务中断、价格调整或功能变更对你的工作流程产生影响。

当然，自托管也意味着你需要承担服务器的购买/租赁、部署、配置、维护、备份、升级和安全防护等责任。但这正是本指南将要详细阐述的内容，旨在帮助你轻松驾驭 GitLab CE 的自托管之旅。

一、 准备工作：环境与要求

在开始安装 GitLab CE 之前，你需要准备好合适的运行环境。

1. 服务器硬件：

   • CPU: 官方建议至少 4 核（推荐 8 核以获得更好性能），这是支持少量并发用户的基本要求。对于更大规模的团队（如数百用户），需要更多核心。
   • 内存 (RAM): 官方建议至少 8 GB RAM（推荐 16 GB RAM）。这是运行 GitLab 所有组件（包括 PostgreSQL, Redis, Puma/Unicorn, Sidekiq 等）的 最低要求。实际内存需求会随用户数、项目复杂度、CI/CD 使用频率等因素显著增加。内存不足是 GitLab 性能问题最常见的原因之一。
   • 存储空间： 初始安装大约需要 2.5 GB 的空间。但你的代码仓库、CI/CD 产生的构建物 (Artifacts)、容器镜像库等会持续消耗大量空间。建议至少准备 50 GB 的可用空间，并根据预估的代码量和使用情况规划，推荐使用 SSD 以获得更好的 I/O 性能。考虑使用逻辑卷管理（LVM）以便后续灵活扩容。
   • 操作系统： GitLab CE 官方推荐并主要支持以下 Linux 发行版（64位）：
     • Ubuntu (推荐 LTS 版本, 如 20.04, 22.04)
     • Debian (推荐稳定版)
     • CentOS / RHEL (推荐 7.x 或兼容版本如 Rocky Linux, AlmaLinux 8.x)
     • openSUSE Leap

2. 网络配置：

   • 静态 IP 地址或固定域名： 服务器需要有一个固定的 IP 地址或一个可以通过 DNS 解析的域名，以便用户和其他服务能够稳定地访问 GitLab 实例。
   • 防火墙规则： 需要配置防火墙，至少允许以下端口的入站连接：
     • 80 (HTTP): 用于初始访问和 Let’s Encrypt 证书验证（如果使用）。
     • 443 (HTTPS): 用于安全的 Web 访问，是推荐的主要访问方式。
     • 22 (SSH): 用于 Git 通过 SSH 协议进行代码操作，以及服务器远程管理。你也可以为 GitLab 配置一个非标准的 SSH 端口。
   • DNS 解析： 如果你打算使用域名访问 GitLab，确保该域名已正确配置 A 记录（或 AAAA 记录）指向你服务器的公网 IP 地址。

3. 邮件服务 (SMTP)： GitLab 需要发送邮件用于用户注册确认、密码重置、通知等。你需要准备一个 SMTP 服务器的信息（地址、端口、用户名、密码、认证方式），可以是公司自建的邮件服务器，也可以是第三方邮件服务提供商（如 Gmail, SendGrid, Mailgun 等）。

4. 基础软件： 在安装 GitLab CE 之前，确保系统已安装一些基础工具，如 curl, openssh-server, ca-certificates。某些系统可能还需要安装邮件发送代理（如 postfix 或 sendmail），尽管 GitLab Omnibus 包通常会处理邮件发送，但有一个本地 MTA 有时能简化配置。

二、 安装 GitLab CE：推荐使用 Omnibus 包

GitLab 官方强烈推荐使用 Omnibus 包进行安装。这是一个包含了 GitLab 及其所有依赖项（Nginx, PostgreSQL, Redis, Sidekiq, Puma 等）的预编译软件包，极大地简化了安装和配置过程。

以下以 Ubuntu 20.04/22.04 LTS 为例说明安装步骤（其他支持的系统类似，只需将 apt 替换为相应的包管理器命令，如 yum 或 zypper）：

1. 更新系统并安装依赖：
   bash
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl openssh-server ca-certificates tzdata perl
# 可选：安装 Postfix 用于邮件发送（如果不想配置外部 SMTP，Postfix 是个简单选择）
# sudo apt install -y postfix
# 在 Postfix 配置界面，通常选择 'Internet Site'，并设置系统邮件名称为你的 GitLab 域名。

2. 添加 GitLab 官方软件源：
   GitLab 提供了一个脚本来帮助添加其官方 APT/YUM 仓库。
   bash
curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
# 对于 CentOS/RHEL 系统，使用 script.rpm.sh
# curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash

3. 安装 GitLab CE 包：
   执行安装命令。这会下载并安装最新稳定版的 GitLab CE。
   bash
sudo apt install gitlab-ce
# 对于 CentOS/RHEL 系统
# sudo yum install gitlab-ce
   这个过程可能需要一些时间，因为它会下载几百兆的软件包并解压。

安装完成后，GitLab CE 的所有文件默认位于 /opt/gitlab/ 目录下，配置文件位于 /etc/gitlab/gitlab.rb，日志文件位于 /var/log/gitlab/ 下的各个子目录，数据（仓库、数据库等）则存储在 /var/opt/gitlab/ 下。

三、 初始配置：让 GitLab 跑起来

安装完成后，最重要的一步是配置 GitLab 的访问 URL。

1. 编辑主配置文件：
   使用你喜欢的文本编辑器（如 nano, vim）打开 /etc/gitlab/gitlab.rb 文件。
   bash
sudo nano /etc/gitlab/gitlab.rb

2. 设置 external_url：
   找到 external_url 这一行（可能被注释掉了），将其修改为你计划用于访问 GitLab 的 URL。强烈建议使用 HTTPS。

   • 如果你有域名 gitlab.example.com 并打算使用 HTTPS：
     ruby
external_url 'https://gitlab.example.com'
   • 如果你暂时只使用 IP 地址 192.168.1.100 并且先用 HTTP（不推荐生产环境）：
     ruby
external_url 'http://192.168.1.100'
     注意： 这个 URL 非常重要，GitLab 会用它来生成仓库克隆地址、邮件中的链接等。请确保设置正确。

3. （可选）配置 Let’s Encrypt 自动获取 SSL 证书：
   如果你设置了 external_url 为 https://... 并且使用的是一个公网可访问的域名，GitLab Omnibus 包可以自动为你申请和续签 Let’s Encrypt 免费 SSL 证书。确保以下配置被启用（取消注释并设为 true）：
   ruby
letsencrypt['enable'] = true
# 可选：设置接收 Let's Encrypt 通知的邮箱
# letsencrypt['contact_emails'] = ['[email protected]']
# 注意：确保服务器的 80 端口对公网开放，Let's Encrypt 需要通过 HTTP-01 方式验证域名所有权。
   如果你的服务器在内网，或者使用自己的 SSL 证书，则需要手动配置 Nginx 的 SSL 证书路径（参考 gitlab.rb 文件中的 nginx['ssl_certificate'] 和 nginx['ssl_certificate_key'] 配置项）。

4. 应用配置并启动 GitLab：
   保存 /etc/gitlab/gitlab.rb 文件后，运行以下命令。这个命令会读取配置文件，生成 GitLab 各个组件所需的实际配置文件，并（重新）启动所有服务。
   bash
sudo gitlab-ctl reconfigure
   首次运行 reconfigure 可能需要几分钟时间，因为它需要设置数据库、编译资源等。后续修改配置后也需要运行此命令。

5. 访问 GitLab 并设置初始密码：
   reconfigure 成功完成后，在浏览器中访问你设置的 external_url。你应该能看到 GitLab 的登录页面。

   • 初始管理员账号： 用户名为 root。
   • 设置密码： 首次访问时，系统通常会要求你为 root 用户设置一个新密码。按照提示操作即可。如果未提示，或者忘记了密码，可以通过命令行重置（参考 GitLab 官方文档）。

至此，你的 GitLab CE 实例已经基本运行起来了！你可以使用 root 账号登录，开始探索 GitLab 的世界。

四、 核心功能与基本使用

登录后，你可以开始使用 GitLab 的核心功能：

1. 用户管理： 在 Admin Area (管理员区域，通常通过顶部导航栏的扳手图标进入) -> Overview -> Users 中，你可以创建新用户、管理现有用户、设置用户权限等。对于私有实例，建议在 Admin Area -> Settings -> General -> Sign-up restrictions 中禁用用户注册，改为管理员手动创建账号。
2. 群组 (Groups)： 用于组织项目和管理成员权限。可以创建群组，将用户添加到群组，并赋予不同的角色（Guest, Reporter, Developer, Maintainer, Owner）。项目可以属于用户个人，也可以属于群组。
3. 项目 (Projects)： 这是代码仓库的核心。你可以创建新项目（空的，或从模板创建，或导入现有仓库），或者 Fork 其他项目。在项目页面，你可以：
   • 克隆仓库： 获取仓库的 HTTPS 或 SSH 克隆地址。
   • 代码浏览： 查看文件、提交历史、分支、标签。
   • Issue 跟踪： 创建、分配、讨论和管理任务、Bug 或功能请求。
   • 合并请求 (Merge Requests, MRs)： 这是代码审查和协作的核心流程。开发者在自己的分支上工作，完成后创建 MR 请求将代码合并回主分支（如 main 或 master），Maintainer 可以审查代码、评论、批准并合并。
   • CI/CD Pipelines： 配置 .gitlab-ci.yml 文件定义自动化构建、测试和部署流程。
   • Wiki： 编写项目文档。
   • Settings： 配置项目相关的各种选项，如成员权限、仓库设置、CI/CD 变量、集成等。

五、 关键配置与维护

自托管意味着你需要关注实例的长期健康运行。

1. 邮件 (SMTP) 配置（如果初始未配）：
   如果 GitLab 需要发送邮件（强烈建议），你需要配置 SMTP。编辑 /etc/gitlab/gitlab.rb，找到 gitlab_rails['smtp_enable'] 相关部分，取消注释并填入你的 SMTP 服务器信息：
   “`ruby
   gitlab_rails[‘smtp_enable’] = true
   gitlab_rails[‘smtp_address’] = “smtp.example.com”
   gitlab_rails[‘smtp_port’] = 587
   gitlab_rails[‘smtp_user_name’] = “your_smtp_username”
   gitlab_rails[‘smtp_password’] = “your_smtp_password”
   gitlab_rails[‘smtp_domain’] = “example.com” # Usually your email domain
   gitlab_rails[‘smtp_authentication’] = “login” # Or ‘plain’, ‘cram_md5’
   gitlab_rails[‘smtp_enable_starttls_auto’] = true
   gitlab_rails[‘smtp_tls’] = false # Set to true if using SMTPS (usually port 465)

   Set the ‘From’ address for emails sent by GitLab

   gitlab_rails[‘gitlab_email_from’] = ‘[email protected]’
   gitlab_rails[‘gitlab_email_reply_to’] = ‘[email protected]’
   修改后，务必运行 `sudo gitlab-ctl reconfigure`。之后可以通过 Rails 控制台测试邮件发送：bash
   sudo gitlab-rails console -e production

   在控制台中输入:

   Notify.test_email(‘[email protected]’, ‘Email Subject’, ‘Email Body’).deliver_now

   退出控制台: exit

   “`

2. 备份与恢复：
   这是自托管最重要的任务之一！ GitLab 提供了内置的备份工具。

   • 创建备份：
     bash
sudo gitlab-backup create
     该命令会备份数据库、所有仓库、附件、CI/CD 构建物等。备份文件默认存储在 /var/opt/gitlab/backups/ 目录下，文件名类似 1678886400_2023_03_15_15.8.1-ce_gitlab_backup.tar。
     注意： 这个备份 不包含 /etc/gitlab/gitlab.rb 配置文件和 SSL 证书文件（/etc/gitlab/ssl/）。你需要单独备份这些文件！
   • 自动化备份： 使用 cron 定时任务定期执行 gitlab-backup create。例如，每天凌晨 2 点执行备份：
     crontab
0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1
CRON=1 会抑制命令的正常输出，只在出错时输出。
   • 备份策略： 制定合理的备份策略，包括备份频率、保留周期、以及将备份文件复制到远程、安全的存储位置（如另一台服务器、对象存储等）。
   • 恢复备份： 恢复是一个更复杂的过程，通常需要在全新的、相同版本的 GitLab 实例上进行。大致步骤如下（请务必参考官方最新文档进行操作！）：
     1. 停止连接数据库的服务：sudo gitlab-ctl stop puma unicorn sidekiq
     2. 确保数据库仍在运行：sudo gitlab-ctl status postgresql
     3. 执行恢复命令，指定备份文件名（不含 .tar 后缀）：sudo gitlab-backup restore BACKUP=timestamp_of_backup
     4. 恢复 /etc/gitlab/gitlab.rb 和 /etc/gitlab/ssl/ 文件。
     5. 重新应用配置并重启：sudo gitlab-ctl reconfigure，然后 sudo gitlab-ctl start
     6. 进行健康检查：sudo gitlab-rake gitlab:check SANITIZE=true

3. 升级 GitLab CE：
   GitLab 频繁发布新版本，包含新功能、性能改进和重要的安全修复。保持更新非常重要。

   • 阅读发布说明： 在升级前，务必查阅你当前版本到目标版本之间的所有版本的发布说明（尤其是 major 版本升级），了解是否有重大变更、弃用功能或特定的升级步骤。
   • 备份： 在执行任何升级操作前，务必创建完整备份！
   • 升级步骤（以 APT 为例）：
     bash
# 1. 更新包列表
sudo apt update
# 2. 查看可用版本（可选）
# sudo apt-cache policy gitlab-ce
# 3. 安装指定版本（如果需要）或最新版
# sudo apt install gitlab-ce=<version> 或直接
sudo apt install gitlab-ce
# 4. reconfigure 不会自动运行，升级后通常需要手动运行
# 但升级包有时会自动触发某些迁移，耐心等待安装完成
# 5. 检查状态
sudo gitlab-ctl status
# 6. 如果有必要，根据提示运行 reconfigure 或其他命令
# sudo gitlab-ctl reconfigure
# 7. 有时需要运行数据库迁移等升级后任务
# sudo gitlab-ctl upgrade
# 8. 再次检查状态和功能是否正常
   • 逐步升级： 避免跨多个 major 版本直接升级，最好遵循官方推荐的升级路径。

4. 监控与日志：

   • 日志文件： GitLab 各组件的日志位于 /var/log/gitlab/ 下的子目录（如 nginx/, postgresql/, puma/, sidekiq/ 等）。当出现问题时，这些日志是排查的首要入口。可以使用 sudo gitlab-ctl tail <service_name> 实时查看日志。
   • 系统资源监控： 使用 top, htop, vmstat, iostat 等工具监控 CPU、内存、磁盘 I/O。GitLab 本身也带有 Prometheus 监控和 Grafana 图表（可在 Admin Area -> Monitoring 中启用和访问），提供对 GitLab 内部性能指标的深入洞察。

六、 安全加固

保护你的代码和数据至关重要。

1. 保持更新： 及时应用 GitLab 的安全补丁和版本更新。
2. HTTPS 强制： 确保始终使用 HTTPS 访问，可以在 gitlab.rb 中配置 Nginx 强制跳转 HTTP 到 HTTPS。
3. 强密码策略与 2FA： 强制用户使用强密码，并鼓励（或强制）启用双因素认证（2FA）。
4. SSH 密钥安全： 教育用户妥善保管自己的 SSH 私钥。定期审查部署密钥 (Deploy Keys) 和项目/群组的访问令牌 (Access Tokens)。
5. 防火墙精细化： 除了允许必要的端口（80, 443, SSH），阻止所有其他不必要的入站连接。考虑限制 SSH 访问来源 IP。
6. 禁用或限制用户注册： 对于内部使用的 GitLab 实例，务必禁用公共注册。
7. 定期安全审计： 检查用户权限、项目可见性设置、CI/CD 变量的安全性等。
8. 操作系统安全： 保持底层操作系统的安全更新，配置好系统防火墙（如 ufw 或 firewalld）。
9. 备份安全： 确保备份文件的存储安全，防止未授权访问。

七、 性能调优与故障排除

• 性能瓶颈： 最常见的瓶颈是内存不足和磁盘 I/O 慢。监控资源使用情况，根据需要增加 RAM 或使用更快的存储（SSD）。
• 调整 Worker 数量： 在 /etc/gitlab/gitlab.rb 中可以调整 Puma (Web 服务器) 和 Sidekiq (后台作业处理器) 的 worker 数量和线程数，以更好地利用 CPU 资源。但这需要根据你的服务器核心数和内存进行仔细调整，并进行测试。参考官方文档中的建议值。
• 数据库调优： 对于大型实例，可能需要调整 PostgreSQL 的配置（如 shared_buffers, work_mem）。
• 故障排除工具：
  • sudo gitlab-ctl status: 查看所有 GitLab 组件的运行状态。
  • sudo gitlab-ctl tail: 实时查看所有或指定服务的日志。
  • sudo gitlab-rake gitlab:check SANITIZE=true: 运行全面的健康检查，检查配置、目录权限、仓库完整性等（SANITIZE=true 会隐藏敏感信息）。
  • sudo gitlab-rails console: 进入 Rails 控制台，可以执行更高级的诊断和修复操作（需谨慎使用）。
  • 官方文档与社区： GitLab 拥有非常详尽的官方文档和活跃的社区论坛，是解决问题的宝贵资源。

结语

自托管 GitLab CE 为你和你的团队提供了无与伦比的代码管理控制权、灵活性和数据安全性。虽然它需要投入一定的运维精力，但借助强大的 Omnibus 安装包和丰富的文档资源，整个过程比想象中要容易得多。

通过遵循本指南的步骤，从准备环境、安装配置，到日常使用、备份维护和安全加固，你应该能够成功部署并管理一个稳定、高效的 GitLab CE 实例。记住，持续学习、定期维护、关注安全是保障自托管服务长期健康运行的关键。现在，开启你的 GitLab 自托管之旅，掌控你的代码世界吧！

---