在 Ubuntu VPS 上安装 GitLab CE — 自托管 Git 服务器

GitLab.com 对小团队来说是免费的，但在您自己的 VPS 上托管 GitLab 社区版（Community Edition） 可以完全控制敏感代码库、支持离线工作，并消除按座位收费的成本。GitLab CE 包含 Git 仓库托管、CI/CD 管道、问题跟踪、wiki 和容器注册表，全部基于开源。对于需要完全数据隐私的团队、有合规要求的企业以及希望避免云服务月费上涨的开发者而言，自托管 GitLab 是理想选择。

系统要求和硬件规划

成功部署 GitLab CE 首先需要确保 VPS 配置符合最低要求。GitLab 是一个功能丰富的应用，包含众多后台服务（web 服务器、数据库、后台作业处理等），因此硬件规划至关重要。

• RAM：8 GB 以上推荐（最低 4 GB）—— 4 GB 配置虽然可以运行，但在处理大型项目或多人并发时会出现明显的性能问题
• CPU：2 核或以上—— 推荐 4 核或更高以获得最佳性能
• 磁盘空间：50 GB 以上—— Git 仓库会随时间不断增长，建议为代码库和备份预留充足空间
• Ubuntu 22.04 LTS—— 官方推荐的操作系统版本，获得长期支持
• 域名和 DNS A 记录—— 必须指向 VPS 的 IP 地址，这对 SSL 证书自动颁发至关重要

在实际部署中，8GB RAM 是生产环境的理想起点。如果团队规模较小且主要进行轻量级开发，4GB 配置也可以接受，但需要禁用一些非关键服务（如 Elasticsearch、Prometheus 和 Grafana）来保持系统稳定性。

预安装检查和准备工作

在开始安装前，需要进行几个重要的准备步骤。首先确保系统包已更新到最新版本，这不仅能获得安全补丁，还能避免依赖包版本冲突。其次，检查网络连接和 DNS 解析，确保 VPS 能够访问 GitLab 的官方软件库和 Let's Encrypt 证书服务。最后，验证域名 DNS 指向是否正确配置。

获取 root 或 sudo 权限是必要的，因为 GitLab 的安装和配置需要系统级别的访问权限。建议在开始前关闭不必要的防火墙规则，或至少开放 HTTP（80）和 HTTPS（443）端口。如果使用 SSH 密钥登录，确保 SSH 服务处于正常运行状态，因为后续可能需要通过 SSH 访问 VPS。

第一步：安装系统依赖和准备

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl openssh-server ca-certificates tzdata perl

这个命令完成两个任务：首先更新包管理器的索引列表，确保能获取到最新的软件包版本。openssh-server 确保 SSH 服务可用，ca-certificates 用于验证 HTTPS 连接的 SSL 证书。tzdata 提供时区数据，重要的是 GitLab 内部的日志和备份时间戳需要准确的时区信息。

第二步：添加 GitLab 官方软件库

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

该脚本从 GitLab 官方源下载配置信息，自动将 GitLab 软件库添加到系统包管理器。这确保安装的 GitLab 版本是官方提供、更新最及时、安全补丁最全的版本。直接从官方源安装（而不是从旧版 apt 缓存）能保证获得最新的特性和安全更新。

第三步：设置域名并安装 GitLab CE

sudo EXTERNAL_URL="https://gitlab.example.com" apt-get install gitlab-ce

在执行此命令前，必须将 gitlab.example.com 替换为您实际的域名，并确保该域名的 DNS A 记录已指向 VPS 的 IP 地址。设置 HTTPS URL 会自动触发 Let's Encrypt 免费 SSL 证书的申请和安装。整个安装过程通常需要 10–15 分钟，期间系统会下载 GitLab 包、初始化数据库和配置所有必要的服务。

如果安装失败，最常见的原因是 DNS 解析问题。可以通过 nslookup gitlab.example.com 验证域名是否正确指向 VPS IP。如果 DNS 尚未生效，可以暂时使用 HTTP（不使用 EXTERNAL_URL 中的 https），安装完成后再配置 SSL。

第四步：获取初始 Root 管理员密码

sudo cat /etc/gitlab/initial_root_password
# 输出会显示一个随机生成的密码
# 该密码有效期仅为 24 小时

GitLab 在安装完成后会自动生成一个随机的 root 用户密码。这个密码保存在 /etc/gitlab/initial_root_password 文件中，有效期只有 24 小时，过期后无法再次查看，因此需要立即记录。使用用户名 root 和此密码登录 GitLab Web 界面，登录成功后应立即修改密码为更强安全的密码，建议使用至少 16 字符、包含大小写字母、数字和特殊符号的复杂密码。

第五步：配置 GitLab 服务参数

sudo nano /etc/gitlab/gitlab.rb

这个文件是 GitLab 的主配置文件，包含所有系统级别的设置。编辑此文件需要管理员权限。配置项众多，下面列出最常用的关键配置：

# 基本设置 — GitLab 访问地址
external_url 'https://gitlab.example.com'

