GitLab 安装深度解析：原理、实战与踩坑记录

团队最近在技术选型时对比了多个方案，这里分享一下我们的调研结果和最终决策依据。

目录

• 一、概述
• 二、 安装方式
• 三、系统要求
• 四、 具体安装步骤
• • 1. Ubuntu 系统安装（原生包方式）
  • • 1.1 安装依赖包
    • 1.2 添加 GitLab 官方仓库
    • 1.3 安装 GitLab
    • 1.4 配置防火墙（如启用）
  • 2. Docker 安装方式
  • • 2.1 创建 `docker-compose.yml` 文件
    • 2.2 启动 GitLab 容器
    • 2.3 等待启动完成
  • 3. Mac 系统安装（M1 芯片支持）
  • • 3.1 创建 `docker-compose.yml`
    • 3.2 进入容器修改配置
• 五、安装后初始设置
• • 1. 访问 GitLab 并获取初始密码
  • • 原生安装获取密码：
    • Docker 安装获取密码：
  • 2. 基本配置修改
  • • 2.1 修改管理员密码
    • 2.2 配置 SMTP 邮件服务器（可选但推荐）
• 六、 GitLab 基本使用
• • 1. 管理区域设置
  • 2. 项目管理
  • • 2.1 创建项目
    • 2.2 项目基本操作
  • 3. 用户和权限管理
  • 4. CI/CD 流水线配置
  • • 4.1 在项目中创建 `.gitlab-ci.yml` 文件
    • 4.2 配置 GitLab Runner
• 七、常用管理命令
• • 1. GitLab 服务管理
  • 2.备份和恢复
• 八、 常见问题解决
• • 1. 502 错误
  • 2. 服务无法启动
  • 3. 邮件无法发送
  • 4. HTTPS 配置

一、概述

GitLab 是一个功能强大的开源 DevOps 平台，集代码托管、CI/CD、项目管理和团队协作于一体。本文将为你梳理如何在主流操作系统上安装 GitLab，以及安装后的基本使用和常见问题处理。

二、 安装方式

GitLab 主要有三种安装方式，你可以根据自己的需求和环境选择合适的方法：

安装方式	适用平台	优点	缺点
原生包安装	Ubuntu, CentOS, Debian 等 Linux 系统	官方推荐，性能最佳，功能完整	对系统资源要求较高
Docker 安装	所有支持 Docker 的平台（Windows, Mac, Linux）	环境隔离，快速部署，易于维护	配置稍复杂，性能略有损耗
Windows 安装	Windows 系统	适合 Windows 环境开发者	官方不支持直接安装，需通过 Docker 或虚拟机

---

三、系统要求

在开始安装前，请确保你的系统满足以下最低要求：

• 内存：至少 4GB（推荐 8GB 或更多）
• CPU：至少 2 核心（推荐 4 核或更多）
• 磁盘空间：至少 10GB（推荐 20GB 或更多）
• 网络：固定的 IP 地址或域名，开放 80 和 443 端口

---

四、 具体安装步骤

1. Ubuntu 系统安装（原生包方式）

以下是官方推荐的 Omnibus 包安装方法：

1.1 安装依赖包

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

在 Postfix 安装过程中，选择 “Internet Site” 并输入服务器主机名。

1.2 添加 GitLab 官方仓库

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

1.3 安装 GitLab

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

将 EXTERNAL_URL 替换为你实际的域名或 IP 地址。

1.4 配置防火墙（如启用）

sudo ufw allow http
sudo ufw allow https
sudo ufw allow OpenSSH

---

2. Docker 安装方式

如果你更喜欢使用 Docker，以下是安装步骤：

2.1 创建 docker-compose.yml 文件

version: '3.8'
services:
gitlab:
image: gitlab/gitlab-ce:latest
container_name: gitlab-docker
hostname: 'gitlab.example.com'
restart: always
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url 'http://192.168.11.111:8807'
letsencrypt['enable'] = false
volumes:
- './config:/etc/gitlab'
- './logs:/var/log/gitlab'
- './data:/var/opt/gitlab'
ports:
- '8807:8807'
- '8808:22'

记得将 external_url 中的 IP 和端口改为你自己的。

2.2 启动 GitLab 容器

docker-compose up -d

2.3 等待启动完成

容器启动后需要几分钟时间 GitLab 才能完全就绪。

⚠️ 踩坑记录：

我在实际项目中遇到过一个问题，这个配置在开发环境正常，但生产环境会报错。 后来发现是因为生产环境的版本不一致导致的。建议大家在部署前一定要检查版本兼容性。

---

3. Mac 系统安装（M1 芯片支持）

对于 Mac 用户（特别是 M1 芯片），可以使用专门的 ARM 镜像：

3.1 创建 docker-compose.yml

