内存受限环境下的 GitLab 自托管部署指南（Docker Compose）

本文介绍如何在内存受限环境下，通过 Docker Compose 部署 GitLab，并且不使用 Nginx 或 Traefik 反向代理。以笔者环境为例，服务器规格为 2 核 4GB RAM + 30GB SSD，未做特殊优化。

1. 序言

根据 GitLab 官方文档说明（截至 2025 年 9 月 26 日），受限环境的最低要求如下：

操作系统：基于 Linux，推荐 Debian 或 RedHat 系统
CPU：4 核 ARM7/ARM64 或 1 核 AMD64
内存：最低 2GB RAM + 1GB 交换分区，推荐 2.5GB RAM + 1GB 交换
存储：最低 20GB，可用随机 I/O 性能越高越好
- 优先级：SSD > eMMC > HDD > 高性能 A1 SD 卡

CPU 单核性能和存储随机 I/O 性能对 GitLab 性能影响最大。小型平台可能因磁盘速度慢而成为系统瓶颈，但在 2 核 4GB 的服务器上运行 GitLab 是可行的。

2. 部署

本文采用 Docker Compose 部署方式，这是官方推荐方式。

2.1 前置准备

安装 Docker 和 Docker Compose
确定 $GITLAB_HOME 目录（可用当前目录 . 代替）

2.2 Docker Compose 配置示例

创建 docker-compose.yml 文件：

services:
  gitlab:
    image: gitlab/gitlab-ee:<version>-ee.0
    container_name: gitlab
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        # Add any other gitlab.rb configuration here, each on its own line
        external_url 'https://gitlab.example.com'
    ports:
      - '80:80'
      - '443:443'
      - '22:22'
    volumes:
      - '$GITLAB_HOME/config:/etc/gitlab'
      - '$GITLAB_HOME/logs:/var/log/gitlab'
      - '$GITLAB_HOME/data:/var/opt/gitlab'
    shm_size: '256m'

$GITLAB_HOME 可替换为当前目录 .，对应 Docker 容器内的配置、日志和数据目录映射。

2.3 系统配置文件 `gitlab.rb`

在 $GITLAB_HOME/config 下创建 gitlab.rb：

puma['worker_processes'] = 0

sidekiq['concurrency'] = 10

prometheus_monitoring['enable'] = false

gitlab_rails['env'] = {
  'MALLOC_CONF' => 'dirty_decay_ms:1000,muzzy_decay_ms:1000'
}

gitaly['configuration'] = {
  concurrency: [
    {
      'rpc' => "/gitaly.SmartHTTPService/PostReceivePack",
      'max_per_repo' => 3,
    }, {
      'rpc' => "/gitaly.SSHService/SSHUploadPack",
      'max_per_repo' => 3,
    },
  ],
  cgroups: {
    repositories: {
      count: 2,
    },
    mountpoint: '/sys/fs/cgroup',
    hierarchy_root: 'gitaly',
    memory_bytes: 500000,
    cpu_shares: 512,
  },
}
gitaly['env'] = {
  'MALLOC_CONF' => 'dirty_decay_ms:1000,muzzy_decay_ms:1000',
  'GITALY_COMMAND_SPAWN_MAX_PARALLEL' => '2'
}

⚠️ 建议删除 cgroups 配置，因为 Docker Compose 环境下 /sys/fs/cgroup 是只读，可能导致 Gitaly 启动失败。

  cgroups: {
    repositories: {
      count: 2,
    },
    mountpoint: '/sys/fs/cgroup',
    hierarchy_root: 'gitaly',
    memory_bytes: 500000,
    cpu_shares: 512,
  }

同时，需要提前将gitlab.rb文件放置于/etc/gitlab/gitlab.rb，这个对应$GITLAB_HOME/config设置的映射地址。

2.4 启动 GitLab

在docker-compose.yml文件目录下，我们启动Gitlab。

docker compose up -d

启动后执行以下命令，应用配置。

sudo docker exec -it gitlab gitlab-ctl reconfigure

3.遇到的问题

3.1自部署 GitLab 克隆仓库失败与个人访问令牌问题排查记录

1️⃣ 问题描述

在自部署 GitLab（18.4.1 CE）中，尝试通过 HTTP/HTTPS 克隆仓库时出现以下错误：

$ git clone http://gitlab.damokeris.xyz/root/obsidian.git Cloning into 'obsidian'... warning: missing OAuth configuration for gitlab.damokeris.xyz remote: HTTP Basic: Access denied fatal: Authentication failed

尝试创建 个人访问令牌（PAT） 时，发现无法创建，只能创建 项目访问令牌。

在浏览器 F12 控制台中还发现报错：

Mixed Content: The page at 'https://gitlab.damokeris.xyz/-/user_settings/personal_access_tokens' was loaded over HTTPS, but requested an insecure XMLHttpRequest endpoint 'http://gitlab.damokeris.xyz/...'.

同时修改 GitLab 配置后，浏览器访问 GitLab 出现：

ERR_TOO_MANY_REDIRECTS

2️⃣ 排查过程

2.1 检查 GitLab 配置

查看 Omnibus 配置文件 gitlab.rb，确认 external_url 设置：

external_url "http://gitlab.damokeris.xyz" gitlab_rails['gitlab_shell_ssh_port'] = 2222
检查 Rails 控制台中应用设置：

