用Docker Compose部署GitLab：从安装到CI/CD的完整实践指南

1. 部署前的思路整理：先看清GitLab是什么，再决定怎么装

GitLab是一个基于Git的代码托管与DevOps平台，热门搜索里出现“GitLab社区版”“持续集成GitLab”“gitlab导入项目”这些词，说明大家实际关注的点集中在三个层面：怎么把GitLab跑起来、跑起来之后怎么用、以及团队协作和自动化流程怎么落地。标题虽然是“安装GitLab”，但纯粹装完一个空壳没有任何价值，真正核心的是安装方式的选择、后续的初始化配置、权限体系搭建和日常维护。

先说结论：如果你在2024年之后才开始接触GitLab，社区版（CE）就够用了，它包含了代码托管、分支保护、Merge Request、Issue跟踪、CI/CD等绝大多数功能。EE（企业版）多出来的那些能力，大部分团队在初期根本用不上。

安装方式上，主流有四种：

• 官方Omnibus包安装（适合物理机或云服务器直接部署）
• Docker部署（适合快速起服务、多实例隔离、方便迁移）
• Kubernetes Helm Chart部署（适合K8s集群内部署）
• 源码编译安装（不推荐，维护成本极高，除非你有特殊定制需求）

我的建议是：如果是个人学习、小团队（10人以内）、或者想在云服务器上快速验证，直接走Docker Compose路线，这也是目前社区里最主流的做法。原因很简单——Omnibus包虽然管理方便，但你得处理各种系统依赖和端口冲突；K8s部署虽然弹性好，但你需要额外维护一套集群，对大多数场景来说是杀鸡用牛刀。Docker方案在“足够简单”和“足够灵活”之间取得了最舒服的平衡点。

另外一个重要的思路是：安装GitLab之前，先想清楚两个问题。第一，你的服务器内存有多少？GitLab不是省油的灯，官方建议是4GB内存起步，我实测2GB的机器跑起来后系统负载长期在80%以上，卡得怀疑人生。第二，你的数据备份策略是什么？GitLab里存的是整个团队的代码资产，装完之后不配备份，等于把鸡蛋放在一个没有锁的篮子里。

2. 环境准备与工具选型：Docker和Docker Compose的安装与验证

2.1 服务器基础环境需求

GitLab官方文档给出的最低配置是2核4GB内存，但那是“能启动”的最低标准，不是“能用得舒服”的标准。我自己的经验是：

• 2核4GB：只能支撑1-5人的小团队，跑CI会有明显卡顿，建议关闭一些不必要的组件
• 4核8GB：10-20人团队比较舒服的选择，可以开GitLab Runner跑轻量CI
• 8核16GB：50人左右团队基本没问题，可以支持较重的CI任务和多项目并发

操作系统方面，Ubuntu 22.04 LTS、Debian 11/12、CentOS 7/8（EOL后建议转RHEL兼容系）都行。我习惯用Ubuntu Server，因为软件包更新快，碰到问题Google一下也有更多现成答案。

存储方面有个容易忽略的点：GitLab默认的仓库存储路径是/var/opt/gitlab（Omnibus）或容器内的/var/opt/gitlab（Docker映射到宿主机）。如果你把系统盘和数据盘混在一起，哪天系统盘满了，整个GitLab直接拒写。我一般会把数据目录挂载到独立的云盘或单独分区上，并把磁盘扩容能力提前摸清楚。

2.2 Docker与Compose安装全过程

我这里以Ubuntu 22.04为例，完整走一遍Docker引擎和Compose插件的安装。

# 更新系统软件源索引 sudo apt update # 安装依赖包，让apt支持通过HTTPS获取软件包 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg # 写入Docker软件源（官方源在国内可能偏慢，可以自行评估是否需要镜像源） echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装Docker引擎和Compose插件 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 验证安装 sudo docker version sudo docker compose version

装完Docker后，我建议立刻做两件事。第一，把当前用户加入docker组，避免每次敲命令都带sudo：

sudo usermod -aG docker $USER

