别再只用GitLab SaaS了！手把手教你用Docker Compose在本地服务器搭建私有GitLab（含Runner与Registry配置）

私有化GitLab全栈部署指南：从Docker Compose到企业级CI/CD实战

当代码成为企业核心资产，越来越多的技术团队开始重新审视SaaS服务的局限性。数据主权、网络延迟、长期成本核算——这些关键词正在推动一场从云端回归本地的技术迁徙。作为这场迁徙的核心载体，GitLab私有化部署不仅能提供与SaaS版本完全一致的功能体验，更能让团队在代码安全、网络拓扑和集成扩展性上获得绝对控制权。

本文将呈现一套经过生产环境验证的私有GitLab部署方案，基于Docker Compose实现分钟级环境初始化，完整覆盖代码仓库、CI/CD流水线和私有容器镜像库三大核心模块。不同于简单的安装教程，我们将重点剖析企业级部署中的性能调优策略、高可用设计要点以及安全加固方案，帮助技术决策者在私有化转型中规避典型陷阱。

1. 环境规划与资源配比

1.1 硬件需求深度解析

GitLab的资源消耗呈现明显的"三高"特征：高内存占用、高IO吞吐、高CPU突发需求。根据我们的压力测试数据，不同规模团队的推荐配置如下：

团队规模并发用户推荐配置容器资源配额备注
5-10人≤54核8G + 100G SSD内存限制6GB, CPU份额0.5适合初创团队PoC阶段
10-30人≤158核16G + 200G SSD内存限制12GB, CPU份额1.5需启用Redis缓存
30-50人≤3016核32G + 500G NVMe内存限制24GB, CPU份额3建议分离Runner节点
50人+≥30集群化部署多节点负载均衡需专业运维团队支持

关键发现：当GitLab内存不足时，会触发OOM Killer终止Unicorn进程，表现为502错误。建议始终保留20%的内存余量应对峰值负载。

1.2 网络拓扑设计

私有部署的核心优势在于网络架构自主权。我们推荐两种企业级网络方案：

方案A：隔离部署模型

graph TD A[办公网络] -->|防火墙规则| B(GitLab主机:443/22) B --> C[内部DNS] C --> D[LDAP/AD服务器] B --> E[独立Runner集群] E --> F[K8s生产环境]

方案B：云混合模型

# 典型安全组规则示例 aws ec2 authorize-security-group-ingress \ --group-id sg-xxxxxx \ --protocol tcp \ --port 443 \ --cidr 192.168.1.0/24

2. Docker Compose部署实战

2.1 编排文件深度优化

以下是我们优化后的生产级docker-compose.yml，重点解决社区版默认配置的三大痛点：数据持久化不全、时区不一致和SMTP缺失：

version: '3.8' services: gitlab: image: gitlab/gitlab-ce:16.8.1-ce.0 container_name: gitlab-ce hostname: gitlab.example.com environment: TZ: Asia/Shanghai GITLAB_OMNIBUS_CONFIG: | external_url 'https://gitlab.example.com' gitlab_rails['time_zone'] = 'Asia/Shanghai' gitlab_rails['smtp_enable'] = true gitlab_rails['smtp_address'] = "smtp.office365.com" gitlab_rails['smtp_port'] = 587 gitlab_rails['smtp_user_name'] = "gitlab@example.com" gitlab_rails['smtp_password'] = "${SMTP_PASSWORD}" gitlab_rails['smtp_domain'] = "example.com" gitlab_rails['smtp_authentication'] = "login" gitlab_rails['smtp_enable_starttls_auto'] = true gitlab_rails['gitlab_email_from'] = 'gitlab@example.com' registry['registry_http_addr'] = "0.0.0.0:5050" ports: - "443:443" - "80:80" - "2222:22" - "5050:5050" # Container Registry volumes: - gitlab_config:/etc/gitlab - gitlab_logs:/var/log/gitlab - gitlab_data:/var/opt/gitlab - /etc/localtime:/etc/localtime:ro shm_size: '256m' deploy: resources: limits: cpus: '2' memory: 8G volumes: gitlab_config: gitlab_logs: gitlab_data:

关键改进点：

  1. 显式声明时区配置避免日志时间错乱
  2. 通过环境变量注入SMTP密码（需提前export SMTP_PASSWORD=xxx）
  3. 限制容器资源防止单点故障影响宿主机
  4. 挂载宿主机localtime保持时间同步

2.2 初始化后必做操作

容器启动后（约5-10分钟），立即执行以下安全加固步骤：

  1. 修改root密码：
docker exec -it gitlab-ce gitlab-rake "gitlab:password:reset[root]"
  1. 启用HTTPS（自签名证书方案）：
# 进入容器 docker exec -it gitlab-ce bash # 生成证书 mkdir -p /etc/gitlab/ssl && cd $_ openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \ -keyout gitlab.example.com.key \ -out gitlab.example.com.crt \ -subj "/CN=gitlab.example.com" # 应用配置 echo "nginx['ssl_certificate'] = '/etc/gitlab/ssl/gitlab.example.com.crt'" >> /etc/gitlab/gitlab.rb echo "nginx['ssl_certificate_key'] = '/etc/gitlab/ssl/gitlab.example.com.key'" >> /etc/gitlab/gitlab.rb gitlab-ctl reconfigure
  1. 关键健康检查：
# 检查服务状态 gitlab-ctl status # 查看日志 tail -f /var/log/gitlab/gitlab-rails/production.log # 测试邮件发送 gitlab-rails console Notify.test_email('admin@example.com', 'GitLab Setup', 'SMTP配置成功').deliver_now

3. Runner高级配置策略

3.1 混合式Runner架构

