GitLab 安装部署

本章目标是在测试或生产环境得到一台「可登录、HTTPS 可达、Git/SSH 可用」的 GitLab 实例。以下示例域名使用 gitlab.example.com，部署前请替换为实际 FQDN。

完成后你将能够：

• 按资源规划准备主机与 DNS；
• 使用 Omnibus 或 Docker Compose 完成安装；
• 获取 root 初始密码并配置 HTTPS；
• 用 gitlab-ctl 和健康检查确认服务正常。

1. 环境准备

1.1 操作系统

Omnibus 官方支持 Ubuntu 22.04/24.04、Debian 12、RHEL/Rocky/Alma 8/9 等。生产避免使用已 EOL 的发行版。

# 确认版本与架构
cat /etc/os-release | grep -E '^NAME=|^VERSION='
uname -m

# 时间同步（CI 与 Token 过期依赖准确时间）
timedatectl status
sudo timedatectl set-ntp true

1.2 防火墙与端口

端口	用途
443	HTTPS（Web、Git over HTTPS、Registry）
80	HTTP（可重定向到 443）
22 或自定义	SSH（Git over SSH）

# firewalld 示例
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-port=2222/tcp   # 若 SSH 改到 2222
sudo firewall-cmd --reload

注意

不要把未配置 HTTPS 和强密码的 GitLab 直接暴露到公网；上线前至少完成 TLS、root 改密、关闭公开注册。

2. 系统要求与资源规划

GitLab 官方最低参考（100 以下用户、少量项目）：

资源	最低	建议（中小团队）
CPU	4 核	8 核
内存	4 GiB	8～16 GiB
磁盘	50 GiB	SSD 100 GiB+，按仓库与 Registry 增长扩容

free -h
nproc
df -h /
df -h /var/opt/gitlab   # Omnibus 默认数据路径

Gitaly 存储与 Registry 镜像会持续增长；PostgreSQL 和备份单独占空间。内存不足时 Sidekiq/Puma 会被 OOM，表现为 502 和 Pipeline 超时。

3. DNS与网络配置

将 gitlab.example.com 解析到 GitLab 节点公网或内网 IP：

gitlab.example.com.  IN  A  10.0.10.50

若使用 内部 CA 或 Let's Encrypt，证书中的 SAN 必须包含该域名。Runner 与开发者机器需能解析并访问该地址（含 443/22）。

dig +short gitlab.example.com
curl -sI --connect-timeout 3 "https://gitlab.example.com" || true

4. Omnibus安装方式

以下以 Ubuntu 22.04 + GitLab CE 17.5 为例（版本可按 发布页 调整）。

4.1 安装依赖与仓库

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

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

国内环境可使用清华等镜像源替换 packages.gitlab.com，安装后包名仍为 gitlab-ce。

4.2 安装并指定 external_url

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

安装过程会自动执行 gitlab-ctl reconfigure，耗时数分钟。

4.3 常用管理命令

sudo gitlab-ctl status
sudo gitlab-ctl tail nginx
sudo gitlab-ctl restart

5. Docker部署方式

使用 固定版本标签，避免 latest 导致不可预期升级。

5.1 目录与 Compose

mkdir -p ~/gitlab-docker/{config,logs,data}
cd ~/gitlab-docker

compose.yaml：

services:
  gitlab:
    image: gitlab/gitlab-ce:17.5.2-ce.0
    container_name: gitlab
    hostname: gitlab.example.com
    restart: unless-stopped
    shm_size: '256m'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.com'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
    ports:
      - '443:443'
      - '80:80'
      - '2222:22'
    volumes:
      - './config:/etc/gitlab'
      - './logs:/var/log/gitlab'
      - './data:/var/opt/gitlab'

docker compose config
docker compose up -d
docker compose logs -f gitlab   # 首次启动约 5～10 分钟

SSH clone 地址形如：ssh://git@gitlab.example.com:2222/group/project.git。

提示

生产环境将 config、logs、data 放到独立磁盘或云盘，并纳入备份策略；shm_size 过小可能导致 Puma/Sidekiq 异常。

6. Kubernetes部署方式

官方 Helm Chart 将 Web、Sidekiq、Gitaly、Registry 等拆为多个 Deployment，PostgreSQL、Redis、对象存储通常使用外部服务（云 RDS/ElastiCache/S3）。

适用条件：

• 已有成熟 K8s 集群与 Ingress/LB；
• 需要多副本 Gitaly、Geo 或大规模 Runner 调度；
• 有 DBA 与 SRE 维护外部数据库和备份。

高层步骤：

helm repo add gitlab https://charts.gitlab.io/
helm repo update
# 按官方 chart 文档填写 globals.hosts.domain、postgresql、redis、minio 等
helm install gitlab gitlab/gitlab -f values.yaml -n gitlab --create-namespace

注意

Helm 部署的故障面包括 Chart 版本、Ingress、PVC 与外部 DB 连接；小团队若无 K8s 运维经验，优先 Omnibus 或 Docker。

7. GitLab初始化配置

7.1 获取 root 初始密码

Omnibus：

sudo cat /etc/gitlab/initial_root_password
# 文件 24 小时后自动删除，请立即登录并修改密码

Docker：

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

7.2 首次登录

1. 浏览器访问 https://gitlab.example.com；
2. 用户 root，粘贴初始密码；
3. User Settings → Password 修改为强密码；
4. Admin Area → Settings → General 关闭 Sign-up enabled（若不允许公开注册）。

# 命令行重置 root 密码（忘记密码时）
sudo gitlab-rake "gitlab:password:reset[root]"
# Docker: docker exec -it gitlab gitlab-rake "gitlab:password:reset[root]"

8. HTTPS配置

8.1 Let's Encrypt（Omnibus 自动）

编辑 /etc/gitlab/gitlab.rb：

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

sudo gitlab-ctl reconfigure

80 端口必须可从公网访问以完成 ACME 验证。

8.2 自有证书

external_url 'https://gitlab.example.com'
nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.example.com.crt"
nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.example.com.key"
letsencrypt['enable'] = false

将证书放入 /etc/gitlab/ssl/ 后执行 gitlab-ctl reconfigure。Docker 场景通过挂载 config/ssl 实现。

9. 安装验证与检查

9.1 服务状态

sudo gitlab-ctl status
# 期望 run: nginx, puma, sidekiq, postgresql, redis, gitaly, workhorse 等为 run

9.2 内置检查

sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake gitlab:doctor

9.3 HTTP 健康

curl -fsS "https://gitlab.example.com/help" -o /dev/null && echo "HTTP OK"
curl -fsS "https://gitlab.example.com/-/health" || true
curl -fsS "https://gitlab.example.com/-/readiness" || true

9.4 Git 验证

git clone https://gitlab.example.com/gitlab-org/gitlab-test.git /tmp/gitlab-test
# 或在 UI 新建 Project 后 clone 空仓库
ssh -T -p 2222 git@gitlab.example.com   # Docker 映射 2222 时

验收清单：

1. Web 登录成功且 root 已改密；
2. gitlab-ctl status 无 prolonged down；
3. gitlab:check 无红色 ERROR；
4. HTTPS 证书浏览器无告警（或内网 CA 已信任）；
5. 测试 git clone / git push 成功。

下一章：核心组件详解。