记住，改完用户组后，要重新登录（或者执行newgrp docker）才能生效。

第二，检查Docker服务是否开机自启，这个很关键，很多人的服务器一重启，GitLab就不见了：

sudo systemctl enable docker sudo systemctl start docker

2.3 为什么要用Compose而不是直接跑docker run

单纯跑一个GitLab容器，一条docker run命令也能凑合。但GitLab这个镜像涉及大量配置项：端口映射、卷挂载、环境变量、容器名、重启策略……用一行命令全塞进去，时间一长你自己都不记得这个容器当初是怎么创建的，更别说团队成员接手了。

Compose文件的好处是：整个部署方式变成了代码，可以提交到Git仓库里做版本管理；要迁移服务器，把docker-compose.yml拷过去跑一遍docker compose up -d就完事；要改配置，直接改YAML后重新加载即可。

这里顺便踩个坑提醒：网上很多人用gitlab/gitlab-ce:latest这个标签。latest标签在镜像更新后可能会变化，导致你隔了几个月重新拉取镜像时直接升级了一个大版本，而GitLab跨版本升级经常要经历多次中间版本迁移（比如从14升到16，得先升15再升16），搞不好数据库就迁移失败了。所以生产环境一定要锁定具体的镜像版本号，比如gitlab/gitlab-ce:16.11.4-ce.0。等确认要升级了，再手动换版本号。

3. 用Docker Compose部署GitLab：每一步都有讲究

3.1 编写docker-compose.yml文件

先创建项目目录和数据目录：

sudo mkdir -p /opt/gitlab cd /opt/gitlab

然后创建docker-compose.yml，下面是我实际验证过的一套配置，关键参数都加了注释说明。

version: '3.8' services: gitlab: image: gitlab/gitlab-ce:16.11.4-ce.0 container_name: gitlab restart: always hostname: gitlab.example.com environment: GITLAB_OMNIBUS_CONFIG: | # 对外访问地址，这里决定你克隆代码时显示的仓库地址前缀 external_url 'http://gitlab.example.com' # 时区设置，默认是UTC，日志和界面时间会差8小时 gitlab_rails['time_zone'] = 'Asia/Shanghai' # 关闭一些用不上的组件，节省内存 grafana['enable'] = false prometheus['enable'] = false # 备份保留时间，这里保留7天 gitlab_rails['backup_keep_time'] = 604800 ports: # SSH端口映射，SSH协议克隆代码用 - "2222:22" # HTTP端口映射 - "80:80" # HTTPS端口，如不需要可注释 - "443:443" volumes: # 配置目录 - /opt/gitlab/config:/etc/gitlab # 数据目录（仓库、数据库） - /opt/gitlab/data:/var/opt/gitlab # 日志目录 - /opt/gitlab/logs:/var/log/gitlab shm_size: '256m'

这里有三个细节要重点解释。

第一，shm_size: '256m'。GitLab内部使用PostgreSQL和Redis，默认/dev/shm只有64MB，很容易触发“out of memory”错误导致重启。我在早期部署时就被这个坑过，页面突然打不开，容器日志一片Segmentation fault，后来翻官方issue才知道是共享内存太小。加上shm_size后问题立刻消失。

第二，SSH端口映射为2222:22。GitLab容器内的SSH服务默认监听22端口，但宿主机通常已经跑了sshd占用22。所以我把宿主机的2222映射到容器的22。这样做之后，SSH克隆代码的地址要带上端口号，比如git clone git@gitlab.example.com:2222:group/project.git。

第三，external_url里的域名。你设置的这个域名会出现在页面跳转、克隆地址拼接等很多地方。如果只是IP访问，直接写http://你的IP即可。但要注意，如果后面想配HTTPS，这里的scheme也要同步修改。

3.2 启动与初始化等待

配置文件写好后，执行：

sudo docker compose up -d

接下来就是等待。第一次启动时，容器要做很多事情：初始化PostgreSQL、编译assets资源、配置nginx、迁移数据库……时间长短取决于服务器性能，小机器可能要5-10分钟，大机器1-2分钟也正常。

