4. GitLab实例部署与拓扑治理

GitLab 的部署拓扑不是“装完能用”就结束的工程问题，而是决定后续可用性、扩展性、升级窗口和故障半径的治理起点。选错拓扑，后期往往不是加机器就能补救，而是需要停机迁移、数据搬迁甚至重建 CI Runner 信任链。因此本节先建立拓扑选型的判断框架，再落到部署标准、环境隔离与配置基线管理。

一、四种主流拓扑的适用边界

GitLab 官方支持的部署形态大致可归为四类：单节点 Omnibus、多节点横向拆分、Geo 多地域、Kubernetes（Helm Chart）部署。它们的核心差异在于“哪些组件被拆开、数据如何复制、故障域如何划分”。

• 单节点 Omnibus：所有组件（Puma、Sidekiq、PostgreSQL、Redis、Gitaly、Nginx）装在一台机器。适合 500 人以下、日活并发不高的团队，运维成本最低，但升级必须整体停机，且单机故障即全站不可用。
• 多节点拆分：把数据库、Redis、Gitaly、应用层分别部署到独立节点，通过 PostgreSQL 流复制、Redis Sentinel、Gitaly Cluster（Praefect）实现高可用。适合 1000 人以上、对可用性有 SLA 要求的企业。
• Geo 多地域：在主节点之外部署只读从节点，通过 Geo 复制 Git 仓库、数据库和对象存储，实现异地容灾与就近读取。注意 Geo 的从节点默认只读，写入仍回主站。
• Kubernetes 部署：用 Helm Chart 把 GitLab 组件容器化，借助 K8s 的调度、探针和 HPA 实现弹性伸缩。适合已有成熟 K8s 平台、追求基础设施即代码的团队，但状态组件（PostgreSQL、Redis、Gitaly）仍建议外置或使用 Operator 管理。

选型时建议按三个问题排序：可用性目标（能否接受小时级停机）、数据规模（仓库总量与并发克隆量）、团队运维能力（是否有专职 SRE）。若三者都低，单节点是理性选择；若可用性要求高但团队小，优先多节点而非 Geo，因为 Geo 的运维复杂度显著更高。

二、部署标准：从“能跑”到“可治理”

无论选哪种拓扑，部署标准应统一收敛到四条硬性要求。第一，版本锁定：生产环境必须固定 GitLab 小版本（如 16.11.3），禁止使用 latest 标签，升级走“测试环境验证 → 灰度 → 生产”的路径。第二，外部依赖显式声明：PostgreSQL、Redis、对象存储的连接参数写入 gitlab.rb 或 Helm values，不依赖默认内嵌实例。第三，备份可验证：每日执行 gitlab-backup create，并每周在隔离环境做一次恢复演练，只备份不恢复等于没有备份。第四，监控覆盖：至少采集 Puma 请求延迟、Sidekiq 队列积压、PostgreSQL 复制延迟、Gitaly 磁盘水位四类指标。

以单节点 Omnibus 为例，关键配置基线片段如下：

external_url 'https://gitlab.example.com'
postgresql['enable'] = false
gitlab_rails['db_host'] = '10.20.1.11'
gitlab_rails['db_port'] = 5432
redis['enable'] = false
gitlab_rails['redis_host'] = '10.20.1.12'
gitlab_rails['redis_port'] = 6379
gitlab_rails['backup_keep_time'] = 604800
nginx['redirect_http_to_https'] = true

执行 gitlab-ctl reconfigure 后，用 gitlab-rake gitlab:check 验证组件连通性，再访问 /help 页面确认版本与组件状态。若 gitlab:check 报数据库连接失败，优先检查 pg_hba.conf 是否放行应用节点网段，而不是反复重装。

三、环境隔离与配置基线管理

环境隔离的核心是“同一份配置模板，不同环境只替换变量”。建议至少划分四套环境：开发（dev）用于功能验证，测试（test）用于升级预演，预生产（staging）与生产同拓扑但数据脱敏，生产（prod）只接受经过验证的变更。四套环境使用同一 GitLab 版本、同一 Helm Chart 版本、同一配置模板，差异仅体现在域名、数据库地址、副本数等变量上。

配置基线管理推荐把 gitlab.rb 或 Helm values 纳入 Git 仓库，采用“基线文件 + 环境覆盖文件”的结构：base.rb 存放所有环境共用的参数，prod.rb 只写生产差异项。变更通过 Merge Request 评审，合并后由 CI 流水线自动执行 gitlab-ctl reconfigure 或 helm upgrade。这样每一次配置变更都有提交记录、评审人和回滚点，避免“某台机器被手工改过”的漂移问题。

最后，拓扑治理不是一次性决策。建议每季度复核一次：当前并发克隆量是否接近 Gitaly 磁盘 IO 上限、PostgreSQL 复制延迟是否稳定、备份恢复演练是否通过。当单节点 CPU 持续高于 70% 或仓库总量超过 500GB 时，就应启动多节点拆分评估，而不是等到故障发生再被动扩容。