使用 Docker Compose 本地部署 GitLab 教程

为了测试和gitlab的交互，有时候需要本地部署gitlab，这个文章就是在 macOS 上快速搭建一个私有代码托管平台并不复杂。通过 Docker Desktop，我们可以利用容器化技术，将 GitLab 及其复杂的依赖环境一键运行在本地，并实现数据的持久化存储。

📋 前提条件

在开始之前，请确保你的 Mac 满足以下条件：

安装 Docker Desktop ：前往官网下载。
运行状态：确保菜单栏的 Docker 图标显示为 "Running"。
硬件建议 ：GitLab 较占资源，建议 Mac 至少拥有 8GB RAM（分配给 Docker 4GB 以上）。

🛠️ 第一步：环境准备与目录创建

我们需要在 macOS 本地建立文件夹，以便将容器内的数据"挂载"出来。这样即使容器被删除，你的代码和配置也不会丢失。

方案 A：官方推荐路径（/opt）

Docker 官方推荐在 macOS 上使用 /opt 路径，以规避 /Users 目录可能存在的权限及性能开销。

Bash

复制代码

# 创建工作目录（用于存放配置文件）
mkdir -p ~/gitlab-deploy
cd ~/gitlab-deploy

# 创建数据挂载点（保存 GitLab 核心数据）
sudo mkdir -p /opt/gitlab/{config,logs,data}

方案 B：用户家目录（~/gitlab-data）

如果你希望备份更方便，可以将数据放在个人目录下。

注意：需在 Docker Desktop 的 Settings -> Resources -> File Sharing 中确保 /Users 在共享列表中。

📄 第二步：配置 Docker Compose

在 ~/gitlab-deploy 目录下创建 docker-compose.yml 文件。这个文件是整个服务的"设计图"。

YAML

复制代码

version: '3.8'
services:
  gitlab:
    image: 'gitlab/gitlab-ce:latest'
    restart: always
    hostname: 'gitlab.local'
    container_name: gitlab
    ports:
      - '80:80'      # HTTP 访问端口
      - '443:443'    # HTTPS 访问端口
      - '2222:22'    # SSH 克隆端口（避免冲突改为 2222）
    volumes:
      # 如果你选了方案 B，请将前面的路径改为 ${HOME}/gitlab-data/...
      - '/opt/gitlab/config:/etc/gitlab'
      - '/opt/gitlab/logs:/var/log/gitlab'
      - '/opt/gitlab/data:/var/opt/gitlab'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://localhost'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222

▶️ 第三步：一键启动与初始化

在终端中执行以下命令启动服务：

Bash

复制代码

docker-compose up -d

⏳ 关键点：耐心等待

GitLab 的初始化非常缓慢，通常需要 5~10 分钟。你可以通过查看实时日志来观察进度：

Bash

复制代码

docker-compose logs -f gitlab

当日志中出现 OK: DB migrations completed 或 Reconfigured! 字样时，说明服务已准备就绪。按下 Ctrl + C 退出日志查看。

🌐 第四步：访问与配置

打开浏览器 ：访问 http://localhost。
设置 Root 密码：
- 首次进入会强制要求设置 root 管理员密码。
- 设置完成后，使用用户名 root 和新密码登录。
SSH 克隆测试：
- 由于我们将 SSH 映射到了 2222 端口，克隆地址应如下：
- git clone ssh://git@localhost:2222/username/project.git

🛠️ 运维常用命令手册

操作	命令	说明
启动服务	`docker-compose up -d`	修改 yml 配置后也执行此命令重启
查看状态	`docker-compose ps`	确认容器是否处于 Up (healthy) 状态
查看日志	`docker-compose logs -f`	排查启动失败或报错时必用
停止服务	`docker-compose stop`	仅停止，不删除容器
卸载服务	`docker-compose down`	停止并移除容器，但本地挂载的数据会保留

💡 macOS 部署注意事项

内存溢出 ：如果 GitLab 启动极慢或浏览器报 502 错误，通常是 Docker 内存分配不足。请在 Docker Desktop 设置中将 Memory 调至 4GB 或更高。
Host 设置 ：GitLab 默认严格匹配 external_url。如果你在配置里写的是 localhost，请不要尝试用局域网 IP 访问，否则会出现登录态异常。
端口冲突 ：如果你的 Mac 已经运行了 Apache 或 Nginx 占用了 80 端口，请将 docker-compose.yml 中的 80:80 修改为 8080:80或者其他端口。