我判断初始化完成的方法很简单：

# 查看容器状态 docker ps # 实时跟踪日志 docker logs -f gitlab

当日志里出现类似gitlab Reconfigured!、nginx: configuration file /etc/nginx/nginx.conf test is successful这样的字样时，基本就绪了。还有一种更直观的方式：直接浏览器访问你配置的external_url，能弹出设置root密码的页面就是成功。

这个阶段最容易出现的错误是502 Bad Gateway。别慌，大概率是GitLab还没完全初始化好，多等几分钟再刷新。如果等了十分钟还是502，再去看日志具体报什么错。

3.3 初次登录：设置root密码与创建管理员账号

浏览器打开GitLab地址，第一次访问会出现设置root密码的页面（有些版本是默认账号root，需要在初始化时通过命令设置密码）。设置好密码后，用root登录。

登录后的第一件事，我建议去Admin Area -> Settings里过一遍几个关键配置：

• 关闭“用户注册”功能（除非你真的打算开放注册），位置在Administration -> Settings -> General -> Sign-up restrictions，把Sign-up enabled取消勾选
• 设置仓库默认分支名。GitLab新版默认main，如果你团队习惯master，在Preferences里改全局默认
• 确认SSH key和Personal Access Token功能是开启状态，后面配置IDE和CI都要用

3.4 HTTPS配置：其实没那么可怕

前面示例里我用的http://开头，但实际团队使用中，强烈建议上HTTPS。原因不仅是浏览器打感叹号的问题，更重要的是：HTTP协议下，代码仓库的登录密码、Access Token都是明文传输的。你自己在公网服务器上部署GitLab，不用HTTPS等于把团队账号密码裸奔在公网上。

用Docker方式配置HTTPS有两种思路：

第一种，在GitLab容器前面加一层反向代理（比如Nginx、Caddy、Traefik），由代理层负责SSL终结，再转发到GitLab容器的HTTP端口。这种方案适合你已经有一套网关体系的情况。

第二种，直接在GITLAB_OMNIBUS_CONFIG里启用HTTPS。你需要先把证书传到服务器的配置目录下，然后在配置里写入：

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

然后执行docker compose exec gitlab gitlab-ctl reconfigure让配置生效。这里有一个注意事项：证书路径是容器内的路径，也就是说你得在宿主的/opt/gitlab/config/ssl目录放证书文件，因为该目录已经挂载成了容器内的/etc/gitlab。

如果你想申请免费证书，可以用Let‘s Encrypt，GitLab甚至内置了自动申请功能，在配置里加一句letsencrypt['enable'] = true就行。但要注意，自动申请要求你的域名已经解析到当前服务器IP，且80端口可从外网访问，否则验证会失败。

4. 核心配置、项目导入与开发者接入：装好只是开始

4.1 在GitLab中创建项目和推送代码

装好GitLab以后，很多人的第一直觉是直接建一个项目然后把本地代码推上去。这条路径基本走通，但提前了解几个概念会让你少走弯路：

• Group（群组）：相当于团队或部门，下面可以建多个Project。我建议你先在GitLab里按团队结构建几个Group，比如backend、frontend、infra，而不是让每个工程师各自建个人项目
• Project（项目）：对应一个代码仓库，可以设置可见性（私有、内部、公开）
• Visibility：公司内部的GitLab，建议统一设成Private，避免代码被搜索引擎收录

创建项目的入口在页面左上角“新建项目”。创建好之后，页面上会直接给出下面几个URL：

• HTTP地址：http://gitlab.example.com/group/project.git
• SSH地址：git@gitlab.example.com:2222/group/project.git

如果你是本地已经有一个Git仓库，直接照着页面提示操作：

cd existing_project git remote add origin git@gitlab.example.com:2222/group/project.git git push -u origin main

如果你是本地还没有仓库，那就：

git clone git@gitlab.example.com:2222/group/project.git cd project # ...干活、提交、推送