ApplicationSetting.current.disable_personal_access_tokens => false

→ 表明 个人访问令牌并未被禁用。

2.2 日志分析

查看浏览器报错：
- Mixed Content → 页面是 HTTPS，但请求了 HTTP 接口，导致请求被浏览器阻止。
GitLab Rails 日志无明显错误，仅显示 GraphQL 警告信息。

2.3 HTTPS 与 Cloudflare 冲突

当 GitLab 配置为 HTTPS 并开启 HTTP→HTTPS 重定向：

external_url "https://gitlab.damokeris.xyz" nginx['redirect_http_to_https'] = true
Cloudflare SSL 设置为 Flexible（灵活） 时，会造成请求循环：
1. 用户访问 Cloudflare HTTPS。
2. Cloudflare 用 HTTP 请求 GitLab。
3. GitLab 检测 HTTP，重定向到 HTTPS。
4. Cloudflare 接收重定向，再次用 HTTP → 循环。

3️⃣ 问题总结

无法克隆仓库
- 原因：使用 HTTP Basic 访问，需要使用 个人访问令牌（PAT） 而不是密码。
- 浏览器和 Git 客户端必须使用 HTTPS 才能正确发送 PAT。
无法创建个人访问令牌
- 表面上 ApplicationSetting 没有禁用，但浏览器访问时因为 HTTP/HTTPS 混合内容 被阻止。
- XMLHttpRequest 请求被浏览器拦截，导致创建 PAT 页面无法正常加载。
浏览器访问出现重定向循环
- 原因：GitLab HTTP→HTTPS 重定向 + Cloudflare Flexible SSL 产生循环。
- 表现为 ERR_TOO_MANY_REDIRECTS。

4️⃣ 解决方案建议

4.1 HTTPS 配置

GitLab 设置：

external_url "https://gitlab.damokeris.xyz" nginx['redirect_http_to_https'] = true letsencrypt['enable'] = true
Cloudflare SSL 设置：
- 选择 Full 或 Full (Strict)，确保 Cloudflare 与 GitLab 服务器之间也使用 HTTPS。
避免 Cloudflare Flexible 模式，否则会导致循环重定向。

4.2 Git 客户端

克隆仓库时必须使用 HTTPS + PAT：

git clone https://<username>:<personal_access_token>@gitlab.damokeris.xyz/root/obsidian.git
避免 HTTP URL，防止浏览器和 Git 客户端因混合内容或重定向被阻止。

3.2 解决 GitLab Web IDE 无法打开：OAuth 回调 URL 不匹配问题

在自托管 GitLab 时，打开项目 Web IDE，我遇到过这样一个报错页面：

无法打开 Web IDE
您用于访问 Web IDE 的 URL 与配置的 OAuth 回调 URL 不匹配。当您使用代理时通常会出现此问题。

找不到 https://gitlab.example.com/-/ide/oauth_redirect 的回调 URL 条目。

这个问题的根源是：GitLab Web IDE 依赖 OAuth 认证，而实例 OAuth 应用程序中配置的回调 URL 与实际访问的 URL 不一致。最常见的情况是 http 与 https 协议不一致。

问题定位

进入 GitLab 管理后台：

Admin Area → Settings → Applications → 实例 OAuth 应用程序
可以看到 GitLab Web IDE 的配置，其中的回调 URL 可能是：

http://gitlab.example.com/-/ide/oauth_redirect

但我实际访问 GitLab 用的是：

https://gitlab.example.com

由于协议不同（http vs https），Web IDE 就会报错。

解决方法

修改实例 OAuth 应用程序
- 在 Admin Area → Settings → Applications 找到 GitLab Web IDE
- 编辑回调 URL，改成：
```
https://gitlab.example.com/-/ide/oauth_redirect
```
检查 GitLab 主配置
- 打开 /etc/gitlab/gitlab.rb，确认设置为：
```
external_url "https://gitlab.example.com"
```
- 如果之前是 http://...，改成 https://...，然后执行：
```
sudo gitlab-ctl reconfigure
```
（可选）重启 GitLab
```
sudo gitlab-ctl restart
```

总结

GitLab Web IDE 报错 “OAuth 回调 URL 不匹配” 通常是 域名或协议不一致 导致的。
只要确保以下两点，就能解决问题：

实例 OAuth 应用程序里的回调 URL 与实际访问 URL 完全一致
gitlab.rb 里的 external_url 配置正确（建议始终使用 https）

这样 Web IDE 就可以正常使用了 ✅

1. 序言​

2. 部署​

2.1 前置准备​

2.2 Docker Compose 配置示例​

2.3 系统配置文件 gitlab.rb​

2.4 启动 GitLab​

3.遇到的问题

3.1自部署 GitLab 克隆仓库失败与个人访问令牌问题排查记录​

1️⃣ 问题描述​

2️⃣ 排查过程​

2.1 检查 GitLab 配置​

2.2 日志分析​

2.3 HTTPS 与 Cloudflare 冲突​

3️⃣ 问题总结​

4️⃣ 解决方案建议​

4.1 HTTPS 配置​

4.2 Git 客户端​

3.2 解决 GitLab Web IDE 无法打开：OAuth 回调 URL 不匹配问题​

问题定位​

解决方法​

总结​