3. 自助目录架构设计：分层架构与组件交互

自助目录的可靠性并非单一组件能够承载，必须通过清晰的分层架构来隔离关注点、定义交互契约、控制故障爆炸半径。本章将详细拆解 Catalog 层、编排层、基础设施层的职责边界与核心交互流程，并给出组件级关系图。

3.1 三层架构总览

自助目录采用严格的三层纵向切分，每一层只依赖下层提供的稳定接口，禁止跨层直接调用。三层定义如下：

3.2 分层交互关系与核心流程

下图展示了三层之间的组件交互关系，以及一次完整的自助部署请求在层间的流转路径。

3.3 组件交互详细说明

3.3.1 Catalog 层内部交互

• Git 模板仓库 存储所有经过评审的 Helm/Kustomize 模板，每个模板包含 catalog.yaml 元数据文件。
• 索引器 定期扫描 Git 仓库，解析 catalog.yaml 并构建全文索引，写入 Catalog API 的缓存层。
• Catalog API 对外提供 RESTful 接口：GET /catalog/templates、GET /catalog/templates/{name}/versions。
• Web UI 通过 Catalog API 展示模板列表、版本差异、参数表单，用户在此选择模板并填写参数。

3.3.2 编排层核心流程

1. Pipeline Engine 接收 Web UI 提交的部署请求，包含模板名称、版本、参数键值对。
2. Policy Engine 对参数进行校验：命名规范、资源配额上限、标签合规、安全策略（如禁止 privileged: true）。
3. 校验通过后，Application Generator 根据模板和参数渲染出 Argo CD Application YAML，并写入 GitOps 仓库的指定路径。
4. 若策略要求人工审批，则触发 审批 流程，审批通过后才执行写入操作。

3.3.3 基础设施层职责

3.4 分层架构的可靠性收益

分层架构带来的可靠性收益可归纳为以下四点：

• 故障隔离：任意一层崩溃不会导致全局不可用，其他层仍可提供降级服务。
• 独立扩缩：Catalog 层可水平扩展索引节点，编排层可增加 Pipeline Worker，基础设施层可添加 Argo CD 实例，互不干扰。
• 契约测试：层间通过 API 契约交互，可对每一层单独编写集成测试和混沌工程实验。
• 版本演进：升级 Catalog API 时无需修改编排层代码，只要保持接口兼容即可。

3.5 典型部署请求的层间时序

以下时序图展示一次完整的自助部署请求如何穿越三层：

3.6 分层架构的契约定义示例

层间通信必须基于明确的 API 契约。以下展示编排层调用 Catalog API 获取模板版本的契约示例：

# 请求：GET /catalog/templates/nginx-ingress/versions/v1.2.0
# 响应：
{
  "template": "nginx-ingress",
  "version": "v1.2.0",
  "schema": {
    "type": "object",
    "properties": {
      "replicas": {
        "type": "integer",
        "minimum": 1,
        "maximum": 10,
        "default": 3
      },
      "ingressClass": {
        "type": "string",
        "enum": ["nginx", "traefik", "istio"],
        "default": "nginx"
      },
      "tlsEnabled": {
        "type": "boolean",
        "default": true
      }
    },
    "required": ["replicas", "ingressClass"]
  },
  "policies": {
    "maxReplicasPerNamespace": 5,
    "requiredLabels": ["app.kubernetes.io/name", "app.kubernetes.io/instance"]
  }
}