Docker Compose编排GitLab：从单机部署到生产级配置

1. 为什么选择Docker Compose部署GitLab第一次接触GitLab时我尝试过直接在服务器上安装结果被复杂的依赖关系和配置过程折磨得够呛。后来发现用Docker部署简直像发现了新大陆——特别是配合Docker Compose所有服务都能通过一个YAML文件搞定。这种基础设施即代码的方式让部署过程变得可重复、可版本控制。GitLab官方提供的Docker镜像已经预配置了所有必要组件包括Nginx、PostgreSQL、Redis等但默认的单容器方案并不适合生产环境。我在实际项目中踩过的坑包括数据丢失风险、性能瓶颈、升级困难等。而通过Docker Compose编排可以实现服务分离数据库、缓存等组件独立部署资源隔离为不同服务分配CPU/内存限制灵活扩展未来可轻松添加CI Runner等组件2. 基础环境准备2.1 硬件资源配置建议根据我的经验GitLab对资源的需求是这样的开发测试环境2核CPU/4GB内存/50GB存储20人团队生产环境4核CPU/8GB内存/200GB存储100人以上团队建议8核CPU/16GB内存SSD存储特别提醒GitLab运行时会启动多个Unicorn worker进程内存不足会导致502错误。我曾在一个2GB内存的机器上部署结果频繁崩溃后来发现官方建议至少4GB。2.2 软件依赖安装首先确保宿主机已安装最新版Docker和Docker Compose# 安装Docker curl -fsSL https://get.docker.com | sh sudo systemctl enable --now docker # 安装Docker Compose sudo curl -L https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose sudo chmod x /usr/local/bin/docker-compose验证安装docker --version # 应显示Docker版本 docker-compose --version # 应显示Compose版本3. 编写docker-compose.yml文件3.1 最小化生产配置这是我经过多个项目验证的基础模板version: 3.8 services: gitlab: image: gitlab/gitlab-ce:latest container_name: gitlab hostname: gitlab.yourdomain.com restart: unless-stopped environment: GITLAB_OMNIBUS_CONFIG: | external_url https://gitlab.yourdomain.com gitlab_rails[time_zone] Asia/Shanghai gitlab_rails[gitlab_shell_ssh_port] 2222 ports: - 80:80 - 443:443 - 2222:22 volumes: - ./gitlab/config:/etc/gitlab - ./gitlab/logs:/var/log/gitlab - ./gitlab/data:/var/opt/gitlab shm_size: 256m关键参数说明hostname必须设置为最终访问的域名GITLAB_OMNIBUS_CONFIGGitLab的核心配置shm_size解决Sidekiq内存不足问题3.2 集成PostgreSQL和Redis生产环境建议使用独立数据库services: postgres: image: postgres:13 container_name: gitlab-postgres environment: POSTGRES_USER: gitlab POSTGRES_PASSWORD: your_strong_password POSTGRES_DB: gitlabhq_production volumes: - ./postgres/data:/var/lib/postgresql/data restart: unless-stopped healthcheck: test: [CMD-SHELL, pg_isready -U gitlab] interval: 10s timeout: 5s retries: 5 redis: image: redis:6 container_name: gitlab-redis command: [redis-server, --requirepass yourredispassword] volumes: - ./redis/data:/data restart: unless-stopped healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5 gitlab: depends_on: postgres: condition: service_healthy redis: condition: service_healthy environment: GITLAB_OMNIBUS_CONFIG: | postgresql[enable] false redis[enable] false gitlab_rails[db_adapter] postgresql gitlab_rails[db_host] postgres gitlab_rails[db_port] 5432 gitlab_rails[db_username] gitlab gitlab_rails[db_password] your_strong_password gitlab_rails[redis_host] redis gitlab_rails[redis_port] 6379 gitlab_rails[redis_password] yourredispassword4. HTTPS安全配置4.1 自动获取Lets Encrypt证书最简便的HTTPS配置方式environment: GITLAB_OMNIBUS_CONFIG: | letsencrypt[enable] true letsencrypt[contact_emails] [adminyourdomain.com] letsencrypt[auto_renew] true letsencrypt[auto_renew_hour] 0 letsencrypt[auto_renew_minute] 30 letsencrypt[auto_renew_day_of_month] */44.2 手动配置已有证书如果有商业证书可以这样配置mkdir -p gitlab/config/ssl # 将证书文件放入gitlab/config/ssl # 重命名为gitlab.yourdomain.com.crt和gitlab.yourdomain.com.key然后在docker-compose.yml中添加environment: GITLAB_OMNIBUS_CONFIG: | nginx[ssl_certificate] /etc/gitlab/ssl/gitlab.yourdomain.com.crt nginx[ssl_certificate_key] /etc/gitlab/ssl/gitlab.yourdomain.com.key nginx[redirect_http_to_https] true5. 生产环境优化配置5.1 资源限制与健康检查防止GitLab占用过多资源gitlab: deploy: resources: limits: cpus: 2 memory: 4G reservations: memory: 2G healthcheck: test: [CMD, /opt/gitlab/bin/gitlab-healthcheck, --fail] interval: 1m timeout: 10s retries: 35.2 邮件通知配置以腾讯企业邮箱为例environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails[smtp_enable] true gitlab_rails[smtp_address] smtp.exmail.qq.com gitlab_rails[smtp_port] 465 gitlab_rails[smtp_user_name] gitlabyourdomain.com gitlab_rails[smtp_password] your_password gitlab_rails[smtp_domain] yourdomain.com gitlab_rails[smtp_authentication] login gitlab_rails[smtp_enable_starttls_auto] true gitlab_rails[smtp_tls] true gitlab_rails[gitlab_email_from] gitlabyourdomain.com测试邮件发送docker exec -it gitlab gitlab-rails console Notify.test_email(recipientexample.com, Test Subject, Test Body).deliver_now6. 日常维护操作6.1 数据备份与恢复配置自动备份environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails[backup_path] /var/opt/gitlab/backups gitlab_rails[backup_keep_time] 604800 # 保留7天手动备份命令docker exec -it gitlab gitlab-backup create恢复备份# 先将备份文件放入gitlab/data/backups docker exec -it gitlab gitlab-backup restore BACKUP文件名前缀6.2 版本升级步骤安全升级流程停止当前容器docker-compose stop gitlab备份数据docker-compose exec gitlab gitlab-backup create拉取新镜像docker-compose pull gitlab启动新版本docker-compose up -d gitlab监控日志docker-compose logs -f gitlab建议在非工作时间进行升级大型版本升级如14→15可能需要更长时间。7. 常见问题排查问题1502 Whoops错误检查内存是否不足docker stats gitlab查看日志docker logs --tail 100 gitlab解决方案增加内存或调整Unicorn worker数量问题2SSH克隆失败确认gitlab_rails[gitlab_shell_ssh_port]与映射端口一致检查防火墙规则iptables -L -n问题3邮件发送失败测试Telnet连接docker exec -it gitlab telnet smtp.exmail.qq.com 465检查垃圾邮件箱尝试更换端口465/587问题4容器启动超时增加启动超时时间gitlab: deploy: resources: limits: cpus: 4 memory: 8G healthcheck: start_period: 10m记得第一次成功部署GitLab后我兴奋地给团队发邮件通知结果因为SMTP配置错误所有人都没收到邮件。后来通过docker exec -it gitlab tail -f /var/log/gitlab/mailroom/current才找到问题所在——邮箱密码里有个特殊字符需要转义。这种实战经验才是真正宝贵的知识。