使用docker-compose私有化部署 GitLab：企业级自托管方案详解

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

在开源代码管理需求日益增长的背景下，企业选择私有化部署GitLab的核心诉求体现在三方面：数据主权控制、性能可预测性、功能定制自由度。相较于SaaS版GitLab，自托管方案允许企业完全掌控代码仓库、用户权限、备份策略等核心要素，尤其适合金融、医疗等对数据安全有严格合规要求的行业。

根据GitLab官方发布的《2023年开发者生态报告》，采用私有化部署的企业中，68%将数据安全列为首要考虑因素，42%关注长期成本优化。通过docker-compose部署方案，企业可在保持容器化优势的同时，获得比传统虚拟机部署更高效的资源利用率——典型场景下可节省30%以上的服务器资源。

二、环境准备与基础配置

2.1 系统要求与前置条件

推荐配置：4核CPU、8GB内存、50GB磁盘空间（生产环境建议双倍配置）。操作系统需支持Docker引擎（建议Ubuntu 22.04 LTS或CentOS 8），需提前安装：

# Ubuntu系统安装示例
sudo apt update
sudo apt install -y curl apt-transport-https ca-certificates gnupg
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

2.2 目录结构规划

建议采用如下目录结构，便于后续维护：

/opt/gitlab/
├── config/         # 配置文件目录
│   ├── gitlab.rb   # 高级配置（可选）
│   └── ssl/        # 证书存储
├── data/           # 数据持久化目录
│   ├── gitlab/     # 主数据
│   └── redis/      # Redis数据
└── docker-compose.yml

三、docker-compose配置详解

3.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 'https://gitlab.example.com'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
        postgresql['enable'] = false
        gitlab_rails['db_host'] = 'db'
        gitlab_rails['db_username'] = "gitlab"
        gitlab_rails['db_password'] = "secure_password"
        redis['enable'] = false
        gitlab_rails['redis_host'] = 'redis'
    ports:
      - '2222:22'    # SSH端口映射
      - '80:80'      # HTTP（需前端反向代理）
      - '443:443'    # HTTPS
    volumes:
      - './data/gitlab:/var/opt/gitlab'
      - './config/ssl:/etc/gitlab/ssl'
      - './config/gitlab.rb:/etc/gitlab/gitlab.rb'
    depends_on:
      - db
      - redis
  db:
    image: postgres:14
    container_name: gitlab-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: "gitlab"
      POSTGRES_PASSWORD: "secure_password"
      POSTGRES_DB: "gitlabhq_production"
    volumes:
      - './data/postgresql:/var/lib/postgresql/data'
  redis:
    image: redis:6-alpine
    container_name: gitlab-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - './data/redis:/data'

3.2 关键配置参数解析

1. 外部URL配置：external_url必须与实际访问域名完全匹配，否则会导致OAuth等集成功能异常
2. SSH端口映射：建议使用非标准端口（如2222）避免与宿主机SSH冲突
3. 数据库分离：生产环境必须使用独立数据库容器，禁用内置PostgreSQL
4. 数据持久化：通过volumes实现三重数据保护（应用数据、数据库、Redis）

四、高级配置与优化

4.1 性能调优参数

在gitlab.rb中添加以下配置可显著提升性能：

# 调整Unicorn工作进程数（建议CPU核心数的2倍）
unicorn['worker_processes'] = 8
# 启用Sidekiq并发处理
sidekiq['concurrency'] = 25
# 优化Gitaly存储配置
gitaly['prometheus_listen_addr'] = '0.0.0.0:9236'
gitlab_rails['gitaly_timeout'] = 90

4.2 安全加固方案

1. TLS证书配置：

   # docker-compose.yml补充
   environment:
   GITLAB_OMNIBUS_CONFIG: |
    nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.example.com.crt"
    nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.example.com.key"
    nginx['redirect_http_to_https'] = true

2. 防火墙规则（UFW示例）：

   sudo ufw allow 2222/tcp
   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   sudo ufw enable

3. 双因素认证配置：
   通过管理界面启用：Settings > General > Sign-in restrictions > Enable two-factor authentication

五、运维管理最佳实践

5.1 备份策略

建议采用分层备份方案：

# 每日全量备份脚本示例
#!/bin/bash
docker exec -t gitlab bash -c "gitlab-backup create"
BACKUP_FILE=$(docker exec -t gitlab bash -c "ls -t /var/opt/gitlab/backups/ | head -1")
docker cp gitlab:/var/opt/gitlab/backups/$BACKUP_FILE /backups/

5.2 升级流程

1. 备份当前数据
2. 修改docker-compose.yml中的镜像标签（如gitlab/gitlab-ee:16.0.0）
3. 执行升级：

   docker-compose down
   docker-compose pull
   docker-compose up -d

5.3 监控方案

推荐Prometheus+Grafana监控栈，关键指标包括：

• Sidekiq队列积压量
• PostgreSQL连接数
• 磁盘I/O延迟
• 内存使用率

六、故障排查指南

6.1 常见问题处理

1. 502 Bad Gateway错误：

   • 检查Redis连接：docker logs gitlab-redis
   • 验证数据库连接：docker exec -it gitlab bash -c "sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h db -U gitlab gitlabhq_production"

2. SSH连接失败：

   • 确认端口映射：netstat -tulnp | grep 2222
   • 检查Gitaly服务状态：docker exec -it gitlab bash -c "gitlab-ctl tail gitaly"

6.2 日志分析技巧

关键日志路径：

• /var/log/gitlab/gitlab-rails/production.log
• /var/log/gitlab/sidekiq/current
• /var/log/gitlab/unicorn/unicorn_stdout.log

七、扩展功能集成

7.1 CI/CD流水线优化

在.gitlab-ci.yml中配置缓存：

cache:
  key: "$CI_COMMIT_REF_SLUG"
  paths:
    - vendor/
    - .npm/
  policies:
    - pull
    - push

7.2 容器注册表配置

启用内置Registry：

# gitlab.rb配置
registry_external_url 'https://registry.gitlab.example.com'
registry['enable'] = true
nginx['listen_port'] = 5050

八、成本效益分析

以50人开发团队为例：
| 部署方式 | 初始投入 | 年度维护成本 | 数据控制权 |
|————————|—————|———————|——————|
| SaaS版（高级） | $0 | $4,800 | 无 |
| 自托管方案 | $1,200 | $600 | 完全控制 |

自托管方案在两年周期内可节省约70%成本，同时获得：

• 定制化开发权限
• 审计日志完全留存
• 符合GDPR等数据合规要求

九、总结与建议

通过docker-compose部署GitLab实现了开发效率与运维复杂度的最佳平衡。建议企业：

1. 采用基础设施即代码（IaC）管理配置
2. 建立标准化CI/CD模板库
3. 定期进行安全渗透测试
4. 实施分级存储策略（热数据SSD/冷数据HDD）

典型部署周期可从传统方案的3-5天缩短至8小时内完成，且后续扩容弹性显著提升。对于超大规模部署（>1000用户），建议考虑GitLab Dedicated或混合云架构。