一、环境准备
1、硬件要求
内存和硬件配置：至少 2 核 CPU 和 4G 内存，64位系统，以确保能够运行。建议搭配4核以上CPU、16G以上内存。
2、操作系统选择
本教程基于win11专业版系统利用Docker进行安装建议使用win11系统，省去一些配置工作。
Mac、Linux原生系统安装和配置流程基本相同，可参考本教程。
3、必要软件和依赖
DockerDesktop、WSL2、WSL2 LINUX发行版（Ubuntu,根据需求自行选择版本）、Hyper-V，开启虚拟化服务。这些软件安装和配置可以自行查阅其他教程。
二、安装GitLab
1. 在 Windows 中创建目录
在 D盘 创建以下目录结构（预防系统盘空间爆满）：
text
D:\
├── docker-data\
│ └── gitlab\
│ ├── config\
│ ├── logs\
│ └── data\
手动创建方法：
打开 Windows 文件资源管理器
进入 D盘
新建文件夹 docker-data
在 docker-data 中新建 gitlab 文件夹
在 gitlab 中新建三个子文件夹：config、logs、data
2. 在 WSL2 中创建 docker-compose.yml
进入 D盘对应的 WSL2 路径
cd /mnt/d/docker-data/gitlab
创建 docker-compose.yml
nano docker-compose.yml
YAML文件配置了GitLab服务的基本信息。
3.参考以下配置内容（仔细阅读后文配置详情简介！！！按需配置）
version: '3.8'
services:
gitlab:
image: gitlab/gitlab-ce:latest
container_name: gitlab
restart: unless-stopped
hostname: 'gitlab.xn--fiqs8s'
environment:
GITLAB_OMNIBUS_CONFIG: |
external_url 'http://gitlab.xn--fiqs8s'
gitlab_rails['gitlab_shell_ssh_port'] = 2222
nginx['redirect_http_to_https'] = false
ports:
- "80:80"
- "443:443"
- "2222:22"
volumes:
- ./config:/etc/gitlab
- ./logs:/var/log/gitlab
- ./data:/var/opt/gitlab
deploy:
resources:
limits:
memory: 24G
cpus:'20.0'
reservations:
memory: 8G
cpus:'8.0'
配置信息详情介绍如下：
Version：指定了我们要使用的Docker Compose文件格式的版本。不同版本的Docker Compose支持不同的配置选项和语法。版本3.8是较新的版本，提供了更多功能和更好的兼容性。注意，这个版本号与Docker Engine的版本也有对应关系，通常需要相应版本的Docker Engine支持。版本较新可以忽略。建议加上，避免兼容性问题。可以打开WSL2检查：
命令 | 说明 |
docker-compose --version | 如果版本 >= 1.27.0，可以用 version: '3.8' |
docker compose version | 如果版本较旧，用 version: '3.3' 或 '3.0' |
Image：使用gitlab/gitlab-ce:latest镜像；
container_name:设置容器名称为gitlab；
Restart:设置容器的重启策略为 “除非手动停止，否则一直保持运行”。即容器会在异常退出、宿主机重启后自动重新启动，只有当你手动停止它时，它才会真正停止；
hostname:容器内部的计算机主机名，可以不配置，会生成默认名称。如果配置外部访问，建议和外部访问域名同步，避免邮件链接、webhook、系统报告等显示问题。
environment:GitLab Omnibus（一体化安装包）的环境变量设置，用于在容器启动时自动生成配置文件。
external_url 'http://gitlab.中国' External_url ‘http://gitlab.xn--fiqs8s’ | 定义gitlab对外的完整访问地址 http://：指定访问协议为HTTP（而非HTTPS）。这直接影响GitLab生成的链接形式和Nginx的监听方式。 提示：没有自己的公网ip和域名可以不设置，使用默认配置名称，博主配置是为了进行外部访问 注意： 域名gitlab.中国 的Punycode编码是 gitlab.xn--fiqs8s 不能直接在关键配置中使用 gitlab.中国，必须更改为其Punycode编码格式。服务器软件、命令行工具及配置文件通常无法直接处理中文字符。直接使用可能导致服务无法启动、链接生成错误或连接失败。但用户仍可以直接使用gitlab.中国域名进行访问 后续在ECS的Nginx反向代理配置中，server_name 等所有出现域名的地方，也应统一使用 gitlab.xn--fiqs8s 注：如果使用非汉字后缀域名，不需要此转换操作 |
gitlab_rails['gitlab_shell_ssh_port'] = 2222 | 作用：指定gitlab的ssh服务对用户公开的端口号 关键点：这个端口是告知用户连接时使用的。在项目克隆地址中，它会显示为 git@gitlab.中国:2222:username/project.git。它不等同于容器内部SSH服务实际监听的端口（内部默认仍是22），需要通过Docker端口映射来实现连接。 |
nginx['redirect_http_to_https'] = false | 作用：禁用GitLab内置的Nginx将HTTP请求自动重定向到HTTPS的功能。 为什么：因为您在 external_url 中明确指定了使用 http:// 协议。将此设为 false 后，GitLab才会允许直接通过HTTP访问。如果设为 true 而协议仍是HTTP，会导致访问异常。 |
Ports:配置端口
命令 | 说明 |
Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -eq 80 } | 确认要设置的端口号在宿主机有无被占用，使用powershell管理员权限 |
- "2222:22" | 格式是 "宿主机端口:容器端口"，意味着将宿主机（您的本地电脑）的某个端口绑定到容器内部的某个服务端口。 |
http://localhost 如果不是80端口需要加上冒号和端口号例如 ：8080 | 本地电脑的访问地址； gitlab内部的nginx在容器的80端口提供http服务，此规则使我们可以通过本地电脑的80端口访问它 |
Volumes:这个配置是 Docker 数据卷挂载，用于 持久化保存 GitLab 的所有数据和配置。简单来说，它的作用是将 GitLab 容器内易变、重要的数据目录，“映射”并保存到你本地电脑的对应文件夹中。这样即使删除或重启容器，你的数据也不会丢失。格式：本地目录：容器内目录
配置项 | 说明 |
- ./config:/etc/gitlab | 保存 GitLab 的所有配置文件（包含您之前设置的 external_url 等）。如果丢失，GitLab 需要完全重新配置。 |
- ./logs:/var/log/gitlab | 保存 GitLab 的运行日志，用于故障排查等 |
- ./data:/var/opt/gitlab | 保存 最核心的用户数据，包括：代码仓库、数据库（用户、权限、议题等）、上传的附件。注意！！！如果这个目录丢失，相当于整个 GitLab 数据被清空。 |
核心目的与优势：
数据持久化：容器重建或更新时，你的所有设置、代码和用户数据都安全保留在本地。
便于管理：可以直接在宿主机的 ./config 目录下修改配置文件，而不需要进入容器内部。
方便备份：要备份整个 GitLab，只需备份当前目录下的 config、data、logs 这三个文件夹即可。
你可以把它理解为：容器本身是“临时租用的房子”，而挂载的这些目录是你搬进去的“个人家具和行李”。房子退了，你的东西都还在。
- Deploy:定义与服务器部署相关的配置定义服务的部署属性，但其功能在非集群模式下可能受限。当与Swarm模式结合时，它支持集群化部署。Docker Desktop 是单机环境：博主使用的 Docker Desktop 是一个独立的 Docker 守护进程，不具备 Swarm 集群的调度功能。它会直接忽略 deploy 部分的所有内容。这里添加上让大家作为了解，如果部署方式和博主相同，可以直接删掉。
Resources: | 定义容器可使用的计算资源（CPU、内存） |
Limits: memory: 24 Cpus： ‘20.0’ | 硬件上限，容器最多只能使用24GB内存、20个CPU核心，超过限制容进程被操作系统强制终止。cpus推荐设置为上限50% |
Reservations: memory: 8G Cpus: ‘6.0’ | 软性预留，系统尝试保证至少分配8GB内存、6个核心给该容器使用，但是不一定能够达成。相当于一个不可靠的memory提供下限。 |
编辑完成后写入保存操作：
粘贴代码到 nano 编辑器 |
检查内容是否正确 |
按 Ctrl+X（左下角显示 "Exit"） |
按 Y（左下角显示 "Save modified buffer?"） |
按 Enter（使用默认文件名 docker-compose.yml） |
4、DockerDesktop需要保持运行状态
确保 WSL2 能访问 Docker
写完配置文件后使用验证语法
命令 | 说明 |
cd /mnt/d/docker-data/gitlab | 保存yml文件后立即进入 |
docker-compose config | 验证语法是否正确，是否输出正确的配置信息 |
5.修复权限问题（重要！）
给目录设置正确权限（WSL2中操作）
命令 | 说明 |
cd /mnt/d/docker-data | 从wsl2进入该目录 |
sudo chown -R 1000:1000 gitlab/ | 权限设置 |
sudo chmod -R 755 gitlab/ | 权限设置 |
Ls -la gitlab/ | 验证权限设置是否成功（是否有输出1000:1000字样） |
或者更宽松的权限（设置上述权限有问题再考虑更宽松权限）
sudo chmod -R 777 gitlab/
6. 启动 GitLab（Ubutun内）
命令 | 说明 |
cd /mnt/d/docker-data/gitlab | 进入gitlab目录进行操作 |
docker-compose up -d | 启动gitlab |
等待几秒钟 | |
docker-compose ps | 查看状态，输出up则成功。输出exit或空白，查看日志 |
docker-compose logs gitlab | 查看日志 |
提示：如果下载或连接失败，修改镜像源或使用魔法，这部分操作不展开讲，如有需要请查阅博主其他文章。
命令 | 说明 |
docker pull hello-world | 在wsl2的ubuntu终端运行，检测连接是否成功 |
如果没有可用镜像，可以删除所有设置镜像，使用默认官方仓库，但是没有魔法容易失败，可以在docker settings->docker engine->json窗口中作如下配置：
"max-concurrent-downloads": 3, | 将最大并发下载数设为3，避免单一下载占用所有连接。 |
"max-download-attempts": 5, | 将下载尝试次数增加到5次，给不稳定的网络更多重试机会。 |
点击 “Apply & Restart”，等待 Docker Desktop 完全重启 | 重复上述流程 |
注意！
如果使用非官方镜像，注意镜像名称一致！！！
命令 | 说明 |
cat docker-compose.yml | 查看当前目录下配置文件（使用ubuntu进入gitlab目录）。查看image信息，查看名称 |
sudo docker images | 查看所有镜像信息，看gitlab镜像名称和配置文件中是否相同，如果有差异，进行后续步骤 |
sudo docker tag docker.1ms.run/gitlab/gitlab-ce:latest gitlab/gitlab-ce:latest | 给镜像添加标签/别名 ，前面是实际下载的镜像名称，最后是配置文件内名称。也可以直接修改配置文件内名称为实际下载镜像名称。 |
sudo docker images | 验证打标签操作是否成功 |
返回执行gitlab启动操作步骤 |
- 查看状态(Ubuntu内执行)
命令 | 说明 |
cd /mnt/d/docker-data/gitlab | 进入之前.yml配置文件目录 |
docker-compose logs -f | 查看日志 |
退出持续输出日志 | Ctrl+c |
sudo docker-compose logs --tail=50 | 可以只查看最近50条日志 |
验证文件位置
docker-compose.yml 位置：D:\docker-data\gitlab\docker-compose.yml
配置文件位置：D:\docker-data\gitlab\config\
日志文件位置：D:\docker-data\gitlab\logs\
数据文件位置：D:\docker-data\gitlab\data\
8、启动后操作
获取初始密码，在ubuntu执行：
docker-compose -exec gitlab cat /etc/gitlab/initial_root_password
本地验证:
浏览器访问--> http://localhost-->用户名：root-->密码：上面命令显示的密码
重要注意事项
路径映射：Windows的 D:\ 在 WSL2 中是 /mnt/d/
性能问题：D盘如果是机械硬盘，GitLab运行可能较慢
权限问题：Windows NTFS 和 Linux 权限系统不同，需要手动设置权限
备份方便：数据在D盘，重装系统时不会丢失
三、维护与更新
1.1备份与恢复
备份：停止容器后，复制整个D:\docker-data\gitlab目录到安全位置。
恢复：将备份的目录放回原处，然后运行docker-compose up -d。
这样，你的GitLab数据就持久化在D盘了。