# SMTP 邮件配置 (使用 Gmail 应用专用密码示例)
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "your-app-specific-password"
gitlab_rails['smtp_domain'] = "gmail.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['gitlab_email_from'] = '[email protected]'
gitlab_rails['gitlab_email_display_name'] = 'GitLab Server'

# 禁用开放注册（如果只允许特定用户访问）
gitlab_rails['gitlab_signup_enabled'] = false

# 备份保留时间（这里设为 7 天）
gitlab_rails['backup_keep_time'] = 604800

# 时区设置（重要）
gitlab_rails['time_zone'] = 'UTC'

配置完成后，需要运行重新配置命令应用所有设置变更：

sudo gitlab-ctl reconfigure

这个命令会重新读取 gitlab.rb 文件，检查配置是否有效，然后重启相关服务使新配置生效。过程中会输出大量日志信息，最后应显示 "gitlab Reconfigured!" 表示成功。

SMTP 邮件配置详解

GitLab 需要邮件功能来发送账户通知、密码重置邮件和流水线状态通知。如果不配置 SMTP，用户将无法接收到重要的系统通知。常见的邮件服务选项包括：

• Gmail：需要创建应用专用密码（在 Google 账户安全设置中生成），不能使用普通密码
• SendGrid：按量付费的邮件服务，可靠性高，适合生产环境
• 自托管 Postfix/Dovecot：完全控制，但需要额外的维护工作
• 企业邮件服务：如 Office 365、AWS SES 等

配置后可以在 GitLab 管理界面测试邮件发送功能。确保邮件能正确发送，否则用户在使用过程中会遇到功能障碍。

第六步：安装 GitLab Runner 用于 CI/CD

GitLab Runner 是负责执行 CI/CD 流水线的代理程序。虽然可以在同一 VPS 上安装，但这会占用相当多的系统资源。对于生产环境，强烈建议在单独的 VPS 上部署 Runner。

# 添加 GitLab Runner 官方软件库
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# 安装 GitLab Runner
sudo apt-get install gitlab-runner -y

注册 Runner 与 GitLab 实例连接

安装后需要注册 Runner，使其能与 GitLab 实例进行通信：

# 获取注册令牌的步骤：
# 1. 在浏览器中访问 https://gitlab.example.com/admin/runners
# 2. 点击 "New instance runner" 或 "Register runner"
# 3. 复制显示的 registration token

# 使用 Shell executor 的注册示例
sudo gitlab-runner register \
  --url https://gitlab.example.com \
  --registration-token YOUR_REGISTRATION_TOKEN \
  --executor shell \
  --description "shell-runner-01"

如果更倾向于使用 Docker 容器来隔离 CI/CD 作业（推荐做法），可以使用 Docker executor：

sudo gitlab-runner register \
  --url https://gitlab.example.com \
  --registration-token YOUR_TOKEN \
  --executor docker \
  --docker-image alpine:latest \
  --description "docker-runner-01"

Docker executor 提供更好的隔离性和可重现性，每个作业都在独立的容器中运行，避免了全局环境污染。这对于运行多个项目、处理不同的依赖版本特别有用。

CI/CD 流水线配置示例

在 GitLab 项目中创建 .gitlab-ci.yml 文件来定义自动化流程。以下是一个完整的项目构建、测试和部署流程示例：

stages:
  - build
  - test
  - deploy

variables:
  NODE_ENV: "production"

build_job:
  stage: build
  image: node:18-alpine
  script:
    - echo "开始构建..."
    - npm install
    - npm run build
    - echo "构建完成"
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  only:
    - main
    - develop

test_job:
  stage: test
  image: node:18-alpine
  script:
    - npm install
    - npm test
    - echo "所有测试通过"
  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'
  only:
    - merge_requests

deploy_job:
  stage: deploy
  image: alpine:latest
  script:
    - apk add --no-cache openssh-client rsync
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - echo "$DEPLOY_KEY" > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan -H $DEPLOY_HOST >> ~/.ssh/known_hosts
    - rsync -avz dist/ $DEPLOY_USER@$DEPLOY_HOST:/var/www/app/
  only:
    - main
  when: manual

这个示例定义了三个阶段的流程：

• Build：安装依赖、编译项目、生成产物
• Test：运行单元测试、生成代码覆盖率报告
• Deploy：将构建产物部署到生产服务器（仅在 main 分支且需要手动触发）

备份和灾难恢复

定期备份是运维工作中最关键的环节。失去代码库备份可能导致无法恢复的数据损失。GitLab 提供了简单的备份工具：

# 手动创建备份
sudo gitlab-backup create

# 查看备份文件列表
ls -lh /var/opt/gitlab/backups/

# 设置每天凌晨 2 点自动备份的 cron 任务
(crontab -l; echo "0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1") | crontab -

备份过程中 GitLab 会创建一个包含所有数据库、文件和配置的压缩档案，文件名格式为 TIMESTAMP_gitlab_backup.tar。根据数据库大小，备份可能需要数分钟到数十分钟。