4.2 gitlab导入项目：迁移老仓库的几种姿势

热搜词里有“gitlab导入项目”，这通常出现在两种情况：一是从旧版GitLab迁移到新版，二是从GitHub、Bitbucket或SVN导入代码。GitLab的导入功能还是比较成熟的，路径在Admin Area -> Projects -> New Project -> Import project。

常见的导入渠道包括：

• GitHub：通过OAuth授权后，可以批量导入项目和Issues，前提是服务器能访问到GitHub。实测如果网络状况不好的话，导入大仓库会超时，可以先用git clone --bare手动搬
• 自建GitLab实例：适合换机器迁移的场景。你需要拿到旧实例的一个备份包，在新实例上执行gitlab-backup restore
• SVN：走了这条路的朋友，我只能说一声辛苦了。SVN的目录结构、分支模型和Git差异太大，导入后大概率需要人工整理分支

如果你只是要从旧仓库迁移代码且不想抽丝剥茧，我建议直接用“镜像仓库”的方式。在GitLab项目设置里找到Repository -> Mirroring repositories，填上源仓库地址和认证信息，GitLab会自动定时同步，这样既有新家的日常使用，又保留旧仓库的更新入口。

4.3 个人访问令牌：IDE接入的钥匙

热搜词里出现了“gitlab个人访问令牌”，还提到了IntelliJ IDEA遇上gitlab versions older than 14.0 are not supported的报错。这里展开说一下个人访问令牌这个机制。

个人访问令牌（Personal Access Token，简称PAT）就是一把印着字符串的“钥匙”，它在API调用和HTTPS克隆时代替密码使用。在GitLab中，路径是User Settings -> Access Tokens。

创建令牌时需要选择作用域，常用这几个：

• read_repository：只读仓库内容
• write_repository：读写仓库
• read_api：读取API数据
• api：完整的API访问权限
• read_registry：读取容器镜像仓库

我的习惯是给不用的场景配置最少的权限。IDE拉取推送代码，只需要write_repository就够了；命令行走HTTPS推送，也只需要write_repository；要跑CI脚本调API，再考虑给api。

令牌创建后只显示一次，一定要立刻复制保存。忘了的话只能重新生成，旧令牌立即失效。

至于那则报错gitlab versions older than 14.0 are not supported，意思是你的IDE插件版本太新，或者你的GitLab版本太旧（确实如报错所说低于14.0），插件官方决定不再兼容老版本API。解决办法两条路：升级GitLab实例，或者给IDE换一个支持旧版API的插件版本。但说句实话，GitLab 14.0是2021年发布的版本，都2024年了还在跑14.0以下，确实是该升级了——不仅为了IDE兼容，更为了安全。

4.4 PyCharm提交到GitLab：开发者的日常路径

PyCharm（以及JetBrains全家桶）提交代码到GitLab，本质上还是要走Git命令，IDE只是帮你包装了一层可视化。几个核心步骤：

• VCS -> Enable Version Control Integration，选择Git
• 在Settings -> Version Control -> Git中配置Git可执行文件路径
• 用HTTPS地址克隆项目时，PyCharm会让你输入用户名和密码，这时候用用户名 + 个人访问令牌的组合，令牌就是密码

如果你在IDEA/PyCharm里卡在登录弹窗，最常见的元凶是：GitLab版本过老（上面说的14.0以下），或者令牌没有勾选write_repository权限。先换令牌，再升级GitLab，基本能解决90%的登录问题。

4.5 持续集成GitLab CI/CD：装完就顺手把流水线跑起来

装好GitLab之后，如果不启用CI/CD功能，那装上的是一个“高级网盘”。GitLab内置的CI/CD模块才是它真正值钱的地方。它和Jenkins等外部CI工具的差别在于：流水线定义和代码仓库“绑定”在一起，配置变更走Merge Request评审，天然实现“配置即代码”。

一个最简单的CI配置是这样的：在项目根目录创建.gitlab-ci.yml文件，写上：

