GitLab 企业最佳实践

本章汇总生产环境 GitLab 平台的治理规范，供平台团队制定内部标准时参考。

1. GitLab部署规范

1.1 硬件与架构

规模	用户/项目	CPU	内存	磁盘
小型	< 100 用户	8C	16 GB	500 GB SSD
中型	100–500	16C	32 GB	1 TB SSD
大型	> 500	32C+	64 GB+	Gitaly 独立 + SSD

生产环境禁止将 PostgreSQL、Redis、Gitaly 与 Omnibus 混部在资源 < 8C/16G 的虚拟机
git-data 必须使用 SSD，IOPS 低于 3000 的 HDD 不适合 > 50 用户
时区统一 UTC，NTP 同步：timedatectl status

1.2 部署清单

# /etc/gitlab/gitlab.rb 生产基线片段
external_url 'https://gitlab.example.com'
gitlab_rails['time_zone'] = 'Asia/Shanghai'
gitlab_rails['backup_keep_time'] = 604800  # 7 天
postgresql['shared_buffers'] = "256MB"
puma['worker_processes'] = 4
sidekiq['max_concurrency'] = 25
prometheus['enable'] = true
gitlab_rails['gitlab_email_enabled'] = true

/etc/gitlab/gitlab.rb 纳入 Git 版本管理
安装后立即修改 root 密码并创建独立 Admin 账号
关闭公开注册，接入 LDAP/OAuth

2. 项目管理规范

2.1 命名与结构

group:     team-platform, team-backend, team-mobile
project:   team-backend/order-service
branch:    main (protected), feature/<ticket>-<desc>, release/<version>
tag:       v1.2.3 (semver)

每个微服务独立项目，禁止「大杂烩」仓库
默认分支 main，Protected + 禁止 force push
Merge Request 必须至少 1 人 Review（Critical 项目 2 人）

2.2 分支保护

Project → Settings → Repository → Protected branches：

分支	Allowed to merge	Allowed to push	Force push
main	Maintainers	No one	禁止
release/*	Maintainers	Maintainers	禁止

3. 权限管理规范

角色	组级	项目级	说明
开发	Developer	Developer	日常开发
Tech Lead	Maintainer	Maintainer	合并 MR、管理分支
平台 SRE	Owner（平台组）	Maintainer	不介入业务代码
CI 机器人	—	Reporter + Token	只读 + API

禁止共享个人账号；自动化一律用 Project Access Token
离职当天 Block 账号，7 天后删除
每季度审计 Admin 列表与 Group Owner

4. Runner管理规范

生产 Runner 与 开发 Runner 物理或 K8s 命名空间隔离
生产 Runner 设为 Protected，仅 protected 分支/tag 可用
禁用 Shell executor；Docker/K8s executor 禁止 privileged: true（DinD 除外且需审批）
Runner 镜像只允许来自内部 Harbor
单 Runner concurrent 不超过 CPU 核数 × 2

[[runners]]
  name = "prod-k8s-runner"
  executor = "kubernetes"
  [runners.kubernetes]
    namespace = "gitlab-runner-prod"
    cpu_limit = "2"
    memory_limit = "4Gi"
  tag_list = ["prod", "k8s"]
  run_untagged = false
  protected = true

5. CI/CD规范

5.1 流水线设计原则

快速反馈：lint/unit test 阶段 < 5 分钟
安全门禁：SAST、依赖扫描、容器扫描纳入 MR pipeline
不可变制品：构建一次，多环境 promote（同 digest 部署）
密钥不入库：敏感值放 CI Variables 或 Vault

5.2 标准阶段

stages:
  - validate    # lint, unit test
  - build       # 编译/镜像构建
  - scan        # SAST, container scan
  - deploy      # dev → staging → prod (manual)

main 分支 pipeline 失败禁止自动部署生产
生产 deploy job 必须 when: manual
Cache key 包含 lock 文件 hash，避免脏缓存

6. 备份规范

项	要求
频率	全量每日 1 次；大型实例可增量 + 周全量
保留	本地 7 天；异地 30 天
范围	tar + `gitlab-secrets.json` + `gitlab.rb`
演练	每季度恢复演练，RTO < 4h，RPO < 24h
监控	备份失败 1 小时内告警

# /etc/cron.d/gitlab-backup
0 2 * * * git gitlab-backup create CRON=1 SKIP=registry,artifacts 2>&1 | logger -t gitlab-backup
15 2 * * * root cp /etc/gitlab/gitlab-secrets.json /backup/secrets/gitlab-secrets-$(date +\%F).json

对象存储（uploads/artifacts/LFS）启用跨区域复制，不能仅依赖本地 tar。

7. 升级规范

7.1 升级路径

必须按官方升级路径逐步升级，不可跨多个 major
先升级至当前 major 最新 patch，再升下一 major
只升级 Stable 渠道

7.2 升级 SOP

阅读 Release Notes 与 Breaking Changes
全量备份 + secrets 备份
预发环境同版本验证
维护窗口：gitlab-ctl deploy-page up
执行升级包安装 + gitlab-ctl reconfigure
运行 gitlab-rake gitlab:check 和 smoke test
关闭维护页，观察 24h 监控

回滚：恢复备份 tar + 降级安装包（版本须匹配），不可仅降级包不恢复 DB。

8. 生产环境Checklist

上线前逐项确认：

基础设施

硬件/VM 规格满足容量规划（含 30% 余量）
SSD 挂载 /var/opt/gitlab，独立数据盘
NTP 同步、时区正确
防火墙仅开放 443（Web）、2222（SSH 若自定义）、Prometheus 仅内网

安全

可靠性

每日备份 cron + 失败告警
季度恢复演练记录
Prometheus + Grafana + 告警规则上线
HA 组件（若启用）failover 测试通过

治理

组/项目命名规范文档发布
MR/Review 策略配置
分支保护规则就位
平台 On-call 与升级窗口流程定义
gitlab.rb 纳入配置管理 Git

完成以上清单后，平台方可对外宣告 GitLab 生产就绪（Production Ready）。

1. GitLab部署规范​

1.1 硬件与架构​

1.2 部署清单​

2. 项目管理规范​

2.1 命名与结构​

2.2 分支保护​

3. 权限管理规范​

4. Runner管理规范​

5. CI/CD规范​

5.1 流水线设计原则​

5.2 标准阶段​

6. 备份规范​

7. 升级规范​

7.1 升级路径​

7.2 升级 SOP​

8. 生产环境Checklist​

基础设施​

安全​

可靠性​

治理​