使用Docker-Compose私有化部署GitLab：从环境准备到运维指南

一、私有化部署的必要性分析

在云原生时代，GitLab作为集成的DevOps平台，其私有化部署成为企业保障代码安全、提升研发效率的关键选择。相较于SaaS版本，私有化部署具有三大核心优势：

1. 数据主权控制：所有代码、制品库及用户数据完全存储在企业内部，避免第三方服务泄露风险
2. 定制化能力：支持自定义CI/CD流水线、权限模型及集成企业现有AD/LDAP系统
3. 合规性保障：满足等保2.0、GDPR等法规对数据存储位置和访问控制的要求

通过Docker-Compose部署方案，开发者可在30分钟内完成从环境准备到服务启动的全流程，相比传统虚拟机部署效率提升80%以上。

二、部署前环境准备

1. 硬件资源要求

组件	最小配置	推荐配置
CPU	4核	8核+
内存	8GB	16GB+
存储	100GB SSD	500GB NVMe SSD
网络带宽	100Mbps	1Gbps

2. 软件依赖安装

# 安装Docker CE（Ubuntu示例）
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
# 安装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

3. 存储卷规划

建议创建三个独立存储卷：

• /var/gitlab/config：存储配置文件
• /var/gitlab/logs：存储日志文件
• /var/gitlab/data：存储仓库数据、制品库等

三、Docker-Compose编排文件详解

1. 基础配置示例

version: '3.8'
services:
  web:
    image: gitlab/gitlab-ee:latest
    container_name: gitlab
    restart: unless-stopped
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://gitlab.example.com'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
        postgresql['enable'] = false
        gitlab_rails['db_host'] = 'postgres'
        redis['enable'] = false
        gitlab_rails['redis_host'] = 'redis'
    ports:
      - '80:80'
      - '443:443'
      - '2222:22'
    volumes:
      - '/var/gitlab/config:/etc/gitlab'
      - '/var/gitlab/logs:/var/log/gitlab'
      - '/var/gitlab/data:/var/opt/gitlab'
    depends_on:
      - postgres
      - redis
  postgres:
    image: postgres:14
    environment:
      POSTGRES_USER: gitlab
      POSTGRES_PASSWORD: secure_password
      POSTGRES_DB: gitlabhq_production
    volumes:
      - '/var/gitlab/postgres:/var/lib/postgresql/data'
  redis:
    image: redis:6-alpine
    command: redis-server --requirepass "secure_password"
    volumes:
      - '/var/gitlab/redis:/data'

2. 关键配置参数说明

• external_url：必须与域名解析一致，影响邮件通知中的链接生成
• SSH端口映射：建议使用非标准端口（如2222）避免与主机SSH冲突
• 数据库配置：生产环境建议使用外部PostgreSQL集群
• 资源限制：可通过deploy.resources限制容器资源使用

四、部署流程与验证

1. 部署步骤

# 创建存储目录
sudo mkdir -p /var/gitlab/{config,logs,data,postgres,redis}
# 启动服务
sudo docker-compose up -d
# 查看服务状态
sudo docker-compose ps
sudo docker-compose logs -f

2. 初始化验证

1. 访问http://gitlab.example.com应看到初始化页面
2. 执行docker exec -it gitlab grep 'GitLab started' /var/log/gitlab/gitlab-rails/production.log确认服务启动
3. 使用gitlab-rake gitlab:check进行健康检查

五、运维优化实践

1. 性能调优方案

• 数据库优化：

  -- PostgreSQL配置调整示例
  ALTER SYSTEM SET shared_buffers = '2GB';
  ALTER SYSTEM SET work_mem = '16MB';
  ALTER SYSTEM SET maintenance_work_mem = '512MB';

• GitLab配置优化：

  # 在gitlab.rb中添加
  gitlab_rails['sidekiq_concurrency'] = 25
  gitlab_rails['db_pool_size'] = 50
  puma['worker_processes'] = 4

2. 备份恢复策略

# 创建备份脚本
#!/bin/bash
docker exec -t gitlab gitlab-rake gitlab:backup:create
# 恢复命令示例
docker exec -t gitlab gitlab-rake gitlab:backup:restore BACKUP=1630000000_2021_08_25_14.0

3. 监控告警配置

推荐使用Prometheus+Grafana监控方案：

1. 启用GitLab内置Prometheus：

   prometheus_monitoring['enable'] = true

2. 配置关键指标告警规则：

• 磁盘空间使用率 > 85%
• Sidekiq队列积压 > 100
• 响应时间 > 2s

六、常见问题解决方案

1. 502错误排查流程

1. 检查/var/log/gitlab/gitlab-rails/production.log
2. 验证Puma进程状态：docker exec gitlab ps aux | grep puma
3. 检查数据库连接：docker exec gitlab bash -c "cd /opt/gitlab/embedded/service/gitlab-rails && bundle exec rails runner 'puts ActiveRecord::Base.connection.active?'"

2. 邮件发送失败处理

# 在gitlab.rb中配置SMTP
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.example.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "user@example.com"
gitlab_rails['smtp_password'] = "password"
gitlab_rails['smtp_domain'] = "example.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

七、升级与扩展指南

1. 版本升级流程

# 1. 备份当前数据
docker exec -t gitlab gitlab-rake gitlab:backup:create
# 2. 修改docker-compose.yml中的镜像版本
# 3. 执行升级
docker-compose down
docker-compose up -d
# 4. 运行迁移命令
docker exec -it gitlab gitlab-rake db:migrate

2. 水平扩展方案

对于超过1000用户的实例，建议：

1. 分离Gitaly服务：

   gitaly:
   image: gitlab/gitaly:latest
   volumes:
    - '/var/gitlab/gitaly:/var/opt/gitlab/gitaly'
   environment:
    GITALY_ADDRESS: 'tcp://0.0.0.0:8075'

2. 在gitlab.rb中配置：

   gitlab_rails['gitaly_enabled'] = false
   gitlab_rails['gitaly_address'] = 'tcp://gitaly:8075'

八、安全加固建议

1. 基础安全配置

# 禁用注册功能
gitlab_rails['allow_signup'] = false
# 启用双因素认证
gitlab_rails['two_factor_authentication'] = true
# 限制访问IP
nginx['listen_addresses'] = ['192.168.1.100']

2. 定期安全维护

1. 每月执行：

   docker exec gitlab bash -c "cd /opt/gitlab/embedded/bin && ./rkhunter --checkall"

2. 每季度更新：

   docker-compose pull
   docker-compose up -d --no-deps --build web

通过以上系统化的部署方案，开发者可构建出满足企业级需求的GitLab私有化环境。实际部署中，建议先在测试环境验证配置，再逐步迁移至生产环境。对于超大规模部署（>5000用户），可考虑结合Kubernetes实现更灵活的资源调度。