极狐GitLab双机热备搭建指南，主机备机部署与切换实操

定义框：双机热备是指用极狐GitLab Geo搭建一主一备两个站点，备站点实时复制主站点数据，主站点故障时可切换接管的部署架构。

先说清楚：极狐GitLab的"双机热备"长什么样

聊双机热备，很多人的第一反应是数据库层面的主从切换------备机平时待命，主机一挂VIP飘过去。极狐GitLab的方案逻辑类似，但载体是Geo组件：主站点持续把数据库、Git仓库、附件等资产复制到从站点，从站点保持一份随时可用的完整副本。需要切换时，按照灾难恢复文档执行提升操作，从站点一键转正为主站点。

有三条官方边界必须先讲明白，否则方案评审会上会被架住：

版本要求：Geo为极狐GitLab专业版及以上功能，私有化部署所有站点共用一份许可证；
版本一致：主、从站点必须运行相同的极狐GitLab版本，且站点间需通过特定端口互通；
环境对齐：主站点如果使用对象存储，从站点也必须使用对象存储；两站点时钟偏差超过1分钟，复制就会失败。

还有一条容易被忽略：官方文档明确写明自行编译安装不支持Geo，Linux软件包安装是推荐路径。

搭建前账：两台机器怎么分工

以最常见的两台单节点站点（1K参考架构）为例，主机与备机的分工如下：

维度	主站点	从站点（备机）
数据库角色	PostgreSQL读写	只读副本，流式复制
日常用途	承接全部读写流量	数据同步+可选就近读取
关键配置	`geo_primary_role`	`geo_secondary_role`
切换方式	故障时永久禁用	`gitlab-ctl geo promote`提升

开始动手前，逐项核对这份前置检查单：

两个站点均已按参考架构文档独立安装并可登录；
主站点持有专业版或旗舰版订阅；
两站点极狐GitLab版本严格一致；
从站点可访问主站点PostgreSQL的5432端口；
两站点时钟已通过NTP同步。

主站点配置：六步打底

以下命令均出自官方两个单节点站点设置Geo文档。

第一步，设置唯一的Geo站点名称并应用：

ruby 复制代码

# /etc/gitlab/gitlab.rb
gitlab_rails['geo_node_name'] = 'gitlab-primary'

shell 复制代码

gitlab-ctl reconfigure
gitlab-ctl set-geo-primary-node

第二步，为数据库用户和复制用户设置密码（先生成MD5哈希再写入配置）：

shell 复制代码

gitlab-ctl pg-password-md5 gitlab
gitlab-ctl pg-password-md5 gitlab_replicator

ruby 复制代码

postgresql['sql_user_password'] = '<gitlab用户md5哈希>'
postgresql['sql_replication_password'] = '<复制用户md5哈希>'
gitlab_rails['db_password'] = '<数据库明文密码>'

第三步，声明Geo主角色并开放网络监听：

ruby 复制代码

roles(['geo_primary_role'])
postgresql['listen_address'] = '<主站点IP>'
postgresql['md5_auth_cidr_addresses'] = ['<主站点IP>/32', '<从站点IP>/32']

第四步，临时关闭自动迁移后重启PostgreSQL，再恢复：

shell 复制代码

gitlab-ctl reconfigure
gitlab-ctl restart postgresql

第五步，确认PostgreSQL已监听5432端口，并取出复制证书：

shell 复制代码

netstat -plnt | grep 5432
cat ~gitlab-psql/data/server.crt

从站点配置：复制数据库是分水岭

备机这边的动作顺序很讲究，核心是一条命令：gitlab-ctl replicate-geo-database。它会删除从站点PostgreSQL上的全部现有数据，所以官方反复强调------从站点装好后先别往里灌任何数据。

按官方文档，从站点的落地步骤如下：

停止应用服务，验证到主站点数据库的网络连通性：

shell 复制代码

gitlab-ctl stop puma
gitlab-ctl stop sidekiq
gitlab-rake gitlab:tcp_check[<主站点IP>,5432]

安装主站点复制证书并测试数据库连接：

shell 复制代码

install -D -o gitlab-psql -g gitlab-psql -m 0400 -T server.crt ~gitlab-psql/.postgresql/root.crt

sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql \
    --list -U gitlab_replicator \
    -d "dbname=gitlabhq_production sslmode=verify-ca" \
    -W -h <主站点IP>

在gitlab.rb中声明从角色：

ruby 复制代码

roles(['geo_secondary_role'])
postgresql['listen_address'] = '<从站点IP>'
postgresql['sql_replication_password'] = '<复制用户md5哈希>'

执行复制（每个从站点的复制槽名称必须全局唯一）：

shell 复制代码

gitlab-ctl replicate-geo-database \
   --slot-name=secondary_one \
   --host=<主站点IP> \
   --sslmode=verify-ca

复制完成后还有两个必须手动做 的动作：把主站点的/etc/gitlab/gitlab-secrets.json复制到从站点（该文件不随Geo复制，涉及CI/CD变量与双因子认证的加解密），以及复制SSH主机密钥，否则用户通过SSH访问从站点时会收到主机密钥变更警告。

注册站点与切换实操

数据同步跑通后，在主站点UI的管理员 > Geo > 站点 > 添加站点 中登记从站点，注意名称必须与从站点的geo_node_name完全一致，外部URL必须与从站点external_url一致。随后在从站点执行验证：

shell 复制代码

gitlab-rake gitlab:geo:check

真正的切换（故障转移）同样有官方明确的三步流程：

永久禁用主站点 ，防止脑裂------有SSH权限就gitlab-ctl stop加systemctl disable gitlab-runsvdir，没有就改DNS、停虚拟机或防火墙阻断；
提升从站点 ------单节点执行sudo gitlab-ctl geo promote，提升前可用gitlab-ctl promotion-preflight-checks做最终校验；
清理跟踪数据库配置 ------注释gitlab.rb中的geo_secondary[]配置并gitlab-ctl reconfigure。

两条血泪边界也一并转述：提升启用了选择性同步的从站点，未复制的数据会永久丢失；原主站点提升后完全脱离Geo体系，想恢复只能作为新从站点重新接入。

FAQ

Q1：双机热备场景下，备站点平时能承担读流量吗？

可以。从站点提供完整的UI访问体验，未同步的读取会透明代理到主站点；也可通过统一URL配置地理路由，让就近团队自动接入。但写入始终在主站点，备站点数据库本身是只读的。

Q2：gitlab-secrets.json为什么必须手动复制？

该文件存放加密密钥，用于CI/CD变量、双因子认证等敏感数据的加解密。Geo不复制此文件，从站点与主站点密钥不一致时，故障转移后这些数据将无法解密。

Q3：切换后原主站点还能加回来吗？

可以，但不能直接复活。官方要求先确认旧主站点已彻底禁用，再按"将旧主站点恢复为从站点"的流程重新初始化，让它作为新从站点跟随当前主站点重新同步。

写在最后

双机热备不是装完就完事：时钟同步、版本对齐、secrets文件、切换演练，任何一环掉链子，真出事时备机就是一块昂贵的摆设。建议每季度做一次计划内故障转移演练，把切换流程变成肌肉记忆。

想评估Geo双机热备方案，或需要针对私有化环境的高可用架构咨询，可预约极狐GitLab专家演示，或前往官方文档中心查阅Geo完整章节。