GitLab 安装指南

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

bash 复制代码

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 官方仓库

bash 复制代码

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

1.3 安装 GitLab

bash 复制代码

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

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

1.4 配置防火墙（如启用）

bash 复制代码

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

2. Docker 安装方式

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

2.1 创建 `docker-compose.yml` 文件

yaml 复制代码

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 容器

bash 复制代码

docker-compose up -d

2.3 等待启动完成

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

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

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

3.1 创建 `docker-compose.yml`

yaml 复制代码

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 进入容器修改配置

bash 复制代码

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

添加以下配置：

ruby 复制代码

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 并获取初始密码

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

原生安装获取密码：

bash 复制代码

sudo cat /etc/gitlab/initial_root_password

Docker 安装获取密码：

bash 复制代码

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：

ruby 复制代码

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"

然后重新配置：

bash 复制代码

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` 文件

yaml 复制代码

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 服务管理

bash 复制代码

# 启动所有服务
sudo gitlab-ctl start

# 停止所有服务
sudo gitlab-ctl stop

# 重启所有服务
sudo gitlab-ctl restart

# 查看服务状态
sudo gitlab-ctl status

# 重新配置 GitLab（修改配置后必须执行）
sudo gitlab-ctl reconfigure

2.备份和恢复

bash 复制代码

# 创建备份
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 功能丰富，安装和配置过程可能会遇到各种问题，但遵循以上步骤应该能帮助你顺利完成安装！

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 配置

二、安装方式

四、具体安装步骤

2.1 创建 `docker-compose.yml` 文件

3.1 创建 `docker-compose.yml`

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

八、常见问题解决