备份完成后，应该将备份文件复制到远程存储（如 AWS S3、NAS 或另一个服务器），这样即使主 VPS 故障也能恢复数据。可以使用 rsync 或 s3cmd 自动同步备份：

# 示例：使用 rsync 同步到 NAS 服务器
0 3 * * * rsync -avz /var/opt/gitlab/backups/ backup-user@backup-server:/backups/gitlab/ --delete

监控和日志查看

定期检查 GitLab 服务状态和日志是及时发现问题的方法。GitLab 提供了一套便利的命令行工具：

# 查看所有 GitLab 服务的状态
sudo gitlab-ctl status

# 重启 GitLab 服务
sudo gitlab-ctl restart

# 查看特定服务的实时日志
sudo gitlab-ctl tail postgresql
sudo gitlab-ctl tail nginx
sudo gitlab-ctl tail gitaly

# 检查内存和 CPU 使用情况
sudo gitlab-ctl status | grep -E "(memory|process)"

# 进入交互式 Ruby 控制台调试
sudo gitlab-rails console

日志对于故障排查至关重要。常见的问题包括数据库连接错误、SMTP 邮件发送失败、SSH 密钥权限问题等。通过查看日志可以快速定位问题根源。

内存优化和性能调整

在资源有限的 VPS 上运行 GitLab 需要仔细调整配置以获得最佳性能。以下是针对 4–6GB RAM 的 VPS 的优化建议：

# 在 /etc/gitlab/gitlab.rb 中添加或修改以下参数：

# 禁用 Prometheus 监控（节省约 200 MB）
prometheus_monitoring['enable'] = false

# 禁用 Grafana 仪表板（节省约 100 MB）
grafana['enable'] = false

# 禁用 AlertManager 告警系统
alertmanager['enable'] = false

# 禁用 Node Exporter（Prometheus 依赖）
node_exporter['enable'] = false

# 减少 Puma Web 服务器的工作进程数（默认为 4）
puma['worker_processes'] = 2
puma['min_threads'] = 2
puma['max_threads'] = 4

# 减少 Sidekiq 后台作业处理的并发数
sidekiq['concurrency'] = 5
sidekiq['max_retries'] = 3

# 禁用 GitLab Pages（如果不需要）
pages['enable'] = false

# 启用数据库连接池优化
gitlab_rails['db_pool'] = 10

应用这些优化后，需要重新配置 GitLab：

sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart

重启后系统内存占用会明显减少。可以使用 free -h 和 top 命令监控内存使用情况，确保有充足的空闲内存（建议保持至少 500 MB 的空闲内存）。

安全加固建议

在生产环境中部署 GitLab 需要考虑多方面的安全因素。首先，启用防火墙并只开放必要的端口（HTTP 80、HTTPS 443 和 SSH 22），如果不需要 SSH git 访问可以关闭端口 22。其次，定期更新系统包和 GitLab 本身以获得最新安全补丁。启用 GitLab 的两因素认证（2FA）功能，要求管理员和所有用户使用强密码。考虑配置 LDAP/Active Directory 集成进行企业级身份验证。定期审计用户权限，删除不再活跃的账户。

另外，配置 SSH 密钥是比密码更安全的认证方式。在 /etc/ssh/sshd_config 中禁用密码登录，仅允许 SSH 密钥认证。配置 fail2ban 防止暴力破解攻击。如果 GitLab 实例公开在互联网上，考虑在前面配置 WAF（Web 应用防火墙）来阻止恶意流量。

常见问题排查

问题：安装时 SSL 证书申请失败
原因通常是 DNS 解析问题。确保域名的 DNS A 记录已指向 VPS IP，可能需要等待 DNS 传播（最长 48 小时）。使用 nslookup gitlab.example.com 验证。如果 DNS 尚未生效，可以临时使用 HTTP 安装，稍后再配置 HTTPS。

问题：启动后出现 502 Bad Gateway 错误
通常表示 Puma Web 服务器没有正常启动或 PostgreSQL 数据库不可用。运行 sudo gitlab-ctl status 检查各个服务的状态。查看日志 sudo gitlab-ctl tail 了解详细错误信息。如果是内存不足导致的，尝试减少工作进程数。

问题：邮件无法发送
首先检查 SMTP 配置是否正确，特别是用户名密码是否准确。尝试在 GitLab 控制台测试邮件发送。确保 VPS 能够访问邮件服务器（检查防火墙规则）。查看 mail.log 或 /var/log/syslog 了解具体错误。

版本更新和维护

GitLab 通常每月 22 号发布新版本。虽然不需要每个版本都升级，但建议至少每季度更新一次以获得重要的安全补丁和功能改进。升级过程相对简单：

# 升级前先创建备份
sudo gitlab-backup create

# 升级 GitLab
sudo apt update
sudo apt install gitlab-ce

# 系统会自动处理数据库迁移
# 升级完成后可验证
sudo gitlab-ctl status

升级通常会导致短暂的服务中断（5–10 分钟），建议在非工作时段进行。升级前也应该查看 GitLab 发行说明，了解是否有重大变更需要手工调整。