企业官网建设流程全解析

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容器需要暴露的端口主要有三个：HTTP（80）、HTTPS（443）、SSH（22）。但宿主机的22端口通常已经被系统SSH占用了，所以GitLab的SSH端口需要映射到别的端口，比如2222。

网络模式上，我推荐用桥接模式加端口映射，而不是host模式。host模式虽然省去了NAT开销，但端口冲突问题很烦，而且不利于多容器共存。桥接模式下，容器内部端口不变，宿主机映射端口按需调整，灵活性更好。

端口映射的典型配置：

这里有个容易忽略的点：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 /opt

GitLab对资源的要求，官方给的最低配置是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: 512m

3.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最吃内存的两个组件是Puma（Web服务）和Sidekiq（后台任务）。默认配置下，Puma会启动的worker数量跟CPU核数挂钩，Sidekiq的并发数也不低，在小内存机器上很容易把内存吃满然后触发OOM。

先看Puma的配置。在gitlab.rb里：

puma['worker_processes'] = 2 puma['min_threads'] = 1 puma['max_threads'] = 4

worker_processes的默认值是CPU核数，但每个worker大概占300MB到500MB内存。4核机器默认起4个worker，光Puma就吃掉2GB。对于8GB内存的机器，我建议设成2；16GB可以设成4。max_threads控制每个worker的线程数，默认是4，一般不用改。

再看Sidekiq：

sidekiq['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'] = "128MB"

shared_buffers一般设成总内存的1/4左右，8GB机器设1GB到2GB都合理。effective_cache_size设成总内存的一半到2/3，告诉查询规划器系统大概有多少缓存可用。work_mem是每个排序或哈希操作能用的内存，设太大容易在并发高时爆内存，16MB是个稳妥值。

这些参数调整后需要reconfigure，PostgreSQL会重启。注意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'] = false

Prometheus和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 常见问题速查表

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-size=100m --log-opt max-file=3

这样单个日志文件最大100MB，最多保留3个，总共不超过300MB。

6.3 什么情况下该考虑拆分部署

Docker单容器部署GitLab，适合中小团队。当团队规模上去之后，单容器的瓶颈会越来越明显。几个信号：内存长期吃紧、CI任务排队严重、页面响应明显变慢。

这时候可以考虑拆分部署，把PostgreSQL、Redis、Gitaly这些组件独立出来，GitLab主容器只跑Rails应用。拆分之后每个组件可以独立扩容，整体性能会好很多。但拆分的复杂度也高不少，配置、网络、备份策略都要重新设计，适合有一定运维能力的团队。

对于大多数团队来说，把单容器部署调优到位，比盲目拆分更实际。我见过不少团队，单容器都没调明白就急着拆分，结果问题更多。先把Puma、Sidekiq、PostgreSQL这几个关键参数调好，内存给够，磁盘用SSD，大部分性能问题都能解决。

我个人在实际操作中的体会是，GitLab的调优没有一劳永逸的方案，得根据实际使用情况不断调整。刚开始可以按保守配置来，然后观察docker stats和GitLab管理后台的监控数据，哪里是瓶颈就调哪里。内存、CPU、磁盘IO，这三个里面通常有一个是主要瓶颈，找到它，针对性优化，效果最明显。