生产环境推荐采用"静态Runner+动态Docker Runner"的混合架构：

  • 静态Runner：固定配置的物理机/VM，适合：

    • 需要特殊硬件（如GPU编译）
    • 依赖本地缓存（如node_modules）
    • 安全敏感任务（如部署生产环境）

  • 动态Docker Runner：按需创建的容器化Runner，适合：

    • 普通构建任务
    • 并行测试任务
    • 临时性大规模作业

注册示例（带缓存配置）：

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner \ gitlab/gitlab-runner:v16.8.0 register \ --non-interactive \ --executor "docker" \ --docker-image alpine:latest \ --url "https://gitlab.example.com" \ --registration-token "PROJECT_REGISTRATION_TOKEN" \ --description "docker-runner" \ --tag-list "docker,aws" \ --run-untagged="true" \ --locked="false" \ --docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \ --docker-volumes "/cache" \ --env "DOCKER_DRIVER=overlay2"

3.2 性能调优参数

在/etc/gitlab-runner/config.toml中添加以下关键参数：

concurrent = 10 check_interval = 1 [[runners]] name = "high-perf-runner" executor = "docker" [runners.docker] tls_verify = false image = "alpine:latest" privileged = true disable_cache = false volumes = ["/cache", "/builds:/builds"] shm_size = "512m" [runners.cache] Type = "s3" Path = "gitlab-runner" Shared = true [runners.cache.s3] ServerAddress = "s3.example.com" AccessKey = "AKIAXXXXXX" SecretKey = "XXXXXX" BucketName = "gitlab-runner-cache" BucketLocation = "us-east-1"

缓存策略对比：

缓存类型适用场景优点缺点
本地缓存小型团队/简单项目零配置，低延迟无法跨Runner共享
S3/MinIO分布式团队全局共享，高可靠性需要额外存储服务
GitLab CI混合云环境集成度高性能受网络影响
无缓存安全性优先项目环境纯净每次全量构建耗时

4. 容器镜像库企业级实践

4.1 安全加固方案

私有Registry的三大核心风险点及应对策略：

  1. 匿名拉取风险：
# 在gitlab.rb中强制认证 registry['auth_auto_redirect'] = false registry['token_realm'] = "https://gitlab.example.com/jwt/auth"
  1. 镜像漏洞扫描：
# .gitlab-ci.yml 示例 stages: - scan clair_scan: stage: scan image: docker:stable services: - docker:dind variables: DOCKER_HOST: tcp://docker:2375 DOCKER_DRIVER: overlay2 script: - docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \ registry.gitlab.com/gitlab-org/security-products/klar:latest \ scan --report-file gl-container-scanning-report.json \ ${CI_REGISTRY_IMAGE}:${CI_COMMIT_SHA} artifacts: reports: container_scanning: gl-container-scanning-report.json
  1. 存储配额管理：
# 在gitlab.rb中设置 registry['storage'] = { 'filesystem' => { 'rootdirectory' => "/var/opt/gitlab/gitlab-rails/shared/registry", 'maxthreads' => 10 }, 'delete' => { 'enabled' => true, 'olderthan' => '90d' }, 'quota' => { 'enabled' => true, 'default' => '100GB' } }

4.2 高可用架构设计

对于关键业务系统，建议采用如下架构：

graph LR A[GitLab主节点] -->|同步| B[Registry只读副本] A -->|备份| C[S3兼容存储] B --> D[CDN边缘节点] C --> E[异地灾备中心]

关键配置参数：

# 主节点gitlab.rb registry['storage'] = { 's3' => { 'accesskey' => 'AKIAXXXXXX', 'secretkey' => 'XXXXXX', 'bucket' => 'gitlab-registry', 'region' => 'us-east-1', 'regionendpoint' => 'https://s3.example.com', 'secure' => true } } # 副本节点配置 registry['storage'] = { 'cache' => { 'blobdescriptor' => 'redis' }, 'maintenance'] = { 'readonly' => { 'enabled' => true } } }

5. 迁移与持续运维

5.1 SaaS到私有化的平滑迁移

分阶段迁移策略：

  1. 镜像阶段（1-2周）：

    • 保持SaaS版本为权威源
    • 配置私有实例的镜像仓库
    git clone --mirror https://gitlab.com/example/project.git cd project.git git push --mirror https://gitlab.example.com/example/project.git

  2. 双写阶段（1个月）：

    # 全局.gitconfig配置 [url "https://gitlab.example.com"] insteadOf = https://gitlab.com [url "https://gitlab.com"] pushInsteadOf = https://gitlab.example.com

  3. 切换阶段：

    • 修改DNS记录指向私有实例
    • 更新CI/CD环境变量
    • 迁移Webhook到新地址

5.2 监控与排错指南

关键监控指标：

# Prometheus监控目标 - job_name: 'gitlab' metrics_path: '/-/metrics' static_configs: - targets: ['gitlab.example.com:443'] # 关键告警规则 groups: - name: gitlab.rules rules: - alert: HighUnicornMemory expr: process_resident_memory_bytes{job="gitlab", app="unicorn"} > 4 * 1024 * 1024 * 1024 for: 10m labels: severity: critical annotations: summary: "Unicorn memory usage high (instance {{ $labels.instance }})"

典型故障处理：

  1. 502错误：
# 检查Unicorn gitlab-ctl tail unicorn # 常见解决方案 sudo gitlab-ctl restart unicorn sudo sysctl -w vm.max_map_count=262144
  1. 推送超时：
# Nginx调整 client_max_body_size 0; proxy_read_timeout 600; keepalive_timeout 600;
  1. Runner离线：
# 检查连接性 curl -v https://gitlab.example.com/api/v4/runners # 重置Runner令牌 sudo gitlab-runner restart