stages: - test - deploy unit-test: stage: test image: python:3.11 script: - pip install -r requirements.txt - pytest deploy: stage: deploy image: alpine:latest script: - echo "部署脚本在这里" only: - main

把文件提交推送到GitLab后，由于GitLab内置的Runner没有注册，流水线会卡在pending状态。你需要额外安装一个GitLab Runner来执行任务。GitLab Runner的部署方式有三种：

• 直接装一个Runner在宿主机，标签（tag）设为shell，直接跑本地命令，最简单，但麻烦的是污染执行环境
• 用Docker executer，每次任务起一个全新容器，环境干净，适合大多数场景
• 用K8s，适合已经在K8s集群里的人

Runner注册时需要一个token，在Settings -> CI/CD -> Runners页面获得。注册完Runner并勾选“Run untagged jobs”后，你的流水线就会自动开跑。

我个人强烈建议：即使你暂时不跑CI，也把.gitlab-ci.yml的框架建好，这样团队从一开始就有了一条自动化标准路径。等哪天你想加自动构建、自动部署，只需要往里面加stage，不用再从零开始建体系。

5. 常踩的坑与疑难杂症排查：从启动失败到高危漏洞

5.1 gitlab启动不了：最常见的三种原因

热搜词里有“gitlab启动不了”，这个问题我遇到过很多次，而且每次原因都不完全一样。把高频元凶列一下：

现象一：docker容器不断重启或处于Restarting状态。

排查思路：

# 先看容器状态和日志 docker ps -a docker logs --tail 100 gitlab

常见报错之一：permission denied。这是宿主机数据目录权限不对。我前面把数据挂到/opt/gitlab下，需要确保这个目录能读能写：

sudo chown -R 1000:1000 /opt/gitlab

GitLab容器内部默认用UID 1000运行，如果不把宿主目录属主改成1000，容器就没法写入配置和数据库文件。

常见报错之二：Failed to connect to the internal GitLab API。这个通常出现在启动早期，服务还没完全起来就被探活失败。如果你同时跑了不少吃内存的服务导致系统内存不足，很容易触发。要么加内存，要么按前面配置把Prometheus、Grafana关掉。

常见报错之三：磁盘满了。GitLab写入时会去检查磁盘，一旦遇到No space left on device，整个服务会挂。查看磁盘占用：

df -h

解决方案很直接：清掉不再需要的大文件，或者扩容数据盘。

现象二：服务起来之后，访问页面一直502。

这个在升级场景里最典型，数据库没有正常迁移。先看日志确认是不是db相关的问题：

docker logs gitlab 2>&1 | grep -i "db\|database"

如果是PG::UndefinedTable或database connection error，十有八九是数据卷里有旧版本残留，和当前镜像版本不匹配。最稳妥的办法是：备份现有挂载目录（至少config和data），清空后按新版本重新初始化。当然这是下策，上策是按官方推荐的“逐版本升级”路线走，比如从14升到16，先升到15再升16。

5.2 PostgreSQL和Redis的相关坑位

Docker化的GitLab，PostgreSQL和Redis都藏在容器内部，看起来方便，但也带来一个问题：数据全在容器生命周期里。容器一旦被删除，如果没有正确的数据卷挂载，所有数据一起没了。

所以启动前务必检查三件事：

• config目录有没有挂载
• data目录有没有挂载
• logs目录有没有挂载

如果你发现数据目录是空目录，或者是Docker自动创建的匿名卷，那就完了，容器删掉数据就蒸发了。

另外GitLab新版本（16.x开始）默认会把备份命令精简为gitlab-backup create（老一点的版本是这个命令），备份文件默认生成在/var/opt/gitlab/backups，对应宿主机是/opt/gitlab/data/backups。备份恢复我也顺便说一句：

# 先停掉数据写入 docker compose exec gitlab gitlab-ctl stop puma docker compose exec gitlab gitlab-ctl stop sidekiq # 执行恢复，注意备份文件名里的时间戳 docker compose exec gitlab gitlab-backup restore BACKUP=1700000000_2024_01_01_16.11.4 # 重启 docker compose restart

