1. 为什么选择Docker部署GitLab从裸机到容器的思路转变很多团队第一次搭GitLab都是直接apt install或者下载omnibus包装完发现系统里多了一堆Ruby、PostgreSQL、Redis、Nginx的进程升级的时候还得小心翼翼处理依赖冲突。我最早也是这么干的一台4核8G的机器跑起来倒也能用但每次系统更新都提心吊胆生怕某个库版本对不上把GitLab搞崩。后来全面转向Docker部署核心原因有三个。第一是环境隔离彻底GitLab官方镜像把Rails应用、数据库、缓存、反向代理全部打包在一个容器里跟宿主机系统完全解耦系统怎么升级都不影响容器内部运行。第二是版本管理清晰镜像tag直接对应GitLab版本号回滚就是换个tag重启的事比omnibus的升级脚本靠谱得多。第三是迁移方便把数据卷目录打包拷到另一台机器挂载后启动容器就能恢复换服务器跟换衣服一样简单。但Docker部署GitLab也有它的坑。最典型的就是性能问题——容器默认的资源限制、文件系统层的读写开销、内存分配策略都会让GitLab跑起来比裸机慢一截。尤其是GitLab本身是个内存大户官方推荐最低4GB内存实际用起来8GB才勉强舒服16GB才能算流畅。所以这篇内容的核心不是怎么把容器跑起来而是跑起来之后怎么让它不卡。这篇文章适合两类人看一类是刚接触Docker、想用容器方式搭一套私有GitLab服务的运维或开发另一类是已经用Docker跑着GitLab、但总觉得响应慢、推送卡、页面加载转圈的老用户。我会从镜像选型、目录规划、参数配置、性能调优、问题排查几个维度把踩过的坑和验证过的方案完整讲一遍。所有操作都基于常见的Linux发行版和Docker环境不涉及任何特定厂商或平台。2. 部署前的整体设计与资源规划2.1 镜像选型为什么用官方镜像而不是第三方Docker Hub上搜gitlab能出来一堆镜像有官方的gitlab/gitlab-ce、gitlab/gitlab-ee也有各种第三方精简版。我的建议很明确生产环境只用官方镜像。原因很简单GitLab的组件依赖极其复杂第三方精简版往往砍掉了某些服务或者改了启动逻辑短期看着省资源长期用下来升级、备份、排障全是坑。官方镜像分两个版本CE社区版和EE企业版。CE免费功能对中小团队完全够用EE有额外的合并请求审批、代码质量分析等高级功能但需要许可证。个人和小团队直接用CE就行镜像名是gitlab/gitlab-ce。关于tag的选择不建议用latest。GitLab的版本迭代很快每个大版本都可能引入配置变更或数据库迁移。用具体版本号tag比如gitlab/gitlab-ce:16.11.0-ce.0升级时手动改tag可控性高得多。我一般会选一个稳定的大版本跟到该版本的最后一个patch然后等下一个大版本稳定了再整体升级。2.2 目录规划数据卷怎么挂才合理GitLab容器需要持久化的数据主要有三块配置、日志、数据。官方镜像里对应的路径是/etc/gitlab、/var/log/gitlab、/var/opt/gitlab。这三个目录必须挂到宿主机上否则容器一删数据全没。我的目录规划习惯是这样的/opt/gitlab/ ├── config/ # 对应 /etc/gitlab ├── logs/ # 对应 /var/log/gitlab └── data/ # 对应 /var/opt/gitlab为什么放在/opt下因为/opt通常是独立分区或者至少空间充裕而且路径短、好记。有些教程建议放/srv或者/home都行关键是确保所在分区有足够空间。GitLab的数据增长主要来自Git仓库本身和CI的构建缓存一个中等规模的团队一年下来几十GB很正常所以数据目录所在分区最好留出100GB以上的余量。还有一个细节宿主机目录的权限。GitLab容器内运行的用户UID通常是998不同版本可能不同如果宿主机目录权限不对容器启动时会报权限错误。最省事的做法是先把目录建好权限设成755让容器自己去初始化。如果遇到权限问题再根据日志里的UID去调整。2.3 端口与网络模式的选择GitLab容器需要暴露的端口主要有三个HTTP80、HTTPS443、SSH22。但宿主机的22端口通常已经被系统SSH占用了所以GitLab的SSH端口需要映射到别的端口比如2222。网络模式上我推荐用桥接模式加端口映射而不是host模式。host模式虽然省去了NAT开销但端口冲突问题很烦而且不利于多容器共存。桥接模式下容器内部端口不变宿主机映射端口按需调整灵活性更好。端口映射的典型配置容器内端口宿主机端口用途808080HTTP访问4438443HTTPS访问222222Git SSH克隆这里有个容易忽略的点external_url的配置必须和实际访问地址一致。如果你映射的是8080那external_url就得写成http://你的IP:8080否则GitLab生成的克隆地址、邮件里的链接全是错的。这个坑我踩过不止一次页面能打开但克隆地址不对排查半天才发现是URL没配对。3. 核心部署实操从零到能用的完整流程3.1 环境准备与Docker安装检查在开始之前先确认宿主机的基础环境。我习惯先跑一遍检查命令# 查看系统版本和内核 uname -a cat /etc/os-release # 查看Docker版本 docker --version docker compose version # 查看内存和CPU free -h nproc # 查看磁盘空间 df -h /optGitLab对资源的要求官方给的最低配置是2核4GB但那是能跑起来的底线。实际使用中我的经验值是5人以下小团队4核8GB起步20人左右团队8核16GB再往上就得考虑拆分部署了。内存不足是GitLab卡顿的头号原因后面调优部分会详细讲怎么控制内存。Docker的安装这里不展开各发行版的包管理命令不一样按官方文档走就行。重点确认两件事Docker服务正常运行当前用户有权限执行docker命令或者在root下操作。3.2 拉取镜像与启动容器先拉镜像。这一步网络可能比较慢镜像大小在2GB左右耐心等docker pull gitlab/gitlab-ce:16.11.0-ce.0然后创建目录并启动容器。我习惯用docker run直接起也可以用compose看个人喜好。先给run的版本# 创建目录 mkdir -p /opt/gitlab/{config,logs,data} # 启动容器 docker run -d \ --name gitlab \ --restart always \ --hostname gitlab.example.com \ -p 8080:80 \ -p 8443:443 \ -p 2222:22 \ -v /opt/gitlab/config:/etc/gitlab \ -v /opt/gitlab/logs:/var/log/gitlab \ -v /opt/gitlab/data:/var/opt/gitlab \ --shm-size 512m \ gitlab/gitlab-ce:16.11.0-ce.0这里有几个参数值得说明。--restart always保证容器异常退出或宿主机重启后自动拉起生产环境必加。--hostname设置容器主机名会影响GitLab生成的某些内部链接建议设成实际访问的域名或IP。--shm-size 512m是给共享内存扩容GitLab的某些组件比如PostgreSQL会用到默认64MB有时候不够。如果你更喜欢compose等价的配置是这样version: 3.8 services: gitlab: image: gitlab/gitlab-ce:16.11.0-ce.0 container_name: gitlab restart: always hostname: gitlab.example.com ports: - 8080:80 - 8443:443 - 2222:22 volumes: - /opt/gitlab/config:/etc/gitlab - /opt/gitlab/logs:/var/log/gitlab - /opt/gitlab/data:/var/opt/gitlab shm_size: 512m3.3 首次启动的等待与配置修改容器启动后不要急着访问。GitLab首次启动要初始化数据库、编译资源这个过程根据机器性能不同可能要3到10分钟。你可以用日志观察进度docker logs -f gitlab看到类似gitlab Reconfigured!或者Starting puma之类的输出说明初始化差不多了。这时候先别打开页面先去改配置文件因为默认配置里有些东西必须调整。配置文件在/opt/gitlab/config/gitlab.rb。用编辑器打开找到external_url这一行改成实际访问地址external_url http://你的IP:8080然后找到SSH相关的配置因为宿主机22端口被占用GitLab的SSH也得改gitlab_rails[gitlab_shell_ssh_port] 2222改完配置后需要让GitLab重新加载docker exec -it gitlab gitlab-ctl reconfigure这个reconfigure过程也会花几分钟同样耐心等。完成后就可以用浏览器访问http://你的IP:8080了。首次访问会要求设置root密码设一个强密码然后就能用root登录了。注意reconfigure之后如果页面打不开先检查容器是否还在运行docker ps再看日志有没有报错。常见的是端口冲突或目录权限问题。4. 性能调优让GitLab从能用到好用4.1 内存控制Puma与Sidekiq的worker调优GitLab最吃内存的两个组件是PumaWeb服务和Sidekiq后台任务。默认配置下Puma会启动的worker数量跟CPU核数挂钩Sidekiq的并发数也不低在小内存机器上很容易把内存吃满然后触发OOM。先看Puma的配置。在gitlab.rb里puma[worker_processes] 2 puma[min_threads] 1 puma[max_threads] 4worker_processes的默认值是CPU核数但每个worker大概占300MB到500MB内存。4核机器默认起4个worker光Puma就吃掉2GB。对于8GB内存的机器我建议设成216GB可以设成4。max_threads控制每个worker的线程数默认是4一般不用改。再看Sidekiqsidekiq[max_concurrency] 10默认并发数是20每个并发大概占100MB到200MB。小内存机器上设成10甚至5都可以代价是后台任务处理慢一点但总比OOM强。还有一个内存相关的参数是gitlab_rails[memory_killer]相关的配置不过新版本里这块逻辑有变化不建议手动去调重点还是控制worker数量。调完之后reconfigure然后用docker stats gitlab观察内存占用。正常情况下空闲时内存应该在3GB到5GB之间8GB机器、2个Puma worker、10个Sidekiq并发的配置。4.2 PostgreSQL的共享缓冲区调整GitLab内置了PostgreSQL默认的共享缓冲区配置比较保守。在gitlab.rb里可以调整postgresql[shared_buffers] 1GB postgresql[effective_cache_size] 2GB postgresql[work_mem] 16MB postgresql[maintenance_work_mem] 128MBshared_buffers一般设成总内存的1/4左右8GB机器设1GB到2GB都合理。effective_cache_size设成总内存的一半到2/3告诉查询规划器系统大概有多少缓存可用。work_mem是每个排序或哈希操作能用的内存设太大容易在并发高时爆内存16MB是个稳妥值。这些参数调整后需要reconfigurePostgreSQL会重启。注意reconfigure期间GitLab服务会短暂中断选个没人用的时候操作。4.3 文件系统与IO相关的优化Docker默认的存储驱动是overlay2对于GitLab这种IO密集的应用有几个点可以优化。第一数据目录尽量放在SSD上。Git仓库的读写、数据库的操作对磁盘IO要求不低。机械硬盘跑GitLab页面加载和git clone的体验会明显差一截。第二考虑用volume而不是bind mount。bind mount直接把宿主机目录挂进容器性能上其实没差多少但volume由Docker管理在某些场景下IO路径更短。不过volume的缺点是路径不好找备份的时候得先查volume位置。我个人还是习惯bind mount因为路径直观备份方便。第三日志的IO也不容忽视。GitLab的日志量不小如果日志目录和数据库目录在同一个物理盘上IO竞争会比较明显。有条件的话把/opt/gitlab/logs单独挂一块盘或者至少确保日志轮转配置合理别让日志无限增长。日志轮转在gitlab.rb里配置logging[logrotate_frequency] daily logging[logrotate_rotate] 30 logging[logrotate_size] 100M这样每天轮转一次保留30份单个文件超过100MB也触发轮转。4.4 关闭不需要的功能模块GitLab全家桶里有些功能不是每个团队都用得上关掉能省不少资源。常见的可以关闭的模块# 关闭Prometheus监控如果不用GitLab自带的监控 prometheus_monitoring[enable] false # 关闭Grafana grafana[enable] false # 关闭GitLab Pages如果不用静态站点托管 gitlab_pages[enable] false # 关闭Mattermost如果不用内置聊天 mattermost[enable] falsePrometheus和Grafana这两个监控组件加起来能占几百MB内存不用的话果断关掉。GitLab Pages和Mattermost也是类似用不到就关。不过要注意关闭Prometheus后GitLab管理后台的监控面板会没数据这是正常的。如果你需要监控GitLab本身的运行状态可以自己搭一套外部的监控系统比内置的灵活。5. 常见问题与排查技巧实录5.1 容器启动后页面502或无法访问这是最常见的问题原因通常有几个。先看容器状态docker ps -a | grep gitlab如果状态是Restarting或者Exited说明容器启动就失败了。看日志docker logs --tail 100 gitlab日志里如果有Permission denied那就是目录权限问题。检查/opt/gitlab下三个目录的权限确保容器内用户能读写。最简单的办法是先把权限放宽到777测试确认是权限问题后再收紧到合理值。如果容器在运行但页面502通常是GitLab内部服务还没完全启动。首次启动或者reconfigure后Puma启动需要时间等几分钟再试。如果等了很久还是502进容器看内部服务状态docker exec -it gitlab gitlab-ctl status看哪个服务是down的然后单独看那个服务的日志。5.2 内存不足导致服务被OOM Killer干掉症状是容器突然重启日志里有Killed或者Out of memory字样。用dmesg看系统日志也能看到OOM的记录。解决办法就是前面调优部分讲的减少Puma worker和Sidekiq并发。如果调了还不够那就只能加内存。GitLab这玩意内存给够了什么都好说内存不够怎么调都是拆东墙补西墙。还有一个应急手段是给容器加内存限制让Docker在容器级别做控制docker update --memory 6g --memory-swap 8g gitlab但注意这个限制如果设得比实际需求低容器会被直接杀掉所以设之前先观察实际用量。5.3 Git clone速度慢或推送卡顿这个问题排查起来分几个层面。先确认网络层面没问题然后在服务器上直接测试git操作# 进容器测试 docker exec -it gitlab bash git clone http://localhost/xxx/xxx.git /tmp/test如果容器内部clone很快但外部慢那就是网络或者反向代理的问题。如果容器内部也慢那就是GitLab本身或者磁盘IO的问题。磁盘IO可以用iostat看如果%util长期接近100%说明磁盘是瓶颈。GitLab的Git仓库存储在/var/opt/gitlab/git-data下这个目录所在盘的性能直接决定clone和push的速度。另外GitLab的Housekeeping也会影响性能。仓库大了之后定期执行git gc能压缩仓库体积、提升访问速度。可以在管理后台手动触发也可以配置自动执行。5.4 备份与恢复的注意事项Docker部署的GitLab备份命令是docker exec -it gitlab gitlab-backup create备份文件默认在/var/opt/gitlab/backups下对应宿主机的/opt/gitlab/data/backups。但注意这个备份不包含配置文件/etc/gitlab下的东西所以完整的备份策略是备份数据 备份配置目录。恢复的时候先把容器停掉把备份文件放到指定位置然后执行恢复命令。恢复过程中GitLab的服务是停止的恢复完成后需要reconfigure。提示备份文件可能很大尤其是仓库多的时候。建议定期把备份文件同步到另一台机器或者对象存储别跟GitLab放同一块盘。5.5 常见问题速查表问题现象可能原因排查方向解决手段页面502服务未启动完gitlab-ctl status等待或重启容器容器反复重启内存不足dmesg看OOM减少worker或加内存权限错误目录UID不匹配日志中的Permission denied调整目录权限clone慢磁盘IO瓶颈iostat看%util换SSD或优化存储邮件发不出SMTP配置错误测试邮件发送检查smtp配置升级后报错数据库迁移未完成日志中的migration等待或手动迁移6. 升级维护与长期运行的经验6.1 版本升级的正确姿势GitLab的升级有个基本原则不能跨大版本升级。比如从15.x升到16.x必须先升到15.x的最后一个版本再升16.0再升16.x的最新。跨版本直接升数据库迁移大概率出问题。Docker部署的升级流程相对简单先备份然后拉新版本镜像停旧容器用同样的目录挂载启动新容器。但注意新容器的镜像tag变了其他参数要保持一致。# 备份 docker exec -it gitlab gitlab-backup create # 拉新镜像 docker pull gitlab/gitlab-ce:16.11.1-ce.0 # 停旧容器 docker stop gitlab docker rm gitlab # 用新镜像启动 docker run -d --name gitlab ... gitlab/gitlab-ce:16.11.1-ce.0启动后观察日志等reconfigure完成。如果升级过程中出错日志里会有明确提示根据提示处理。实在不行就回滚到旧镜像用备份恢复数据。6.2 日常维护的几个习惯跑了一段时间之后我养成了几个维护习惯。每周看一眼磁盘空间GitLab的数据增长有时候比预期快尤其是CI的构建产物。每月检查一次日志看看有没有反复出现的错误。每次升级前必做备份而且备份文件要验证能恢复。还有一个容易被忽略的是容器日志的清理。Docker的容器日志默认是json-file驱动不限制大小的话会一直涨。可以在启动容器时加日志限制--log-opt max-size100m --log-opt max-file3这样单个日志文件最大100MB最多保留3个总共不超过300MB。6.3 什么情况下该考虑拆分部署Docker单容器部署GitLab适合中小团队。当团队规模上去之后单容器的瓶颈会越来越明显。几个信号内存长期吃紧、CI任务排队严重、页面响应明显变慢。这时候可以考虑拆分部署把PostgreSQL、Redis、Gitaly这些组件独立出来GitLab主容器只跑Rails应用。拆分之后每个组件可以独立扩容整体性能会好很多。但拆分的复杂度也高不少配置、网络、备份策略都要重新设计适合有一定运维能力的团队。对于大多数团队来说把单容器部署调优到位比盲目拆分更实际。我见过不少团队单容器都没调明白就急着拆分结果问题更多。先把Puma、Sidekiq、PostgreSQL这几个关键参数调好内存给够磁盘用SSD大部分性能问题都能解决。我个人在实际操作中的体会是GitLab的调优没有一劳永逸的方案得根据实际使用情况不断调整。刚开始可以按保守配置来然后观察docker stats和GitLab管理后台的监控数据哪里是瓶颈就调哪里。内存、CPU、磁盘IO这三个里面通常有一个是主要瓶颈找到它针对性优化效果最明显。