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

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

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

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

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

1. 版本要求：Geo为极狐GitLab专业版及以上功能，私有化部署所有站点共用一份许可证；

2. 版本一致：主、从站点必须运行相同的极狐GitLab版本，且站点间需通过特定端口互通；

3. 环境对齐：主站点如果使用对象存储，从站点也必须使用对象存储；两站点时钟偏差超过1分钟，复制就会失败。

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

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

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

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

1. 两个站点均已按参考架构文档独立安装并可登录；

2. 主站点持有专业版或旗舰版订阅；

3. 两站点极狐GitLab版本严格一致；

4. 从站点可访问主站点PostgreSQL的5432端口；

5. 两站点时钟已通过NTP同步。

主站点配置：六步打底

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

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

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

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

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

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

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

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

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

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

gitlab-ctl reconfigure
gitlab-ctl restart postgresql

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

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

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

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

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

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

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

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

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>

1. 在gitlab.rb中声明从角色：

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

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

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一致。随后在从站点执行验证：

gitlab-rake gitlab:geo:check

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

1. 永久禁用主站点，防止脑裂——有SSH权限就gitlab-ctl stop加systemctl disable gitlab-runsvdir，没有就改DNS、停虚拟机或防火墙阻断；

2. 提升从站点——单节点执行sudo gitlab-ctl geo promote，提升前可用gitlab-ctl promotion-preflight-checks做最终校验；

3. 清理跟踪数据库配置——注释gitlab.rb中的geo_secondary[]配置并gitlab-ctl reconfigure。

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

FAQ

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

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

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

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

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

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

写在最后

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

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