5.3 高危漏洞修复思路：别等被打了才想起来

热搜词里的“gitlab高危漏洞修复方案”，我看到的邮件标题基本都是CVE开头，比如CVE-2023-7028之类的账号接管漏洞。先别慌，虽然安全漏洞很可怕，但修复路径是清晰的，核心就一句话：把版本升级到补丁版本。

具体操作分三步走：

第一步：确认当前版本。在GitLab页面左下角或者执行：

docker compose exec gitlab cat /opt/gitlab/version-manifest.txt | head -5

第二步：确认官方补丁版本。去GitLab官网冒个泡，找到对应的安全公告页面，看你的版本区间落在哪个补丁版本。

第三步：升级。如果版本跨度大（比如从16.0直接升到16.11），官方建议分段升级。但在Docker方案里有个简化的判断标准：只要源版本和目标版本之间没有跳过“必须经过”的中间版本（GitLab官方每季度一个大版本，跨年度往上走就谨慎点），直接改镜像标签再docker compose pull && docker compose up -d就行。

升级前务必备份。这块再怎么强调都不为过。升级失败导致数据库不可用的案例，我见过不止一次，而且每次都是没备份或者备份失效的人。

5.4 其他高频问题速查表

做一个简单的清单，方便你日常排查：

这里“推送大文件时报错”值得多写一句。GitLab默认nginx的client_max_body_size大约是250MB，请确认你的团队是否会把超过250MB的单文件推到仓库。如果会，在配置里加：

nginx['client_max_body_size'] = "1024m"

这个同步要把nginx['proxy_set_headers']里的client_max_body_size也带上，不然nginx代理层还是按默认值收包。

6. 生产环境的维护建议与个人实操心得

写到这里，安装与基本使用已经覆盖得比较全了。以我个人的经验，最后再分享几个实用建议，这些都是在真实的团队使用中一遍遍验证过的：

第一个建议：给GitLab配好通知渠道。在Admin Area -> Settings -> Notifications里可以配置Slack等外部通知。推送代码、流水线失败、Merge Request创建这些事件如果能及时通知到人，团队响应问题的速度会快很多，而不是全靠人工盯着页面。

第二个建议：定期演练恢复流程。备份脚本写了、定时任务也配了，但没真正演练过的人，在灾难来临时基本是懵的。我建议你在测试环境（或新开一台机器）上练习一次“从备份恢复GitLab”的完整流程。把恢复的命令、路径、时间踩清楚，真到出问题的那天，你能省下一个通宵。

第三个建议：容器版本固定后，不要随便docker compose pull，因为你拉到的gitlab/gitlab-ce:16.11.4-ce.0是最初拉取的完整版本号，Docker层不会自己改变它，但如果你写的是16.11.4-ce.0这种完整标签也不完全杜绝风险——万一官方撤回这个tag重新推了同tag的镜像，你pull还是会拿到新版。最稳妥的做法是在升级前手动备份，然后显式docker compose pull；在没有备份的情况下，绝不要动版本号。

第四个建议：如果团队规模变大，早点引入GitLab Runner并跑起CI。我经历过一个团队从5人扩张到30人的过程，如果还停留在“手动测试、手动发布”的阶段，整个团队的交付节奏会被大量重复劳动拖垮。GitLab CI不是银弹，但它能逼着团队把构建、测试、部署流程代码化，这才是持续交付的地基。

最后，关于GitLab的部署方式，常见的讨论一直存在：有些老工程师坚持用Omnibus包，因为它是企业里最传统的方式，管理命令统一；也有人一路K8s到底，把所有组件容器化编排管理。我的个人倾向是：小团队用Docker Compose起步是成本最低的选择，等团队和流程成熟了再考虑K8s也不迟。工具是服务业务的，不是拿来炫技的。

装一个GitLab不难，难的是让它稳定运行、被团队真正用起来、并逐步成为开发流程中的核心节点。希望这篇内容能帮你把第一步踩实，也把后续的路看清楚。