GitLab Docker 部署实战：基于 gitlab.yaml 的单容器方案
使用 Docker 部署 GitLab，是中小团队最直接、最容易迁移的一种方案。配置、日志和业务数据都挂载在宿主机目录中，后续做备份、恢复和升级都比较清晰。
一、部署前准备
建议先满足以下条件：
- CPU 至少 4 核。
- 内存至少 4 GB，生产环境建议 8 GB 起。
- 已安装 Docker 20.10+。
- 已安装 Docker Compose V2，也就是可以直接使用
docker compose命令。 - 域名
gitlab.example.com已经解析到目标服务器，或者你已经准备好可访问该服务的内网 DNS。
如果你准备用本文中的配置直接部署，请先在服务器上准备一个独立目录，例如：
mkdir -p /opt/gitlab/{config,logs,data}
cd /opt/gitlab
然后把仓库中的 gitlab.yaml 放到这个目录里。
二、本文使用的 gitlab.yaml
下面这份配置就是当前实际使用的 Compose 文件：
version: "3.8"
services:
web:
image: "gitlab/gitlab-ce:18.11.4-ce.0"
container_name: "gitlab"
restart: always
hostname: "gitlab.example.com"
shm_size: "1g"
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url 'http://gitlab.example.com'
gitlab_rails['gitlab_shell_ssh_port'] = 2222
nginx['listen_port'] = 80
nginx['listen_https'] = false
nginx['client_max_body_size'] = '2048m'
prometheus_monitoring['enable'] = false
ports:
- "80:80"
- "2222:22"
volumes:
- "./config:/etc/gitlab"
- "./logs:/var/log/gitlab"
- "./data:/var/opt/gitlab"
三、逐行解释这份 YAML 配置
下面改成表格形式，阅读会更紧凑一些。
| 行号 | 配置项 | 说明 |
|---|---|---|
| 1 | version: "3.8" |
指定 Compose 文件格式版本。3.8 是一个兼容性较好的写法，适合当前常见的 Docker Compose V2 环境。 |
| 2 | 空行 | 只是为了让顶层结构更清晰，对运行结果没有影响。 |
| 3 | services: |
定义服务集合。一个 Compose 文件里可以包含多个服务，这里目前只定义了一个 GitLab 服务。 |
| 4 | web: |
服务名称。后续执行 docker compose exec web ...、docker compose logs web 时，web 就是引用这个服务。 |
| 5 | image: "gitlab/gitlab-ce:18.11.4-ce.0" |
指定容器镜像和版本。这里固定使用 GitLab CE 18.11.4-ce.0，好处是部署结果可复现，升级时也更可控。 |
| 6 | container_name: "gitlab" |
指定容器名称为 gitlab。这样执行 docker ps 时更容易识别容器，但如果同一台机器上部署多个同名栈，就会发生命名冲突。 |
| 7 | restart: always |
表示容器退出后自动重启。适合服务器重启后自动拉起 GitLab，减少人工干预。 |
| 8 | hostname: "gitlab.example.com" |
指定容器内主机名。GitLab 会使用这个主机名参与一些内部配置生成，通常应与实际访问域名保持一致。 |
| 9 | shm_size: "1g" |
为容器分配 1 GB 的共享内存。GitLab 某些组件对共享内存比较敏感，适当放大有助于减少因内存不足导致的异常。 |
| 10 | environment: |
定义环境变量。这里主要是给 GitLab Omnibus 传入启动时的内置配置。 |
| 11 | GITLAB_OMNIBUS_CONFIG: | |
定义一个多行字符串环境变量。| 表示下面缩进的多行内容会原样作为文本传给 GitLab 的 Omnibus 配置系统。 |
| 12 | external_url 'http://gitlab.example.com' |
设置 GitLab 对外访问地址。浏览器访问入口、邮件里的链接、很多回调地址都会以它为准。这里配置的是 HTTP，而不是 HTTPS。 |
| 13 | gitlab_rails['gitlab_shell_ssh_port'] = 2222 |
告诉 GitLab：用户通过 SSH 克隆仓库时，应该使用 2222 端口，而不是默认的 22。这样页面上展示的 SSH 地址才会正确。 |
| 14 | nginx['listen_port'] = 80 |
指定 GitLab 内置 Nginx 在容器内部监听 80 端口。因为下方端口映射也是 80:80，所以内外端口是对齐的。 |
| 15 | nginx['listen_https'] = false |
关闭 GitLab 内置 Nginx 的 HTTPS 监听。这意味着当前部署方式只提供 HTTP 服务，如果需要 HTTPS，通常要在前置反向代理或 GitLab 内部另行配置证书。 |
| 16 | nginx['client_max_body_size'] = '2048m' |
把上传请求体上限设置为 2048 MB。这样上传大附件、CI 制品或较大的代码包时，不容易因为默认限制被拒绝。 |
| 17 | prometheus_monitoring['enable'] = false |
关闭 GitLab 自带的 Prometheus 监控组件。这样可以降低资源占用，适合资源有限、暂时不依赖内置监控的场景。 |
| 18 | ports: |
定义宿主机端口与容器端口的映射关系。 |
| 19 | - "80:80" |
把宿主机的 80 端口映射到容器的 80 端口。外部访问 http://gitlab.example.com 时，最终就会进入容器内的 GitLab Web 服务。 |
| 20 | - "2222:22" |
把宿主机的 2222 端口映射到容器的 22 端口。这样既避免和宿主机自己的 SSH 22 端口冲突，也能让 GitLab 提供独立的仓库 SSH 访问能力。 |
| 21 | volumes: |
定义数据卷挂载。把 GitLab 关键目录映射到宿主机后，容器删除或升级时数据不会丢。 |
| 22 | - "./config:/etc/gitlab" |
将当前目录下的 config 挂载到容器的 /etc/gitlab。这里存放 GitLab 主要配置文件，例如 gitlab.rb、gitlab-secrets.json 和初始化密码文件。 |
| 23 | - "./logs:/var/log/gitlab" |
将当前目录下的 logs 挂载到容器的 /var/log/gitlab。方便直接在宿主机查看 GitLab 的运行日志。 |
| 24 | - "./data:/var/opt/gitlab" |
将当前目录下的 data 挂载到容器的 /var/opt/gitlab。这是最核心的数据目录，数据库、仓库、附件和备份文件等都在这里。 |
四、启动 GitLab
因为当前 Compose 文件名不是默认的 compose.yaml 或 docker-compose.yml，所以所有命令都建议显式带上 -f gitlab.yaml。
docker compose -f gitlab.yaml up -d
首次启动通常需要 2 到 5 分钟。你可以实时查看日志：
docker compose -f gitlab.yaml logs -f web
如果容器正常启动完成，就可以在浏览器中访问：
http://gitlab.example.com
五、获取 root 初始密码
GitLab 首次启动后，会自动生成 root 用户的初始密码。因为我们已经把 /etc/gitlab 挂载到了宿主机，所以可以直接在宿主机查看。
Linux/macOS：
cat ./config/initial_root_password
PowerShell：
Get-Content .\config\initial_root_password
注意两点：
- 这个文件通常会在 24 小时后自动删除。
- 首次登录后，建议立刻修改
root密码。
六、常用运维命令
下面这些命令都在 gitlab.yaml 所在目录执行。
查看服务状态：
docker compose -f gitlab.yaml ps
查看实时日志：
docker compose -f gitlab.yaml logs -f web
停止服务但不删除容器：
docker compose -f gitlab.yaml stop
停止并删除容器，但保留挂载数据：
docker compose -f gitlab.yaml down
重启服务：
docker compose -f gitlab.yaml restart
进入容器内部排查问题：
docker compose -f gitlab.yaml exec web bash
进入容器后，可以执行：
gitlab-ctl status
