前阵子在交流群里看到有人吐槽公司GitLab跑了大半年版本还停在很老的位置每次看到新版本发布都不敢升级因为当年图省事一条docker run把GitLab全家桶塞进同一个容器里数据库、代码、配置全混在一起。这场景我太熟悉了。官方镜像默认自带PostgreSQL开箱即用确实香但开箱即用的另一面是“一锅端”——只要容器重建、升级、迁移出一点问题数据和应用可能一起遭殃。后来我把自己维护的环境改成了分离部署GitLab容器只负责应用层PostgreSQL单独跑一个容器通过Docker网络互通。这个改法不复杂但中间有不少细节值得记录比如版本匹配、数据卷权限、健康检查、备份恢复顺序每一样都能让人踩坑。这篇文章就从零开始把Docker部署GitLab、数据库分离部署的完整思路和实操过程讲清楚适合理想上手的运维、开发者也适合已经被“一体机”折腾过的团队参考。1. 为什么要把数据库拆出来不拆的代价升级一次就懂1.1 一个容器跑到底省事但埋雷GitLab官方容器镜像gitlab/gitlab-ce看着很省事docker run的时候把80端口和22端口映射出来过几分钟就能打开网页。但它内部的架构是Omnibus全家桶PostgreSQL、Redis、Nginx、Gitaly、Sidekiq、Prometheus全都挤在一个容器里。对个人学习或小团队试用来说这完全没问题但当你把它当成团队正式的代码托管平台问题就逐渐浮出来了。我自己见过最典型的翻车场景是升级小版本。有人看到新镜像Tag没仔细看数据卷有没有挂对直接docker pull然后重新docker run结果容器起来了之前创建的仓库却全部消失。原因很简单数据库和仓库数据默认写在容器可写层里容器一旦被重建旧数据就跟着原容器一起没了。就算你把/etc/gitlab、/var/opt/gitlab挂出来了也只是挂了一层“外壳”里面内置的PostgreSQL数据文件依然混在/var/opt/gitlab/postgresql里备份、迁移、单独升级全都受制于这个大杂烩。一体机架构还有一个隐性成本排查问题的边界不清晰。GitLab页面打不开到底是Nginx的问题、数据库的问题还是Sidekiq没起来在一个容器里全得靠gitlab-ctl status逐个猜。而分离部署后GitLab和PostgreSQL各是一个独立服务日志分开、资源占用分开谁出问题看谁的日志就行。1.2 分离部署带来的实打实好处把数据库拆出去之后最直接的收益是升级不再“一荣俱荣一损俱损”。GitLab容器升级时数据库这边稳定不动万一升级失败要回滚只需要把GitLab容器换回旧镜像Tag数据库还是原来那份回滚成本低很多。备份和恢复的灵活性也完全不一样。一体机环境下做备份只能靠GitLab自带的gitlab-backup打包整个应用状态备份文件动辄几个G恢复时也要整套环境一起恢复。数据库分离之后可以针对PostgreSQL容器单独做pg_dump数据库备份和应用备份解耦。比如只想查某张表的数据、只想验证数据库备份是否完整都可以直接对PostgreSQL动手不用碰GitLab本体。另一个容易被忽略的好处是资源管理。GitLab是出了名的内存大户官方推荐起步4GB内存但PostgreSQL和GitLab应用的内存特征不同拆开之后可以分别观察内存占用。我甚至见过把PostgreSQL放到性能更好的机器上、GitLab留在普通虚拟机的玩法这种弹性是一体机给不了的。1.3 拆完之后架构长什么样这套分离架构在容器层面就两个核心服务postgres容器跑PostgreSQL数据存在独立数据卷里只在内部Docker网络暴露5432端口。gitlab容器跑GitLab主应用连接postgres容器作为外部数据库对外只暴露HTTP和SSH端口。可选地Redis也可以拆出去单独跑一个容器。我在实际部署里先保留了GitLab容器内置Redis因为Redis本身相对轻量、状态也没有那么关键先把数据库拆分做好已经能解决80%的维护痛点。如果你的团队规模很大、GitLab负载很高可以考虑把Redis也拆出来配置方式类似设置gitlab_rails[redis_host]指向独立的Redis容器或外部Redis服务即可。整个访问链路是用户通过浏览器访问GitLab的HTTP端口GitLab处理请求时通过自定义Docker网络访问PostgreSQL容器读取数据仓库的Git操作走SSH端口用户提交代码触发GitLab的Sidekiq后台任务写数据库和文件系统。理解了这个链路后面的配置才不会乱。2. 方案选型和环境准备别急着敲命令先定版本和端口2.1 版本搭配合宜少走一半弯路分离部署最大的坑之一就是版本兼容。GitLab官方镜像内置的PostgreSQL版本和GitLab本身是绑定测试过的你要拆出去就必须选一个GitLab官方支持的外部PostgreSQL版本版本跨度太大GitLab启动时数据库迁移会报错但容器日志里经常是模棱两可的“failed to connect”或“database migration error”。我的习惯是用一个比较保守的组合比如GitLab 16.x系列搭配PostgreSQL 14或15GitLab 17.x系列搭配PostgreSQL 14或15为主。更稳妥的做法是每次准备升级GitLab大版本之前先去查官方升级文档里的数据库版本支持表GitLab 15.x要求PostgreSQL至少12.10GitLab 16.x官方推荐13/14GitLab 17.x时代会更倾向14/15。注意这里的版本号是PostgreSQL的大版本向后兼容关系尽量选官方验证过的组合不要为了“尝新”盲目上最新版PostgreSQL。镜像Tag也建议锁版本不要用latest。gitlab/gitlab-ce:latest今天拉下来和三个月后拉下来可能不是同一个版本哪天重新部署一台新机器环境就和线上不一致了。我习惯在Compose文件里写死小版本比如gitlab/gitlab-ce:16.4.4-ce.0升级是明确、主动的行为而不是“某天不小心拉了个新镜像”。2.2 网络、域名和端口先定再配GitLab有一个配置项叫external_url它决定了网页上所有仓库的克隆地址、网页链接、Webhook回调地址。这个一定在部署前想清楚否则后面一堆“页面能打开但URL不对”的奇怪问题。如果团队有域名直接把external_url设为http://gitlab.example.com用80端口对外如果暂时只有IP就设为http://服务器IP。需要HTTPS的话可以再挂443端口在GitLab配置里启用Lets Encrypt或自己放证书但为了讲清楚分离部署的核心逻辑我这里先用HTTP方案。SSH端口规划是另一个容易忽略的地方。GitLab容器内部SSH固定是22端口宿主机22端口很可能已经被系统SSH占了所以普遍做法是把宿主机的2222端口映射到容器的22端口。这样配置之后所有仓库的SSH克隆地址就不是git域名:group/repo.git而是要写成ssh://git域名:2222/group/repo.git要提前同步给团队别等大家第一次克隆失败再来问。2.3 数据卷规划和权限意识GitLab容器需要持久化的目录主要是三个/etc/gitlab配置文件包括gitlab.rb和gitlab-secrets.json。/var/opt/gitlab应用数据包括仓库数据、备份文件、内置组件状态。/var/log/gitlab日志。PostgreSQL容器只需要一个数据目录/var/lib/postgresql/data。我建议在宿主机建一个项目专属目录比如/opt/gitlab-stack下面的data/gitlab和data/postgres分别对应两个容器。这样以后想整体迁移直接把目录拷走就行。目录权限是新手踩坑重灾区。GitLab容器内部很多服务以UID998运行宿主机挂载目录如果属主不是998容器启动时没有写权限日志里就会出现/var/opt/gitlab/git-data has wrong permissions之类的错误。解决方式很简单初始化时执行chown -R 998:998 /opt/gitlab-stack/data/gitlabPostgreSQL容器的数据目录也有类似问题。如果你挂载的宿主机目录权限和镜像期望不一致PostgreSQL容器会直接退出日志提示数据目录权限有问题。稳妥的做法是先让容器自动初始化如果报权限错误根据日志里提示的UID执行chown这一步不用太早纠结权限错了看日志改就行。3. Docker Compose完整实现一份能直接改的编排文件3.1 先放上完整编排文件直接给出一份可以改改就用的docker-compose.yml。我已经把关键配置都写进去了注释和参数解释放在后面。version: 3.8 networks: gitlab-net: driver: bridge services: postgres: image: postgres:14-alpine container_name: gitlab-postgres restart: always environment: TZ: Asia/Shanghai POSTGRES_USER: gitlab POSTGRES_PASSWORD: 替换成强密码 POSTGRES_DB: gitlabdb volumes: - ./data/postgres:/var/lib/postgresql/data networks: - gitlab-net healthcheck: test: [CMD-SHELL, pg_isready -U gitlab -d gitlabdb] interval: 10s timeout: 5s retries: 5 gitlab: image: gitlab/gitlab-ce:16.4.4-ce.0 container_name: gitlab restart: always hostname: gitlab.example.com ports: - 80:80 - 2222:22 environment: GITLAB_OMNIBUS_CONFIG: | external_url http://gitlab.example.com postgresql[enable] false gitlab_rails[db_host] postgres gitlab_rails[db_port] 5432 gitlab_rails[db_username] gitlab gitlab_rails[db_password] 替换成强密码 gitlab_rails[db_database] gitlabdb redis[enable] true gitlab_rails[time_zone] Asia/Shanghai prometheus_monitoring[enable] false gitlab_rails[backup_path] /var/opt/gitlab/backups volumes: - ./data/gitlab/config:/etc/gitlab - ./data/gitlab/logs:/var/log/gitlab - ./data/gitlab/data:/var/opt/gitlab networks: - gitlab-net depends_on: postgres: condition: service_healthy这套编排文件里PostgreSQL没有对外暴露5432端口只通过gitlab-net这个内部网络提供给GitLab容器使用。很多人习惯给数据库也加一个ports映射其实没必要反而把数据库暴露到宿主机网络增加了风险。真要排查数据库问题用docker compose exec postgres psql进入容器操作就行。3.2 PostgreSQL容器的初始化逻辑postgres:14-alpine这个镜像在数据目录为空时会执行初始化流程并根据环境变量自动创建用户和数据库。这里三个环境变量要配齐POSTGRES_USER业务用户这里设为gitlab。POSTGRES_PASSWORD业务用户密码GitLab连接数据库时用同一个。POSTGRES_DB业务数据库名这里设为gitlabdb和后面GitLab配置里的db_database必须一致。如果你只设置了密码忘了设置POSTGRES_DB容器起来后只会创建一个默认的postgres数据库GitLab启动时找不到gitlabdb就会一直卡在数据库等待状态。另外要注意这些环境变量只在数据目录为空、首次初始化时生效。如果挂载的数据目录已经存在PostgreSQL会直接使用已有数据环境变量会被忽略。这一点在升级、迁移时尤其要注意不要以为改了POSTGRES_PASSWORD环境变量就能改数据库密码改了也不会生效。3.3 GitLab容器改连外部数据库GitLab容器连接外部数据库的配置关键全在GITLAB_OMNIBUS_CONFIG这个环境变量里。拆开来看postgresql[enable] false gitlab_rails[db_host] postgres gitlab_rails[db_port] 5432 gitlab_rails[db_username] gitlab gitlab_rails[db_password] 替换成强密码 gitlab_rails[db_database] gitlabdbpostgresql[enable] false是灵魂配置。如果不关掉内置PostgreSQLGitLab容器起来后还是会尝试启动自带数据库你会看到两个PostgreSQL同时跑一个在容器内部一个在外部容器然后端口和进程互相干扰。这个配置项我是建议放在第一行时刻提醒自己“这里已经改用外部数据库了”。gitlab_rails[db_host]写成postgres不是localhost也不是写一串IP。因为两个容器在同一个自定义网络gitlab-net里Compose的DNS解析会把服务名postgres解析成对应容器的IP。用服务名连接的好处是容器重建后IP变了也不需要改配置这是容器间通信的推荐做法。3.4 启动顺序、健康检查与后续调整GitLab容器启动时要做数据库迁移如果PostgreSQL还没准备好就可能报连接错误。depends_on加condition: service_healthy的作用是让编排器等PostgreSQL容器通过健康检查后再启动GitLab容器。健康检查的命令pg_isready -U gitlab -d gitlabdb会在PostgreSQL容器内部执行每隔10秒探测一次连续5次成功才标记为healthy。第一次启动时GitLab容器初始化比较慢等1到3分钟都很正常。想确认启动进度用这两个命令docker compose logs -f gitlab docker compose exec gitlab gitlab-ctl status看到类似“gitlab Reconfigured!”的日志以及run: sidekiq、run: puma等状态基本就说明起来了。如果中间改了GITLAB_OMNIBUS_CONFIG里的配置最好直接执行docker compose down再docker compose up -d重新创建容器让镜像入口程序重新执行配置有时候图省事只docker restart配置不一定会重新应用这种“改了没生效”的坑很常见。4. 备份、恢复与日常升级分离架构最大的红利在这4.1 GitLab自带备份和数据库备份怎么配合先说结论建议两套备份都做。GitLab自带备份负责应用层和数据库层的整体一致性数据库独立备份负责PG容器层面的快速恢复和安全网。GitLab自带备份非常简单在项目目录下执行docker compose exec -T gitlab gitlab-backup create备份文件默认生成在/var/opt/gitlab/backups目录因为我们已经把/var/opt/gitlab挂载到了宿主机所以备份文件会直接出现在./data/gitlab/data/backups下复制走即可。这个备份里包含GitLab的完整数据库快照、仓库数据、上传附件、CI/CD配置等是恢复GitLab最完整的“后悔药”。只跑GitLab自带备份够不够在一体机架构下确实够但分离之后我建议再加一层数据库独立备份。做法很简单用pg_dump从PostgreSQL容器里导出数据归档docker exec gitlab-postgres pg_dump -U gitlab -F c -f /tmp/gitlab_$(date %F).dump gitlabdb docker cp gitlab-postgres:/tmp/gitlab_$(date %F).dump /data/gitlab-backup/-F c表示输出为自定义压缩格式后面恢复可以用pg_restore灵活选择表。这个备份依赖的是GitLab应用容器还在运行时做的逻辑备份一致性上不如GitLab自带备份那么强但它有独特价值如果PostgreSQL容器因为数据文件损坏起不来或者整个PG卷丢了你可以先把PostgreSQL容器重建好然后用这个归档恢复数据库基础数据再看情况恢复仓库目录。至少不会所有东西都从头再来。推荐的做法是写一个清理脚本保留最近7天或14天的备份。备份文件一旦忘了清理磁盘满只是时间问题后面GitLab会开始报各种莫名奇妙的错误。4.2 恢复流程顺序错了真会翻车恢复GitLab自带备份的顺序一定要注意。我的标准流程是# 1. 先停掉GitLab容器避免应用写入数据库 docker compose stop gitlab # 2. 恢复数据库层备份如果用了PG独立备份方案 docker exec -i gitlab-postgres pg_restore --clean --if-exists -U gitlab -d gitlabdb /path/to/backup.dump # 3. 或者恢复GitLab自带备份 docker compose start gitlab docker compose exec -T gitlab gitlab-backup restore BACKUP_TIMESTAMP恢复GitLab自带备份时它会尝试连接配置里的外部PostgreSQL然后把整个数据库drop掉再重建。这一步非常危险只应该在明确要回滚的状态下执行。执行前务必再备份一遍当前状态不然恢复失败后连当前数据都找不回来。有一件特别容易忽略的事就是/etc/gitlab/gitlab-secrets.json这个文件。GitLab很多敏感信息比如CI/CD Runner的token、两阶段验证的加密密钥都依赖这个文件。如果只恢复了备份文件但secrets文件缺失或版本不对恢复起来的GitLab会出现Runner失联、Job验证失败等诡异问题。所以在日常备份里一定要把./data/gitlab/config整个目录带上它里面有gitlab.rb和gitlab-secrets.json是恢复时最容易漏掉的一环。4.3 升级版本前必须检查的三件事升级GitLab最怕的就是数据库迁移做到一半卡住然后整个服务起不来。分离部署后升级路径已经清晰很多但有三件事每次都要检查。第一版本跨度。GitLab大版本之间升级有官方路径比如不能从14.x直接跳17.x必须先升到15、再到16、再到17。小版本之间相对宽松但我也见过跳过多个小版本后数据库迁移出问题的案例。别偷懒按官方支持的升级路径走。第二数据库版本兼容。如果GitLab新版本要求PostgreSQL大版本更高比如从PostgreSQL 14升到16.x对应需要15那就要先把PostgreSQL容器升级。不要先拉新GitLab镜像再处理数据库顺序反了GitLab的数据库迁移会直接失败。PostgreSQL的数据目录跨大版本不能直接复用需要pg_upgrade或逻辑导出导入这一步建议单独演练别拿生产环境冒险。第三备份可恢复性。每次升级前跑一遍GitLab自带备份确认目录里生成了新的.tar备份文件并且数据库独立备份也能正常导出。最好每隔一段时间真的找一台测试机恢复一次验证备份不是“看起来存在其实不能恢复”。这个习惯坚持下来能让你在关键时刻不慌。5. 常见问题速查与排障实录这些坑我都替你踩过5.1 高频问题对照表以下是我实际部署和维护中遇到频率最高的问题直接对照排查。现象可能原因排查与解决GitLab容器启动后一直502PostgreSQL还没healthy或连接参数不对docker compose ps查看postgres状态docker compose logs -f gitlab看具体错误日志出现“could not translate host namepostgres”两个容器不在同一网络或db_host写错了确认两个服务都在gitlab-net网络db_host要写服务名postgres克隆地址显示是容器hostnameexternal_url配置不对修改external_url为对外域名/IP重新创建容器SSH克隆仓库失败宿主机2222端口未映射或防火墙没放行确认Compose端口映射2222:22克隆地址带端口ssh://git域名:2222/...报/var/opt/gitlab/git-data has wrong permissions宿主机挂载目录属主不是UID 998执行chown -R 998:998 ./data/gitlab后重启容器PostgreSQL容器反复重启挂载目录权限不对或数据目录被初始化过看PG日志按提示chown对应UID检查数据目录是否非空备份恢复后Runner失联gitlab-secrets.json没随配置一起恢复保留./data/gitlab/config恢复后比对secrets文件磁盘很快被占满备份文件、日志、容器镜像都堆在系统盘数据目录放独立分区备份加保留策略定期清理内存不足容器被OOMGitLab最低要4GB内存加PG会更吃紧扩内存或加swap可关闭Prometheus减少占用5.2 几个容易被忽略的细节还有一个问题容易被忽略如果宿主机80端口已经被Nginx或别的Web服务占用GitLab映射起来会冲突。要么把宿主机端口改成8080:80同时把external_url改成http://域名:8080要么让Nginx反代到GitLab容器。不要傻乎乎地以为容器端口映射失败是GitLab的问题先检查宿主机端口占用。PostgreSQL容器虽然没对外暴露端口但日志里依然能看到访问来源。日常排障进数据库推荐一条命令搞定docker compose exec postgres psql -U gitlab -d gitlabdb -c \dt如果发现GitLab和PostgreSQL两个容器经常因为时间不同步导致日志对不上记得在两边都设置TZ: Asia/Shanghai环境变量避免日志时间差影响排查。最后强调一次网络上一定要用自定义网络服务名连接不要用几个容器共用network_mode: host的方式。虽然host网络模式下容器性能损耗小但GitLab和PostgreSQL会把服务都绑在宿主机端口上数据库、Web服务互相抢占端口和IP维护体验非常痛苦。自定义网络是Docker下多容器协作的标准做法也方便以后迁移、扩容值得坚持。这套架构在我这边稳定运行了很长一段时间最大的感受不是“用了Docker很酷”而是出问题时有清晰的抢救路径。第一次拆分完成后我专门挑了一个低峰时段做恢复演练把GitLab容器和PostgreSQL容器分别模拟故障再恢复整个过程让我彻底放下了对升级的恐惧。如果你也正被一体机架构折磨别等到不得不升级时再拆选一个业务低峰窗口先做完整备份再按这套方案把数据库拎出来。只要备份和恢复流程跑通了后面的每次升级都会轻松很多。