使用Docker-Compose私有化部署GitLab：从零到一的完整指南

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

在传统部署方式中，GitLab的安装需要手动配置依赖服务（如PostgreSQL、Redis、Gitaly等），且不同操作系统环境可能导致兼容性问题。Docker-Compose通过声明式YAML文件将GitLab及其依赖服务容器化，实现环境一致性和快速复现。其核心优势包括：

1. 轻量级隔离：每个服务运行在独立容器中，避免资源冲突
2. 配置即代码：通过docker-compose.yml文件管理服务拓扑
3. 快速迭代：升级或回滚版本仅需修改配置文件并重启服务
4. 资源可控：通过--scale参数动态调整服务实例数量

对于中小型团队而言，Docker-Compose方案在保持灵活性的同时，大幅降低了私有化部署的技术门槛。

二、部署前环境准备

硬件要求

组件	最低配置	推荐配置
CPU	2核	4核（支持并发操作）
内存	4GB	8GB（含CI/CD运行时）
磁盘	40GB（SSD优先）	100GB+（存储仓库数据）

软件依赖

1. Docker Engine：建议使用最新稳定版（验证命令：docker --version）
2. Docker-Compose：v1.29+（支持x-common变量复用）
3. 操作系统：Linux（Ubuntu 20.04/CentOS 8）或macOS（需x86架构）

网络配置

• 开放端口：
  • 80（HTTP访问）
  • 443（HTTPS访问）
  • 2222（SSH克隆，需与主机22端口映射）
• 建议配置防火墙规则仅允许内网访问，或通过反向代理暴露服务

三、Docker-Compose配置详解

基础配置模板

version: '3.8'
services:
  web:
    image: gitlab/gitlab-ee:latest
    container_name: gitlab
    restart: unless-stopped
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://your-domain.com'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
        postgresql['enable'] = false
        redis['enable'] = false
        gitlab_rails['db_username'] = "gitlab"
        gitlab_rails['db_password'] = "secure_password"
        gitlab_rails['db_host'] = "db"
        gitlab_rails['redis_host'] = "redis"
    ports:
      - "80:80"
      - "443:443"
      - "2222:22"
    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_USER: gitlab
      POSTGRES_PASSWORD: secure_password
      POSTGRES_DB: gitlabhq_production
    volumes:
      - ./postgresql/data:/var/lib/postgresql/data
  redis:
    image: redis:6-alpine
    container_name: gitlab-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - ./redis/data:/data

关键配置项解析

1. external_url：必须与域名解析一致，影响GitLab生成的所有URL
2. SSH端口映射：通过2222:22避免与主机SSH服务冲突
3. 数据持久化：
   • config：存储GitLab配置文件（如gitlab.rb）
   • logs：容器日志目录
   • data：仓库数据、上传文件等核心数据
4. 外部数据库：使用独立PostgreSQL容器而非内置数据库，提升性能

四、部署流程与优化

1. 初始化部署

# 创建工作目录
mkdir -p gitlab/{config,logs,data,postgresql/data,redis/data}
cd gitlab
# 下载并修改docker-compose.yml
wget https://example.com/docker-compose.yml  # 替换为实际模板
vim docker-compose.yml  # 修改环境变量
# 启动服务
docker-compose up -d

2. 初始化配置

通过浏览器访问http://your-domain.com，首次访问会触发初始化流程：

1. 设置管理员密码（默认账号：root）
2. 配置SMTP邮件服务（用于密码重置等通知）
3. 设置LFS对象存储（可选）

3. 性能优化建议

• 内存限制：在docker-compose.yml中添加资源限制

  web:
    deploy:
      resources:
        limits:
          memory: 6G

• 数据库调优：修改PostgreSQL的postgresql.conf

  shared_buffers = 256MB
  work_mem = 4MB
  maintenance_work_mem = 128MB

• 启用Gitaly缓存：在GITLAB_OMNIBUS_CONFIG中添加

  gitlab_rails['gitaly_token_authenticated_storage_enabled'] = true

五、运维管理最佳实践

1. 备份与恢复

# 创建备份（需在GitLab容器内执行）
docker-compose exec web gitlab-backup create
# 恢复备份（示例）
docker-compose exec web bash -c "
  GITLAB_BACKUP_DIR=/var/opt/gitlab/backups
  chmod 600 $GITLAB_BACKUP_DIR/$(ls -t $GITLAB_BACKUP_DIR | head -1)
  gitlab-rake gitlab:backup:restore BACKUP=1625093228_2021_06_30_13.4.6
"

2. 升级策略

1. 备份当前数据
2. 修改docker-compose.yml中的镜像标签（如latest→15.0.0-ee.0）
3. 执行docker-compose pull && docker-compose up -d
4. 检查日志：docker-compose logs -f web

3. 监控方案

• Prometheus集成：在GITLAB_OMNIBUS_CONFIG中启用

  prometheus['enable'] = true
  prometheus_monitoring['enable'] = true

• 自定义告警：通过GitLab API监控关键指标

  curl --header "PRIVATE-TOKEN: your_token" "http://localhost/api/v4/monitor"

六、常见问题解决方案

1. 502 Bad Gateway错误

• 检查gitlab-workhorse日志：docker-compose logs web | grep workhorse
• 常见原因：
  • 内存不足（增加容器内存限制）
  • 数据库连接失败（检查db服务状态）
  • 配置文件权限错误（确保config目录权限为755）

2. SSH克隆失败

• 验证端口映射：netstat -tulnp | grep 2222
• 检查GitLab SSH配置：

  gitlab_rails['gitlab_shell_ssh_port'] = 2222
  gitlab_rails['gitlab_shell_host'] = "your-domain.com"

3. 邮件发送失败

• 测试SMTP配置：

  docker-compose exec web bash -c "
    echo 'Test email' | mail -s 'Test' user@example.com
  "

• 检查/var/log/gitlab/mailroom/current日志

七、进阶配置建议

1. 多节点部署

对于高可用场景，可拆分服务到不同节点：

# docker-compose.yml（主节点）
services:
  web:
    image: gitlab/gitlab-ee
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        roles ['geo_primary_role']
        geo_secondary_node['enable'] = false
# docker-compose.yml（次节点）
services:
  web:
    image: gitlab/gitlab-ee
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        roles ['geo_secondary_role']
        geo_primary_node['url'] = "https://primary.example.com"

2. CI/CD加速

• 配置Runner缓存：

  volumes:
    - ./cache:/cache
  environment:
    CACHE_DIR: /cache

• 使用Docker-in-Docker（DinD）执行器：

  services:
    docker:
      image: docker:20.10-dind
      privileged: true
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock

八、总结与展望

通过Docker-Compose部署GitLab，开发者可以在30分钟内完成从环境准备到生产就绪的全流程。这种方案特别适合：

• 内部代码管理平台
• 持续集成/持续部署（CI/CD）流水线
• 私有化代码托管需求

未来可扩展方向包括：

1. 集成Kubernetes Operator实现动态扩缩容
2. 结合Vault实现密钥管理
3. 使用Thanos实现跨节点监控数据聚合

建议定期（每季度）进行安全审计和依赖更新，确保平台稳定性与数据安全性。