一、为什么选择Docker-Compose部署GitLab？

在企业级开发场景中，私有化GitLab是保障代码安全、提升协作效率的核心需求。传统部署方式（如直接安装RPM包或手动配置容器）存在维护成本高、扩展性差等问题。Docker-Compose通过声明式YAML文件，将GitLab服务（Web、数据库、Redis等）的依赖关系、网络配置、存储卷等参数集中管理，显著降低部署复杂度。其优势体现在：

1. 环境一致性：通过docker-compose.yml文件定义完整环境，避免因服务器差异导致的配置错误。
2. 快速迭代：升级GitLab版本时，仅需修改镜像标签并重启服务，无需重新配置依赖组件。
3. 资源隔离：每个服务运行在独立容器中，避免端口冲突和资源竞争。
4. 可扩展性：支持通过修改配置文件轻松扩展存储、备份等模块。

二、部署前环境准备

1. 硬件与软件要求

• 服务器配置：建议至少4核CPU、8GB内存、50GB可用磁盘空间（生产环境需根据团队规模调整）。
• 操作系统：CentOS 7/8、Ubuntu 20.04 LTS等主流Linux发行版。
• 依赖工具：安装Docker（建议20.10+版本）和Docker-Compose（1.29+版本）。

  # 示例：Ubuntu 20.04安装Docker
  curl -fsSL https://get.docker.com | sh
  sudo usermod -aG docker $USER  # 添加当前用户到docker组
  # 安装Docker-Compose
  sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  sudo chmod +x /usr/local/bin/docker-compose

2. 网络与域名规划

• 端口分配：GitLab默认使用80（HTTP）、443（HTTPS）、22（SSH）端口，需确保服务器防火墙放行这些端口。
• 域名配置：建议为GitLab申请独立域名（如gitlab.example.com），并通过Nginx反向代理实现HTTPS访问。

三、Docker-Compose配置详解

1. 基础配置文件

以下是一个精简的docker-compose.yml示例，包含GitLab核心服务：

version: '3.8'
services:
  web:
    image: gitlab/gitlab-ee:latest  # 企业版镜像，社区版用gitlab/gitlab-ce
    container_name: gitlab
    restart: unless-stopped
    hostname: gitlab.example.com  # 必须与实际域名一致
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.com'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222  # 避免与主机SSH端口冲突
        postgresql['enable'] = false
        gitlab_rails['db_host'] = 'db'
        gitlab_rails['db_password'] = 'your_strong_password'
        redis['enable'] = false
        gitlab_rails['redis_host'] = 'redis'
    ports:
      - '80:80'
      - '443:443'
      - '2222:22'  # 映射SSH端口
    volumes:
      - './config:/etc/gitlab'
      - './logs:/var/log/gitlab'
      - './data:/var/opt/gitlab'
    depends_on:
      - db
      - redis
  db:
    image: postgres:13
    container_name: gitlab-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: gitlabhq_production
      POSTGRES_USER: gitlab
      POSTGRES_PASSWORD: 'your_strong_password'
    volumes:
      - './postgresql:/var/lib/postgresql/data'
  redis:
    image: redis:6-alpine
    container_name: gitlab-redis
    restart: unless-stopped
    command: redis-server --requirepass 'your_strong_password'
    volumes:
      - './redis:/data'

2. 关键配置说明

• 数据持久化：通过volumes映射配置、日志和数据目录到主机，防止容器删除后数据丢失。
• 依赖服务分离：将PostgreSQL和Redis拆分为独立服务，提升数据库性能并简化备份。
• 环境变量注入：使用GITLAB_OMNIBUS_CONFIG动态配置GitLab参数，避免直接修改容器内文件。

四、部署与初始化

1. 启动服务

mkdir -p gitlab/{config,logs,data,postgresql,redis}
cd gitlab
docker-compose up -d

首次启动需下载镜像并初始化数据库，耗时约5-10分钟（视网络和硬件而定）。可通过以下命令检查状态：

docker-compose logs -f web  # 实时查看GitLab日志
docker-compose ps         # 检查服务运行状态

2. 初始化配置

访问https://gitlab.example.com，按向导完成以下步骤：

1. 设置管理员密码（默认用户名为root）。
2. 配置SMTP邮件服务（用于密码重置和通知）。
3. 导入现有项目或创建新仓库。

五、进阶优化与维护

1. 性能调优

• 调整JVM参数：在GITLAB_OMNIBUS_CONFIG中增加：

  gitlab_rails['env'] = { 'JAVA_OPTS' => '-Xms1g -Xmx2g' }

• 启用Gitaly缓存：优化大仓库的克隆性能：

  gitaly['prometheus_listen_addr'] = '0.0.0.0:9236'

2. 备份与恢复

• 自动备份：通过Cron定时执行：

  0 2 * * * docker-compose exec web gitlab-rake gitlabcreate

• 恢复数据：将备份文件（/var/opt/gitlab/backups/）复制到主机后，运行：

  docker-compose exec web gitlab-rake gitlabrestore BACKUP=timestamp_of_backup

3. 安全加固

• 禁用公开注册：在Admin Area > Settings > General中关闭Sign-up enabled。
• 强制双因素认证：要求所有用户启用2FA。
• 定期更新镜像：通过docker-compose pull获取最新安全补丁。

六、常见问题解决方案

1. 502错误：通常由内存不足引起，需增加容器内存限制或优化PostgreSQL配置。
2. SSH连接失败：检查gitlab_rails['gitlab_shell_ssh_port']与映射端口是否一致。
3. 邮件发送失败：验证SMTP配置并测试docker-compose exec web gitlab-rails console中的邮件发送功能。

七、总结与展望

通过Docker-Compose私有化部署GitLab，开发者可在1小时内完成从环境搭建到生产就绪的全流程。相比Kubernetes方案，Docker-Compose更轻量且易于维护，尤其适合中小团队或内部研发场景。未来可结合GitLab Runner实现CI/CD流水线自动化，或通过Prometheus+Grafana构建监控体系，进一步释放私有化GitLab的潜力。

实际部署中，建议先在测试环境验证配置，再逐步迁移生产数据。定期备份和监控容器资源使用情况，是保障服务稳定性的关键。