GitLab 私有化部署与配置指南

1. 简介

GitLab 是一个完整的 DevSecOps 平台，提供代码托管、CI/CD 流水线、代码审查和项目管理功能。对于企业或团队，私有化部署 GitLab Community Edition (CE) 是保护代码资产和实现工程化管理的常见选择。

2. 部署前准备

2.1 硬件要求

GitLab 是资源密集型应用，官方推荐配置如下：

• CPU: 4 Cores (最低 2 Cores，但 UI 响应会较慢)
• 内存: 4GB RAM (强烈建议 8GB+，否则容易出现 502 错误)
• Swap: 建议配置 4GB 交换分区，防止内存溢出导致进程崩溃。
• 磁盘: SSD 存储，建议 50GB+ (取决于代码仓库大小)。

2.2 环境准备

确保服务器已安装 Docker 和 Docker Compose。

3. Docker 安装步骤 (推荐)

使用 Docker 容器化部署是最便捷、且易于升级的方式。

3.1 启动命令

运行以下命令启动 GitLab CE 容器。请将 $GITLAB_HOME 替换为实际路径 (如 /srv/gitlab)。

docker run --detach \
  --hostname gitlab.example.com \
  --publish 443:443 --publish 80:80 --publish 2222:22 \
  --name gitlab \
  --restart always \
  --volume $GITLAB_HOME/config:/etc/gitlab \
  --volume $GITLAB_HOME/logs:/var/log/gitlab \
  --volume $GITLAB_HOME/data:/var/opt/gitlab \
  --shm-size 256m \
  gitlab/gitlab-ce:latest

注意：我们将容器的 22 端口映射到了宿主机的 2222，因为宿主机的 22 端口通常被 SSHD 占用。

3.2 初始配置与访问

1. 等待启动：GitLab 首次启动需要进行大量初始化（数据库迁移、编译资源），可能需要 3-5 分钟。可通过 docker logs -f gitlab 查看进度。
2. 获取初始密码： 用户名默认为 root，随机生成的密码存储在容器内：

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

   注意：该文件会在 24 小时后自动删除，请尽快修改密码。
3. 登录：访问 http://<服务器IP>，使用 root 账号登录。

4. 核心配置详解

配置文件位于 $GITLAB_HOME/config/gitlab.rb。修改后需执行 docker exec -it gitlab gitlab-ctl reconfigure 生效。

4.1 修改外部访问地址 (External URL)

这是 GitLab 生成克隆链接和发送邮件时使用的地址。

# vim /etc/gitlab/gitlab.rb
external_url 'http://gitlab.yourdomain.com'

4.2 SSH 端口修正

由于我们映射了 2222 端口，需要告知 GitLab 生成正确的 SSH 克隆链接（如 ssh://git@host:2222/user/repo.git）。

gitlab_rails['gitlab_shell_ssh_port'] = 2222

4.3 配置 HTTPS (Let's Encrypt)

GitLab 内置了 Let's Encrypt 支持。确保域名已解析到服务器，并开放 80/443 端口。

external_url 'https://gitlab.yourdomain.com'
letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['admin@example.com']
letsencrypt['auto_renew'] = true

5. 配置 GitLab Runner (CI/CD)

GitLab Runner 是执行 CI/CD 任务的代理程序。建议将其安装在独立的服务器或容器中。

4.4 配置邮件通知 (SMTP)

GitLab 需要发送注册验证、密码重置和 CI/CD 通知邮件。以 Gmail 为例：

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'] = "smtp.gmail.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = false
gitlab_rails['smtp_openssl_verify_mode'] = 'peer'

# 修改发件人地址
gitlab_rails['gitlab_email_from'] = 'your-email@gmail.com'
gitlab_rails['gitlab_email_reply_to'] = 'noreply@yourdomain.com'

配置完成后，进入 Rails Console 测试发送：

docker exec -it gitlab gitlab-rails console
# 在控制台中输入:
Notify.test_email('dest_email@example.com', 'Message Subject', 'Message Body').deliver_now

5. 配置 GitLab Runner (CI/CD)

5.1 注册 Runner

1. 在 GitLab 项目设置中找到 Registration Token (Settings -> CI/CD -> Runners)。
2. 启动 Runner 容器并注册：

docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register

3. 按照交互提示输入：
   • GitLab instance URL: http://<gitlab-ip>/ (如果使用 Docker 内部网络，可能需要使用容器名或宿主机 IP)
   • Registration token: (从页面复制)
   • Description: docker-runner-01
   • Tags: docker (可选)
   • Executor: docker
   • Docker image: alpine:latest (默认镜像)

5.2 启动 Runner 服务

docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

注意：挂载 docker.sock 是为了让 Runner 能够启动兄弟容器来执行构建任务 (Docker-in-Docker)。

5.3 配置 Runner 并发

默认 config.toml 中 concurrent = 1。可以修改 /srv/gitlab-runner/config/config.toml 提高并发数：

concurrent = 4

修改后重启 Runner 容器：docker restart gitlab-runner

6. 维护与故障排除

6.1 常用维护命令

进入容器后执行：

• gitlab-ctl reconfigure: 重载配置 (修改 gitlab.rb 后必做)
• gitlab-ctl restart: 重启所有服务
• gitlab-ctl tail: 查看日志 (排查 500/502 错误神器)
• gitlab-ctl status: 查看服务健康状态

6.2 备份与恢复

• 创建备份：

  docker exec -t gitlab gitlab-backup create

  备份文件默认保存在 /var/opt/gitlab/backups。 提示：可以通过 Cron 任务定期执行此命令。

• 恢复备份： 需要先停止连接数据库的服务 (unicorn/puma, sidekiq)，然后执行恢复命令。

  # 停止数据写入服务
  gitlab-ctl stop puma
  gitlab-ctl stop sidekiq
  
  # 执行恢复 (文件名不含 _gitlab_backup.tar 后缀)
  gitlab-backup restore BACKUP=1697234567_2023_10_14_16.4.1
  
  # 重启
  gitlab-ctl restart

6.3 版本升级策略

GitLab 不支持跨大版本直接升级 (如 13.x -> 15.x)。必须遵循升级路径： Current -> Latest Patch -> Next Major .0 -> Next Major Latest Patch ...

• 检查升级路径：使用 GitLab Upgrade Path 工具。
• 操作步骤：
  1. 备份数据 (必须!)。
  2. 修改 docker-compose.yml 中的镜像版本 tag。
  3. docker-compose up -d。
  4. 等待迁移完成 (查看日志)。

6.4 常见错误：502 Whoops, GitLab is taking too much time to respond

• 原因：通常是内存不足，Unicorn/Puma 进程启动缓慢或超时。
• 解决：
  1. 增加服务器内存或 Swap。
  2. 调整超时时间：

     gitlab_rails['webhook_timeout'] = 90
     puma['worker_timeout'] = 120

---

参考资料

• GitLab 官方 Docker 安装文档
• GitLab Runner 官方文档
• GitLab 备份恢复指南