极狐GitLab主备同步延迟治理，复制滞后监控与优化方法
极狐GitLab主备同步延迟治理，复制滞后监控与优化方法
定义框：主备同步延迟是指极狐GitLab Geo从站点落后主站点的数据时间差，涵盖数据库复制滞后与仓库、附件等数据类型的同步积压，直接决定灾备切换时的数据丢失风险。
延迟不可怕，看不见的延迟才可怕
搭完Geo双站点之后，很多团队就进入了"装完即安"的状态——主站点天天跑流水线，从站点安安静静地挂着。直到某次演练或者真故障切换，才发现备站点的数据停在几个小时前。这时候问题已经不是"同步延迟多少秒"，而是"这次切换要丢多少提交、多少附件"。
所以延迟治理的第一性原理很简单：先把延迟变成一个可测量的数字，再谈优化。极狐GitLab在这一点上给了三套互补的观测手段，覆盖从命令行到API到页面的完整链路，全部出自Geo监控官方文档。
三套监控手段：命令行、API、页面各管一段
观测手段 | 入口 | 核心输出 | 适用场景 |
|---|---|---|---|
Rake任务 |
| Database replication lag秒数+各数据类型同步/验证百分比 | 日常巡检、值班交接 |
状态API |
|
| 接入Prometheus等外部监控告警 |
管理页面 | 管理员 > Geo > 站点 | 站点健康状态、复制详情、验证进度 | 可视化核查、汇报截图 |
其中Rake任务的输出最直观，在从站点任何运行Rails进程（Puma、Sidekiq或Geo Log Cursor）的节点上执行：
sudo gitlab-rake gitlab:geo:status输出会列出站点角色、健康状态、GitLab版本，以及关键的Database replication lag，再往下是LFS Objects、MR Diffs、Uploads、Job Artifacts等每一种数据类型的 succeeded X / total Y (Z%) 复制与验证进度。一条命令就能判断"延迟是数据库层面的，还是某个数据类型积压了"。
如果要把延迟纳入企业级告警体系，Geo状态API返回的 db_replication_lag_seconds 字段是标准采集点：
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://primary.example.com/api/v4/geo_nodes/status"注意一点：这套 geo_nodes API已在极狐GitLab 16.0中弃用，官方建议迁移到Geo站点API，新接入监控时直接按新接口设计，避免二次返工。
延迟偏高怎么定位：拆开看三层
gitlab:geo:status 只告诉你延迟有多大，没告诉你延迟出在哪。官方故障排除文档给了一个非常实用的定位方法：到主站点数据库节点上把PostgreSQL的复制延迟拆成三段看。
gitlab-psql -xc 'SELECT write_lag,flush_lag,replay_lag FROM pg_stat_replication;'
-[ RECORD 1 ]---------------
write_lag | 00:00:00.072392
flush_lag | 00:00:00.108168
replay_lag | 00:00:00.108283三个值各对应复制链路的一段，偏高的那段就是病灶所在：
指标 | 含义 | 偏高说明什么 |
|---|---|---|
| WAL已由从站接收但未写入存储 | 主从之间网络性能下降或带宽不足 |
| WAL已发送到存储但未确认刷盘 | 从站磁盘I/O性能不达标 |
| WAL已持久化但未在数据库重放 | 存在长事务，或CPU等资源饱和 |
顺便记住两条衍生判据：write_lag 与 flush_lag 差距大，说明数据可能停在易失性写缓存里没真正落盘；flush_lag 与 replay_lag 差距大，说明数据落了盘但数据库重放不过来。
数据库层面之外，还有一条最容易炸的暗雷：非活跃复制槽。从站点断连后，主站点对应的复制槽会被标记为非活跃，WAL文件被无限保留——延迟会"看起来正常"，但主站点磁盘被慢慢吃光，PostgreSQL日志里反复出现 WARNING: oldest xmin is far in the past。官方的处理路径是先查槽状态：
-- 主站点执行：sudo gitlab-psql -d gitlabhq_production
SELECT * FROM pg_replication_slots;
-- active 为 f 的槽处于非活跃状态确认从站点无法重连后，删除非活跃槽并重新启动复制过程；对应报错 replication slot does not exist 时，需要重新运行复制过程重建槽位。这套流程在PostgreSQL复制故障排除文档里有完整步骤。
一份可落地的延迟治理巡检清单
把上面的内容压缩成值班可执行的五步，建议直接抄进运维手册：
从站点执行
sudo gitlab-rake gitlab:geo:status，记录Database replication lag与各数据类型同步百分比；db_replication_lag_seconds持续偏高时，到主站点执行SELECT write_lag,flush_lag,replay_lag FROM pg_stat_replication;定位网络、磁盘还是资源问题；从站点执行
sudo gitlab-rake gitlab:geo:check，确认Database replication working为yes、时钟同步正常；主站点检查
pg_replication_slots，发现非活跃槽立即按官方流程处理，防止WAL撑爆磁盘；通过
GET /geo_nodes/statusAPI把延迟接入外部告警，设置阈值（例如超过60秒告警），同时留意站点状态超过1小时未更新会被标记为不健康。
两个容易踩的坑顺带提一下：其一，gitlab:geo:status 输出中对象存储里的对象显示"未验证"属预期行为，官方文档明确说明对象存储对象不参与验证，别误判成故障；其二，指标收集作业依赖Redis独占租约，如果站点状态迟迟不更新，可在从站点Rails控制台执行 Geo::MetricsUpdateWorker.new.perform 手动触发并观察报错。
FAQ
Q1：Database replication lag 显示多少秒算正常？
官方没有设定统一的正常阈值，gitlab:geo:status 与API只负责如实报告数值。实践上应结合自身RPO目标设定告警线，并观察趋势：偶发抖动通常由大批量推送或backfill引起，持续偏高才需要按三层指标拆解定位。
Q2：仓库、附件的同步百分比落后于数据库延迟，是出问题了吗？
不一定是故障。数据库复制是流式的、近乎实时，而仓库和附件的同步由Geo后台进程按事件队列异步执行，受Sidekiq吞吐和网络带宽影响。若某类数据长期不追平，查看从站点的 gitlab-rails/geo.log 定位具体失败原因。
Q3：能否降低Geo指标收集频率来减轻数据库压力？
可以。官方提供 gitlab_rails['geo_metrics_update_worker_cron'] 配置项调整收集周期，但有一条硬边界：指标超过10分钟未更新，站点就会被标记为不健康，所以调整时不要越过这条线。官方还建议优先考虑减少复制的对象类型与数据量。
如果你的双站点还没有一套量化的延迟基线，建议先按本文清单跑一次全量巡检，把数字记下来。想动手搭Geo或需要架构评审支持，可以预约极狐GitLab专家演示，或前往极狐GitLab文档中心查阅Geo完整部署与运维手册，也可免费试用体验完整灾备能力。
