4. Git仓库结构设计：monorepo vs 多repo策略

在管理可观测性平台配置时，Git仓库结构的选择直接影响团队协作效率、CI/CD流水线复杂度以及配置的可发现性。可观测性平台通常包含Prometheus规则、Grafana仪表盘、Alertmanager配置、Loki日志规则、Tempo追踪采样策略等多个组件，每个组件又有开发、测试、生产等多套环境。合理的仓库结构是Argo CD实现“Git作为单一事实来源”的基础。

4.1 Monorepo vs 多Repo：核心对比

4.2 目录结构最佳实践

无论选择哪种仓库策略，目录结构都应遵循Kubernetes原生配置管理的最佳模式。以下推荐结构适用于Monorepo场景，多Repo场景可截取其中对应组件目录独立使用。

4.2.1 基于Kustomize的base/overlays结构

observability-config/
├── base/                          # 公共基础配置
│   ├── prometheus/
│   │   ├── kustomization.yaml
│   │   ├── prometheus.yaml        # Prometheus CR
│   │   ├── service.yaml
│   │   ├── serviceaccount.yaml
│   │   └── rules/                 # 告警规则
│   │       ├── kubernetes-alerts.yaml
│   │       └── node-exporter-alerts.yaml
│   ├── grafana/
│   │   ├── kustomization.yaml
│   │   ├── grafana.yaml           # Grafana CR / Deployment
│   │   ├── datasources/           # 数据源配置
│   │   │   └── prometheus-datasource.yaml
│   │   └── dashboards/            # 仪表盘JSON
│   │       ├── kubernetes-cluster.json
│   │       └── node-exporter.json
│   └── alertmanager/
│       ├── kustomization.yaml
│       ├── alertmanager.yaml
│       └── config/                # 告警路由与接收器
│           └── alertmanager-config.yaml
├── overlays/                      # 环境覆盖
│   ├── dev/
│   │   ├── kustomization.yaml
│   │   ├── prometheus-patch.yaml
│   │   └── grafana-ingress.yaml
│   ├── staging/
│   │   ├── kustomization.yaml
│   │   ├── prometheus-replicas.yaml
│   │   └── alertmanager-receivers.yaml
│   └── production/
│       ├── kustomization.yaml
│       ├── prometheus-ha.yaml
│       ├── grafana-resources.yaml
│       └── alertmanager-pagerduty.yaml
├── charts/                        # Helm Charts（可选）
│   ├── prometheus-stack/
│   │   ├── Chart.yaml
│   │   ├── values/
│   │   │   ├── dev.yaml
│   │   │   ├── staging.yaml
│   │   │   └── production.yaml
│   │   └── templates/
│   └── loki-stack/
│       ├── Chart.yaml
│       └── values/
├── values/                        # 纯Values文件（非Helm场景）
│   ├── prometheus-common.yaml
│   ├── grafana-common.yaml
│   └── alertmanager-common.yaml
├── apps/                          # Argo CD Application定义
│   ├── prometheus-app.yaml
│   ├── grafana-app.yaml
│   └── alertmanager-app.yaml
└── .argocd-source.yaml            # Argo CD Source配置（可选）

4.2.2 目录结构决策矩阵

4.3 分支策略

分支策略需要与目录结构、环境数量、发布节奏相匹配。可观测性配置的变更频率通常低于应用代码，但变更影响面更大（一个错误的告警规则可能导致告警风暴）。

4.3.1 推荐分支模型：Trunk-Based + 环境分支

4.3.2 分支操作流程

1. 开发阶段：从 main 创建特性分支（feature/add-cpu-alert），修改 base/prometheus/rules/ 下的告警规则文件
2. PR审查：提交PR到 main，触发CI流水线：语法校验 → 规则单元测试 → 模拟告警渲染 → 安全扫描
3. 合并到main：PR通过后 squash merge 到 main，自动触发环境分支更新
4. 环境提升：
   • 合并 main → release/dev：Argo CD自动同步到开发环境
   • 验证通过后，合并 release/dev → release/staging：同步到预发布环境
   • 预发布验证通过后，合并 release/staging → release/production：同步到生产环境
5. 紧急修复：从 main 创建 hotfix/critical-alert 分支，修复后直接合并到 main 并 cherry-pick 到 release/production

4.4 Monorepo与多Repo的混合实践

在实际工程中，纯粹的Monorepo或多Repo都难以完美适配所有场景。以下混合策略经过多个生产环境验证：

4.5 目录结构决策流程

选择仓库结构和目录布局时，可按以下决策树快速判断：

1. 团队规模与分工：单团队（≤10人）→ Monorepo；多团队 → 考虑多Repo或混合策略
2. 配置耦合度：Prometheus规则与Grafana面板强耦合 → 放入同一仓库；Loki配置与Prometheus弱耦合 → 可独立仓库
3. 变更频率：告警规则每周变更 → Monorepo方便原子提交；Grafana仪表盘每月变更 → 可独立管理
4. 环境数量：3个以下环境 → base/overlays结构足够；5个以上环境 → 考虑Helm + values分层
5. 合规要求：生产环境需要独立审批 → 使用环境分支 + PR gate；开发环境快速迭代 → 直接合并到main