2. 服务目录基础：服务目录的组成要素与目录结构设计原则

服务目录（Service Catalog）是 CI/CD 跨环境同步的核心数据模型。它定义了“哪个服务的哪个版本，在哪个环境中，使用什么配置运行”。本章将拆解服务目录的四个组成要素，并给出目录结构的设计原则，确保目录在跨环境同步时具备可追溯性、可复用性和不可变一致性。

2.1 服务目录的四个组成要素

一个标准化的服务目录条目由以下四个要素构成，缺一不可：

2.2 目录结构设计原则

服务目录的物理存储结构直接影响同步脚本的复杂度和可维护性。以下四条原则是经过生产验证的最佳实践：

• 原则一：按环境分层 —— 顶层目录按环境名称划分，每个环境内部再按服务名组织。避免将所有环境的配置混放在同一层级。
• 原则二：版本与配置分离 —— 版本信息存放在独立的版本清单文件中，配置则按服务/环境拆分到单独的文件或目录。版本升级时只需修改版本清单，无需改动配置目录。
• 原则三：配置继承与覆盖 —— 建立“基础配置 → 环境覆盖”的层级结构。公共配置放在 base/ 目录，各环境只存放差异部分，减少重复。
• 原则四：不可变历史 —— 每次同步操作生成一个带时间戳或版本号的快照目录，保留历史记录，支持回滚和审计。

service-catalog/
├── base/                          # 公共基础配置
│   └── order-service/
│       └── config.yaml
├── dev/
│   ├── versions.yaml              # 版本清单
│   └── order-service/
│       └── config-override.yaml
├── staging/
│   ├── versions.yaml
│   └── order-service/
│       └── config-override.yaml
├── prod/
│   ├── versions.yaml
│   └── order-service/
│       └── config-override.yaml
└── snapshots/                     # 历史快照
    └── 2025-03-21T10-30-00Z/
        ├── dev/...
        ├── staging/...
        └── prod/...

2.3 服务目录组成要素关系图

下图展示了四个要素之间的关联关系，以及它们在跨环境同步中的流转路径：

2.4 目录结构设计对比

不同的目录结构设计会直接影响同步脚本的复杂度和可维护性。下表对比了三种常见方案的优劣：

2.5 配置继承与覆盖机制

为了减少重复配置，服务目录支持“基础配置 + 环境覆盖”的合并策略。以下是一个典型的配置合并流程：

1. 加载基础配置：从 base/<service>/config.yaml 读取公共参数。
2. 加载环境覆盖：从 <env>/<service>/config-override.yaml 读取环境专属参数。
3. 深度合并：环境覆盖中的键值对递归覆盖基础配置中的同名键。数组类型默认替换而非追加。
4. 变量插值：支持 ${ENV_VAR} 或 {{ .Values.key }} 形式的占位符，在同步时由 CI/CD 系统注入实际值。

# base/order-service/config.yaml
database:
  host: localhost
  port: 5432
  pool_size: 10
feature_flags:
  new_checkout: false

# staging/order-service/config-override.yaml
database:
  host: staging-db.internal
  pool_size: 20
feature_flags:
  new_checkout: true

# 合并结果（staging 环境）
database:
  host: staging-db.internal    # 覆盖
  port: 5432                    # 继承
  pool_size: 20                 # 覆盖
feature_flags:
  new_checkout: true            # 覆盖

2.6 服务目录的版本化与快照

每次跨环境同步操作都应生成一个不可变的快照，记录同步时刻的完整目录状态。快照结构如下：

snapshots/
└── 2025-03-21T10-30-00Z/          # 同步时间戳（UTC ISO 8601）
    ├── manifest.yaml               # 本次同步的元数据（源环境、目标环境、操作人、触发流水线ID）
    ├── dev/
    │   ├── versions.yaml           # 冻结的版本清单
    │   └── order-service/
    │       └── config.yaml         # 合并后的最终配置
    ├── staging/
    │   └── ...
    └── prod/
        └── ...