version: "3.8"
services:
gitlab-ce:
image: yrzr/gitlab-ce-arm64v8:latest
container_name: gitlab-ce
privileged: true
restart: always
ports:
- "9922:22"
- "9980:9980"
volumes:
- /your/path/gitlab/etc:/etc/gitlab:z
- /your/path/gitlab/log:/var/log/gitlab:z
- /your/path/gitlab/opt:/var/opt/gitlab:z
deploy:
resources:
limits:
memory: 4096M

3.2 进入容器修改配置

docker exec -it gitlab-ce /bin/bash
vi /etc/gitlab/gitlab.rb

添加以下配置：

external_url 'http://127.0.0.1:9980'
gitlab_rails['gitlab_ssh_host'] = '127.0.0.1'
gitlab_rails['gitlab_shell_ssh_port'] = 9922

---

五、安装后初始设置

1. 访问 GitLab 并获取初始密码

1. 打开浏览器，访问你配置的 EXTERNAL_URL
2. 使用以下凭据登录：
   • 用户名：root
   • 密码：从以下文件获取

原生安装获取密码：

sudo cat /etc/gitlab/initial_root_password

Docker 安装获取密码：

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

⚠️ 注意：此密码文件会在 24 小时后自动删除，请及时修改密码。

---

2. 基本配置修改

登录后建议立即进行以下配置：

2.1 修改管理员密码

• 点击右上角头像 → Settings → 左侧菜单 “Password”

2.2 配置 SMTP 邮件服务器（可选但推荐）

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.your-email.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "your-username"
gitlab_rails['smtp_password'] = "your-password"
gitlab_rails['smtp_domain'] = "your-domain.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['gitlab_email_from'] = "gitlab@your-domain.com"

然后重新配置：

sudo gitlab-ctl reconfigure

---

六、 GitLab 基本使用

1. 管理区域设置

以管理员身份登录后，你可以通过点击顶部导航栏的 “Admin Area”（扳手图标）进入管理区域，进行以下重要设置：

• 关闭 Gravatar（国内访问不了）：Settings → Preferences → Gravatar
• 关闭公开注册（内部使用）：Settings → General → Sign-up restrictions
• 配置外部认证（如 LDAP、OAuth 等）

---

2. 项目管理

2.1 创建项目

• 点击导航栏 “+” 号 → “New project”
• 选择创建空白项目、从模板创建或导入项目

2.2 项目基本操作

• 文件管理：在项目内创建、上传文件
• 分支管理：查看和管理代码分支
• 合并请求：创建和审查代码合并
• 议题跟踪：管理任务和 bug 报告

---

3. 用户和权限管理

• 创建用户：Admin Area → Users → New user
• 分配权限：将用户添加到项目并设置相应角色
  • Guest
  • Reporter
  • Developer
  • Maintainer
  • Owner

---

4. CI/CD 流水线配置

GitLab 内置了强大的 CI/CD 功能：

4.1 在项目中创建 .gitlab-ci.yml 文件

stages:
- build
- test
- deploy
build_job:
stage: build
script:
- echo "Building the project..."
- go build -o myapp
artifacts:
paths:
- myapp
test_job:
stage: test
script:
- echo "Running tests..."
deploy_job:
stage: deploy
script:
- echo "Deploying application..."
only:
- main

4.2 配置 GitLab Runner

• 进入项目 → Settings → CI/CD → Runners
• 按照说明安装和注册 Runner

---

七、常用管理命令

1. GitLab 服务管理

# 启动所有服务
sudo gitlab-ctl start
# 停止所有服务
sudo gitlab-ctl stop
# 重启所有服务
sudo gitlab-ctl restart
# 查看服务状态
sudo gitlab-ctl status
# 重新配置 GitLab（修改配置后必须执行）
sudo gitlab-ctl reconfigure

---

2.备份和恢复

# 创建备份
sudo gitlab-rake gitlab:backup:create
# 恢复备份
sudo gitlab-rake gitlab:backup:restore BACKUP=备份文件名

---

八、 常见问题解决

1. 502 错误

• 原因：通常是内存不足导致
• 解决方案：
  • 建议增加系统内存至 4GB 以上
  • 检查端口冲突，确保 80 和 443 端口未被占用

2. 服务无法启动

• 原因：系统资源不足或配置错误
• 解决方案：
  • 检查系统资源是否充足
  • 查看日志文件：sudo gitlab-ctl tail

3. 邮件无法发送

• 原因：SMTP 配置错误或防火墙限制
• 解决方案：
  • 确认 SMTP 配置正确
  • 检查防火墙设置

4. HTTPS 配置

如需启用 HTTPS，可配置：

• 自签名证书
• Let’s Encrypt 证书

---

GitLab 功能丰富，安装和配置过程可能会遇到各种问题，但遵循以上步骤应该能帮助你顺利完成安装！